MCP 协议实战：让 AI 助手真正读懂你的代码仓库

什么是 MCP？

Model Context Protocol（MCP）是 Anthropic 在 2024 年底推出的开放协议，目的是让 AI 模型能够安全、标准化地访问外部数据源和工具。你可以把它理解为 AI 世界的 USB 接口——不管什么设备，插上就能用。

为什么需要 MCP？

在没有 MCP 之前，让 AI 助手访问你的代码仓库、数据库或 API，需要为每个 AI 平台写一套定制集成。一个工具要对接 ChatGPT、Claude、Gemini，就要写三套不同的 plugin。MCP 统一了这个接口，一次实现到处可用。

核心架构

MCP 采用经典的客户端-服务器架构：

AI 应用（Host）
  └── MCP Client
        └── MCP Server（你的工具/数据）

• Host：AI 应用本身，比如 Claude Desktop、Cursor、VS Code
• Client：维持与 Server 的 1:1 连接
• Server：暴露 Resources（数据）、Tools（操作）和 Prompts（模板）

实战：搭建一个代码仓库 MCP Server

下面用 TypeScript 写一个简单的 MCP Server，让 AI 可以浏览和搜索你的代码。

1. 初始化项目

mkdir my-repo-mcp && cd my-repo-mcp
npm init -y
npm install @modelcontextprotocol/sdk zod

2. 实现 Server

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import { execSync } from "child_process";
import fs from "fs";

const server = new McpServer({
  name: "repo-browser",
  version: "1.0.0"
});

// 工具：列出目录文件
server.tool("list_files", { path: z.string().default(".") }, async ({ path }) => {
  const files = fs.readdirSync(path, { withFileTypes: true });
  const result = files.map(f => 
    `${f.isDirectory() ? "📁" : "📄"} ${f.name}`
  ).join("\n");
  return { content: [{ type: "text", text: result }] };
});

// 工具：搜索代码
server.tool("search_code", { query: z.string() }, async ({ query }) => {
  try {
    const result = execSync(
      `grep -rn "${query}" --include="*.ts" --include="*.js" . | head -20`,
      { encoding: "utf-8", timeout: 5000 }
    );
    return { content: [{ type: "text", text: result || "没有找到匹配" }] };
  } catch {
    return { content: [{ type: "text", text: "搜索无结果" }] };
  }
});

// 工具：读取文件
server.tool("read_file", { path: z.string() }, async ({ path }) => {
  const content = fs.readFileSync(path, "utf-8");
  return { content: [{ type: "text", text: content.slice(0, 10000) }] };
});

const transport = new StdioServerTransport();
await server.connect(transport);

3. 配置到 Claude Desktop

在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "my-repo": {
      "command": "npx",
      "args": ["tsx", "/path/to/my-repo-mcp/index.ts"],
      "env": { "REPO_PATH": "/your/project" }
    }
  }
}

配置完成后重启 Claude Desktop，你就能在对话中直接让 AI 浏览你的代码、搜索函数定义、阅读特定文件了。

进阶玩法

• Git 集成：添加 git_log、git_diff 工具，让 AI 理解代码变更历史
• 资源暴露：把项目的 README、架构文档作为 Resource 暴露，AI 自动获取上下文
• Prompt 模板：预设 code review、bug 分析等 prompt 模板

安全注意事项

1. MCP Server 跑在本地，数据不会直接上传到云端
2. 用 Zod 做输入校验，防止路径穿越攻击
3. 限制文件读取范围，不要暴露敏感配置
4. 生产环境建议用 SSE 传输替代 stdio，支持认证

总结

MCP 正在成为 AI 工具生态的标准协议。掌握 MCP 开发，意味着你写的工具可以被所有支持 MCP 的 AI 应用直接调用。这不仅仅是一个技术标准——它代表了 AI 从「对话」走向「行动」的关键一步。

如果你正在做 AI 相关的开发，强烈建议现在就开始学习 MCP，因为它的生态正在爆发式增长。