Claude Code MCP Server 探索工具技术分析报告

> 研究对象: yasasbanukaofficial/claude-code 和 TaGoat/claude_code_cli > 发布包: claude-code-explorer-mcp (npm) > 分析日期: 2026-04-02

---

目录

1. 概述 2. MCP Server 架构设计 3. 工具发现与调用机制 4. 代码库交互方式 5. MCP 协议实现细节 6. 可复用的设计模式 7. 总结

---

1. 概述

Claude Code MCP Server 是一个专门用于探索 Claude Code 源代码的 Model Context Protocol (MCP) 服务器实现。它允许任何 MCP 兼容的客户端（Claude Code、Claude Desktop、VS Code Copilot、Cursor）以交互方式浏览庞大的代码库。

1.1 基本统计

1.2 核心功能

• 工具列表: 列出 40+ 个 Agent 工具（BashTool、FileEditTool 等）
• 命令列表: 列出 50+ 个斜杠命令（/commit、/review 等）
• 源码读取: 读取任意工具或命令的完整实现
• 代码搜索: 跨整个源码树的正则搜索
• 目录浏览: 浏览 src/ 下的任意目录
• 架构概览: 获取高级架构信息

2. MCP Server 架构设计

2.1 整体架构

┌─────────────────────────────────────────────────────────────────┐
│                    MCP Client (Claude/Cursor/VS Code)           │
└───────────────────────────┬─────────────────────────────────────┘
                            │ STDIO / HTTP
┌───────────────────────────▼─────────────────────────────────────┐
│                  Claude Code Explorer MCP Server                │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │   Tools     │  │  Resources  │  │   Prompts   │             │
│  │  (8 tools)  │  │  (3+1 res)  │  │  (5 prompts)│             │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘             │
│         │                │                │                     │
│         └────────────────┼────────────────┘                     │
│                          ▼                                     │
│              ┌─────────────────────┐                           │
│              │   File System API   │                           │
│              │  (fs/promises)      │                           │
│              └──────────┬──────────┘                           │
│                         │                                      │
└─────────────────────────┼──────────────────────────────────────┘
                          │
              ┌───────────▼───────────┐
              │   SRC_ROOT Directory  │
              │  (Claude Code src/)   │
              └───────────────────────┘

2.2 代码结构

mcp-server/
├── src/
│   ├── index.ts          # STDIO 入口点
│   ├── server.ts         # 核心服务器实现（transport-agnostic）
│   └── http.ts           # HTTP 入口点（可选）
├── package.json
└── tsconfig.json

2.3 核心设计原则

1. Transport 无关性: 服务器逻辑与传输层分离，支持 STDIO 和 HTTP 2. 路径安全: 通过 safePath() 函数阻止路径遍历攻击 3. 模块化设计: 工具、资源、提示各自独立注册 4. 配置灵活性: 通过环境变量 CLAUDE_CODE_SRC_ROOT 配置源码路径

---

3. 工具发现与调用机制

3.1 工具注册流程

// 服务器初始化时注册所有工具
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "list_tools",
      description: "List all Claude Code agent tools...",
      inputSchema: { type: "object", properties: {} }
    },
    // ... 更多工具
  ]
}));

// 处理工具调用
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;
  switch (name) {
    case "list_tools": { /* 实现 */ }
    case "search_source": { /* 实现 */ }
    // ...
  }
});

3.2 工具清单

3.3 工具调用示例

// 搜索源码示例
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === "search_source") {
    const { pattern, filePattern, maxResults = 50 } = request.params.arguments;
    
    // 编译正则
    const regex = new RegExp(pattern, "i");
    
    // 遍历所有文件
    const allFiles = await walkFiles(SRC_ROOT);
    const matches = [];
    
    for (const file of allFiles) {
      if (matches.length >= maxResults) break;
      const content = await fs.readFile(path.join(SRC_ROOT, file), "utf-8");
      const lines = content.split("\n");
      
      for (let i = 0; i < lines.length; i++) {
        if (regex.test(lines[i])) {
          matches.push(`${file}:${i + 1}: ${lines[i].trim()}`);
        }
      }
    }
    
    return {
      content: [{ type: "text", text: matches.join("\n") }]
    };
  }
});

---

4. 代码库交互方式

4.1 目录遍历工具

// 递归遍历文件树
async function walkFiles(root: string, rel = ""): Promise<string[]> {
  const results: string[] = [];
  const entries = await fs.readdir(path.join(root, rel), { withFileTypes: true });
  
  for (const e of entries) {
    const child = rel ? `${rel}/${e.name}` : e.name;
    if (e.isDirectory()) {
      results.push(...(await walkFiles(root, child)));
    } else {
      results.push(child);
    }
  }
  return results;
}

4.2 工具发现机制

// 扫描 tools/ 目录发现所有工具
async function getToolList(): Promise<ToolInfo[]> {
  const toolsDir = path.join(SRC_ROOT, "tools");
  const entries = await fs.readdir(toolsDir, { withFileTypes: true });
  const tools: ToolInfo[] = [];
  
  for (const e of entries) {
    // 排除 shared 和 testing 目录
    if (!e.isDirectory() || e.name === "shared" || e.name === "testing")
      continue;
    
    const files = await listDir(path.join(toolsDir, e.name));
    tools.push({ 
      name: e.name, 
      directory: `tools/${e.name}`, 
      files 
    });
  }
  return tools.sort((a, b) => a.name.localeCompare(b.name));
}

4.3 命令发现机制

// 扫描 commands/ 目录发现所有命令
async function getCommandList(): Promise<CommandInfo[]> {
  const cmdsDir = path.join(SRC_ROOT, "commands");
  const entries = await fs.readdir(cmdsDir, { withFileTypes: true });
  const commands: CommandInfo[] = [];
  
  for (const e of entries) {
    if (e.isDirectory()) {
      const files = await listDir(path.join(cmdsDir, e.name));
      commands.push({
        name: e.name,
        path: `commands/${e.name}`,
        isDirectory: true,
        files,
      });
    } else {
      commands.push({
        name: e.name.replace(/\.(ts|tsx)$/, ""),
        path: `commands/${e.name}`,
        isDirectory: false,
      });
    }
  }
  return commands.sort((a, b) => a.name.localeCompare(b.name));
}

4.4 安全路径处理

/** 安全地解析用户提供的相对路径，阻止路径遍历攻击 */
function safePath(relPath: string): string | null {
  const resolved = path.resolve(SRC_ROOT, relPath);
  if (!resolved.startsWith(SRC_ROOT)) return null;
  return resolved;
}

---

5. MCP 协议实现细节

5.1 协议架构

MCP (Model Context Protocol) 是一个开放标准，允许 AI Agent 发现和使用外部工具。

┌─────────────────────────────────────────────────────────────┐
│                        MCP Protocol                          │
├─────────────────────────────────────────────────────────────┤
│  Transport Layer: STDIO / HTTP / WebSocket                   │
├─────────────────────────────────────────────────────────────┤
│  Message Format: JSON-RPC 2.0                                │
├─────────────────────────────────────────────────────────────┤
│  Core Capabilities:                                          │
│    - Tools (工具调用)                                        │
│    - Resources (资源读取)                                    │
│    - Prompts (提示模板)                                      │
└─────────────────────────────────────────────────────────────┘

5.2 Server 初始化

import { Server } from "@modelcontextprotocol/sdk/server/index.js";

const server = new Server(
  { 
    name: "claude-code-explorer", 
    version: "1.1.0" 
  },
  {
    capabilities: {
      tools: {},      // 支持工具调用
      resources: {},  // 支持资源读取
      prompts: {},    // 支持提示模板
    },
  }
);

5.3 资源定义

// 静态资源列表
server.setRequestHandler(ListResourcesRequestSchema, async () => ({
  resources: [
    {
      uri: "claude-code://architecture",
      name: "Architecture Overview",
      description: "High-level overview...",
      mimeType: "text/markdown",
    },
    {
      uri: "claude-code://tools",
      name: "Tool Registry",
      description: "List of all agent tools",
      mimeType: "application/json",
    },
    {
      uri: "claude-code://commands",
      name: "Command Registry",
      description: "List of all slash commands",
      mimeType: "application/json",
    },
  ],
}));

// 资源模板（动态资源）
server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => ({
  resourceTemplates: [
    {
      uriTemplate: "claude-code://source/{path}",
      name: "Source file",
      description: "Read a source file...",
      mimeType: "text/plain",
    },
  ],
}));

5.4 提示模板定义

server.setRequestHandler(ListPromptsRequestSchema, async () => ({
  prompts: [
    {
      name: "explain_tool",
      description: "Explain how a specific tool works...",
      arguments: [
        {
          name: "toolName",
          description: "Tool directory name, e.g. 'BashTool'",
          required: true,
        },
      ],
    },
    {
      name: "architecture_overview",
      description: "Get a guided tour of the architecture",
    },
  ],
}));

// 提示模板内容生成
server.setRequestHandler(GetPromptRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;
  
  if (name === "explain_tool") {
    const toolName = args?.toolName;
    // 读取工具源码...
    return {
      description: `Explanation of ${toolName}`,
      messages: [
        {
          role: "user",
          content: {
            type: "text",
            text: `Analyze and explain this tool: ${sourceCode}`
          }
        }
      ]
    };
  }
});

5.5 STDIO 传输层

import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

async function main() {
  const server = createServer();
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("MCP Server running on stdio");
}

---

6. 可复用的设计模式

6.1 目录扫描模式

// 通用目录扫描器
async function scanDirectory<T>(
  dirPath: string,
  filter: (entry: Dirent) => boolean,
  transform: (entry: Dirent, files: string[]) => T
): Promise<T[]> {
  const entries = await fs.readdir(dirPath, { withFileTypes: true });
  const results: T[] = [];
  
  for (const e of entries) {
    if (!filter(e)) continue;
    const files = await listDir(path.join(dirPath, e.name));
    results.push(transform(e, files));
  }
  
  return results.sort((a, b) => 
    (a as any).name.localeCompare((b as any).name)
  );
}

// 使用示例：扫描工具
const tools = await scanDirectory(
  path.join(SRC_ROOT, "tools"),
  (e) => e.isDirectory() && e.name !== "shared" && e.name !== "testing",
  (e, files) => ({ name: e.name, directory: `tools/${e.name}`, files })
);

6.2 安全路径验证模式

class SafeFileSystem {
  constructor(private root: string) {}
  
  private safePath(relPath: string): string | null {
    const resolved = path.resolve(this.root, relPath);
    if (!resolved.startsWith(this.root)) return null;
    return resolved;
  }
  
  async readFile(relPath: string): Promise<string | null> {
    const abs = this.safePath(relPath);
    if (!abs) return null;
    try {
      return await fs.readFile(abs, "utf-8");
    } catch {
      return null;
    }
  }
  
  async listDirectory(relPath: string): Promise<string[] | null> {
    const abs = this.safePath(relPath);
    if (!abs) return null;
    try {
      const entries = await fs.readdir(abs, { withFileTypes: true });
      return entries.map(e => e.isDirectory() ? e.name + "/" : e.name);
    } catch {
      return null;
    }
  }
}

6.3 内容行号处理模式

// 读取文件特定行范围，并添加行号
async function readFileWithLineNumbers(
  filePath: string,
  startLine = 1,
  endLine?: number
): Promise<string> {
  const content = await fs.readFile(filePath, "utf-8");
  const lines = content.split("\n");
  const end = endLine ?? lines.length;
  
  const slice = lines.slice(
    Math.max(0, startLine - 1),
    Math.min(lines.length, end)
  );
  
  return slice
    .map((line, i) => `${(startLine + i).toString().padStart(5)} | ${line}`)
    .join("\n");
}

6.4 文件搜索模式

interface SearchResult {
  file: string;
  line: number;
  content: string;
}

async function searchFiles(
  root: string,
  pattern: RegExp,
  options: {
    filePattern?: string;
    maxResults?: number;
  } = {}
): Promise<SearchResult[]> {
  const { filePattern, maxResults = 50 } = options;
  const results: SearchResult[] = [];
  
  // 获取所有文件
  const allFiles = await walkFiles(root);
  const filtered = filePattern
    ? allFiles.filter(f => f.endsWith(filePattern))
    : allFiles;
  
  for (const file of filtered) {
    if (results.length >= maxResults) break;
    
    const content = await fs.readFile(path.join(root, file), "utf-8");
    const lines = content.split("\n");
    
    for (let i = 0; i < lines.length; i++) {
      if (pattern.test(lines[i])) {
        results.push({
          file,
          line: i + 1,
          content: lines[i].trim()
        });
        if (results.length >= maxResults) break;
      }
    }
  }
  
  return results;
}

6.5 提示模板构建模式

// 功能映射表模式
const featureMap: Record<string, string[]> = {
  "permission system": ["utils/permissions/", "hooks/toolPermission/", "Tool.ts"],
  "mcp client": ["services/mcp/", "tools/MCPTool/"],
  "query engine": ["QueryEngine.ts", "query/"],
  bridge: ["bridge/"],
  plugins: ["plugins/"],
  skills: ["skills/"],
};

async function buildFeaturePrompt(feature: string): Promise<string> {
  const paths = featureMap[feature.toLowerCase()] ?? [];
  let context = "";
  
  for (const p of paths) {
    const content = await readFileOrListDir(p);
    context += `\n### ${p}\n${content}\n`;
  }
  
  return `Explain how "${feature}" works:\n${context}`;
}

---

7. 总结

7.1 核心发现

1. MCP 协议提供标准化的 AI 工具集成方式：通过统一的 JSON-RPC 接口，AI 客户端可以自动发现和使用服务器提供的工具、资源和提示。

2. 代码探索 MCP Server 的核心价值：

• 将庞大的代码库结构化暴露给 AI
• 支持细粒度的源码读取和搜索
• 提供预定义的提示模板简化分析任务

• 路径遍历防护（safePath()）
• 只读访问（不暴露写操作）
• 源码范围限定（只能访问 SRC_ROOT 下的内容）

• Transport 层无关（STDIO/HTTP）
• 模块化工具/资源/提示注册
• 环境变量配置灵活

7.2 应用场景

• 代码库学习: 快速了解大型项目的结构和实现
• 架构分析: 系统性地分析项目架构和设计模式
• 代码审查: 辅助进行代码审查和重构建议
• 文档生成: 自动生成项目文档和 API 参考

7.3 借鉴价值

此 MCP Server 实现为构建类似的代码探索工具提供了完整参考：

• 如何扫描和索引代码库结构
• 如何安全地暴露文件系统访问
• 如何设计有用的 AI 提示模板
• 如何实现高效的代码搜索

参考链接

• GitHub: https://github.com/TaGoat/claude_code_cli
• NPM: https://www.npmjs.com/package/claude-code-explorer-mcp
• MCP 协议文档: https://modelcontextprotocol.io/
• MCP TypeScript SDK: https://github.com/modelcontextprotocol/typescript-sdk

*报告生成时间: 2026-04-02* *分析工具: Kimi Search + kimi_fetch*

#ClaudeCode #Anthropic #AIAgent #MCP #架构分析 #代码泄露 #技术报告 #小凯