使用说明

代码库上下文MCP服务器

一个模型上下文协议（MCP）服务器，通过AST（抽象语法树）解析和Python、JavaScript、PHP和HTML项目的依赖图生成提供深度代码库分析。

概述

此MCP服务器使Claude Code和Codex CLI能够通过以下方式理解您的代码库结构：

从源文件中提取函数、类和导入
构建显示导入关系的依赖关系图
分析模块架构并检测循环依赖关系
在整个代码库中搜索符号

✨ 具有仅使用Python内置的自定义轻量级图形实现，不需要NetworkX或外部图形库！

快速开始

服务器已经配置好，可以使用了！当你启动克劳德代码时 或Codex CLI 会话中，MCP工具将自动可用。

测试设置

在您的任何项目中启动Claude Code或Codex，您应该看到：

# Codebase Context Loaded

You now have access to MCP tools for deep codebase analysis...

然后让你的助手分析你的项目：

User: "Give me a summary of this project"
Assistant: [Automatically uses `get_project_summary`]

注：在本文档中，任何提及“Claude”的地方都是指您正在运行的启用MCP的客户端（Claude Code或Codex CLI）。

Codex CLI支持

Codex CLI现在加载完全相同的MCP工具：

~/.codex/settings.json 镜像Claude钩子，以便SessionStart/PostToolUse运行 /home/tchang/MCP/rules/*.sh 食品法典委员会会议。
~/.codex/mcp.json 注册 codebase-context 服务器使用相同的命令/args，在可用时使用Codex项目目录环境变量。
~/.config/mcp/servers.json 提供了一个全局注册表项，因此其他支持MCP的工具可以重用服务器，而无需额外的设置。
rules/session_start_hook.sh 更新以检测Claude或Codex是否启动了会话并打印了正确的客户端标签。

要使用它： 重新启动Codex CLI，打开任何项目，然后运行 list_mcp_resources （或者只是开始编码）。你应该立即看到 codebase-context 服务器在工具列表中，并接收与Claude Code使用的相同的自动项目摘要工作流。

目录结构

/home/tchang/MCP/
├── codebase-context-server/
│   ├── server.py              # Main MCP server
│   ├── ast_tools.py           # AST parsing for Python/JS/PHP/HTML
│   ├── graph_tools.py         # Dependency graph generation
│   ├── requirements.txt       # Python dependencies
│   └── venv/                  # Python 3.13 virtual environment
├── rules/
│   ├── codebase_instructions.md     # Instructions for Claude/Codex
│   └── session_start_hook.sh        # SessionStart hook script
└── git-hooks/                 # Git hook templates (for future use)

可用的MCP工具

1.get_project_summary

获取有关代码库的高级统计信息。

用途：

Claude will call this automatically at session start

退货：

文件、函数、类、行总数
语言细分（Python、JS、PHP、HTML）

2.分析文件_列表

从单个文件中提取详细的AST信息。

参数：

file_path：文件路径（相对于项目根目录）
deep：布尔值，包含完整的AST结构（默认值：false）

退货：

带有签名和位置的函数
具有继承信息的类
导入语句
文件统计

3.分析目录

分析目录中所有支持的文件。

参数：

directory：目录路径
extensions：可选过滤器（例如，[“.py”，“.js”]）
deep：包括完整的AST结构

退货：

所有文件的完整AST数据
按语言分列的统计摘要

4.获取依赖关系图

构建显示导入关系的依赖关系图。

参数：

directory：项目根目录（默认为当前）
output_format：“summary”（默认）或“json”

退货：

文件和依赖项总数
循环依赖关系（如有）
大多数导入的文件

5.get_module_structure

模块组织的高级视图。

退货：

入口点（其他人未导入的文件）
叶子模块（不导入其他文件的文件）
目录细分
循环依赖

6.获取文件依赖关系

显示特定文件的依赖关系。

参数：

file_path：要分析的文件
directory：项目根

退货：

文件导入的内容
导入文件的内容

7.搜索_符号

在代码库中按名称查找函数或类。

参数：

pattern：搜索字符串（子字符串匹配）
symbol_type：“函数”、“类”或“两者都有”

退货：

将符号与文件位置和行号匹配

语言支持

语言	扩展	函数	类	导入	完整AST	图形
Python	.py	✓	✓	✓	✓	✓
JavaScript/TypeScript	.js、.jsx、.ts、.tsx	✓	✓	✓	✓	✓
PHP	.PHP	✓	✓	✓	✓	✓
HTML	.HTML、.htm	✗	✗	✗	✓	✗

注：依赖图生成使用自定义轻量级实现，无外部依赖！

运作原理

1.启动

当您开始Claude Code或Codex会议时：

SessionStart钩子运行(~/.claude/settings.json)
挂钩显示可用工具
克劳德自动呼叫 get_project_summary
您将获得代码库的概述

2.开发过程中

Claude根据上下文智能地使用工具：

编辑前： 分析文件AST和依赖关系
架构问题： 生成依赖关系图
代码搜索： 使用符号搜索
影响分析： 检查文件依赖关系

3.配置

MCP服务器配置 (~/.claude/mcp.json):

{
  "mcpServers": {
    "codebase-context": {
      "command": "/usr/local/bin/python3.13",
      "args": ["/home/tchang/MCP/codebase-context-server/server.py"],
      "env": {
        "PROJECT_DIR": "${CLAUDE_PROJECT_DIR}"
      }
    }
  }
}

会话启动挂钩 (~/.claude/settings.json):

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "/home/tchang/MCP/rules/session_start_hook.sh"
          }
        ]
      }
    ]
  }
}

Codex MCP配置 (~/.codex/mcp.json):

{
  "mcpServers": {
    "codebase-context": {
      "command": "/home/tchang/MCP/codebase-context-server/venv/bin/python",
      "args": [
        "/home/tchang/MCP/codebase-context-server/server.py"
      ],
      "env": {
        "PROJECT_DIR": "${CODEX_PROJECT_DIR}",
        "PYTHONPATH": "/home/tchang/MCP/codebase-context-server"
      }
    }
  }
}

Codex挂钩+MCP配置 (~/.codex/settings.json):

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "/home/tchang/MCP/rules/session_start_hook.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "/home/tchang/MCP/rules/post_edit_hook.sh"
          }
        ]
      }
    ]
  },
  "mcpServers": {
    "codebase-context": {
      "command": "/home/tchang/MCP/codebase-context-server/venv/bin/python",
      "args": [
        "/home/tchang/MCP/codebase-context-server/server.py"
      ],
      "env": {
        "PROJECT_DIR": "${CODEX_PROJECT_DIR}",
        "PYTHONPATH": "/home/tchang/MCP/codebase-context-server"
      },
      "enabled": true
    }
  }
}

测试

测试1：项目总结

cd /home/tchang/python/projects/your-project
claude
# Claude should automatically show project summary

测试2：文件分析

问克劳德：

"Analyze the structure of main.py"

克劳德将使用 analyze_file_ast 显示函数、类和导入。

测试3：依赖关系图

问克劳德：

"Show me the dependency structure of this project"

克劳德将使用 get_module_structure 和 get_dependency_graph.

测试4：符号搜索

问克劳德：

"Where is the login function defined?"

克劳德将使用 search_symbols 找到它。

故障排除

MCP服务器未加载

检查MCP配置（Claude）：

cat ~/.claude/mcp.json

检查MCP配置（Codex）：

cat ~/.codex/mcp.json

手动测试服务器：

cd /home/tchang/MCP/codebase-context-server
source venv/bin/activate
python server.py
# Should wait for input (MCP server running)
# Press Ctrl+C to exit

SessionStart钩子未运行

检查设置（Claude）：

cat ~/.claude/settings.json

检查设置（Codex）：

cat ~/.codex/settings.json

手动测试挂钩：

/home/tchang/MCP/rules/session_start_hook.sh
# Should display instructions

Python依赖关系问题

重新安装依赖关系：

cd /home/tchang/MCP/codebase-context-server
source venv/bin/activate
pip install -r requirements.txt

MCP工具未出现

检查克劳德代码日志：

tail -f ~/.claude/debug/*.log

重新启动Claude代码：

# Exit current session and start fresh

性能提示

大型代码库

对于线路超过100k的项目：

工具通过缓存进行了优化
使用有针对性的查询而不是全面分析
deep=false （默认）用于更快的分析

排除目录

以下目录将自动跳过：

.git, __pycache__, node_modules
venv, .venv, vendor
dist, build

第2和第3阶段路线图

第二阶段：代码库发现

目标： 使用第一阶段工具分析您的实际项目

流程：

Claude使用当前工具分析您的代码库
发现模式：
- 如何定义路由/端点
- 数据库查询的位置
- 配置文件格式
- 文件结构

可交付成果： 专用工具设计文件

第三阶段：专业工具

目标： 根据您的代码库构建工具

计划工具：

API路由发现
- 自动检测框架（Flask、Slim、Express等）
- 使用方法和处理程序提取所有端点
数据库架构提取
- 连接MySQL数据库
- 解析迁移文件
- 从ORM模型中提取
配置分析器
- 解析.env文件
- 从config.php、settings.py中提取
- 更正敏感数据
文档索引器
- 索引文档字符串和注释
- 解析README和文档/
- 可搜索的文档上下文

您的项目

服务器适用于您的所有项目：

/home/tchang/python/projects/ （16524个文件，约365k行）
/home/tchang/python/Working/ （651个文件，~464k行）
/var/www/html/samplelogin/ （1116个文件，约140万行）

高级用法

自定义文件扩展名

编辑 ast_tools.py 要添加更多语言：

EXT_TO_LANG = {
    '.py': 'python',
    '.js': 'javascript',
    # Add your custom extensions here
}

导出依赖关系图

图形会自动导出到 .context/ 在每个项目中：

dependency-graph.json -机器可读格式
dependency-graph.dot -用于可视化的Graphviz格式

图形可视化

# Install Graphviz
sudo apt-get install graphviz

# Generate PNG from DOT file
dot -Tpng .context/dependency-graph.dot -o dependency-graph.png

为第二阶段做出贡献

当你开始使用这些工具时，请注意：

你在代码中发现了什么模式
什么额外的背景会有所帮助
特定的痛点或重复的询问

这将为第3阶段专用工具的设计提供信息。

支持

对于问题或疑问：

检查上面的故障排除部分
审查 /home/tchang/MCP/rules/codebase_instructions.md
手动测试组件（服务器、挂钩、工具）

文件位置

MCP服务器： /home/tchang/MCP/codebase-context-server/
说明： /home/tchang/MCP/rules/codebase_instructions.md
MCP配置： ~/.claude/mcp.json
设置： ~/.claude/settings.json
日志： ~/.claude/debug/

版本

第1阶段-完成

Python、JS、PHP、HTML的AST分析
依赖图生成
模块结构分析
符号搜索
自动会话初始化

第2阶段-计划

代码库模式发现
框架检测

第3阶段-计划中

API路由发现
数据库架构提取
配置解析
文档索引

使用说明

代码库上下文MCP服务器

概述

快速开始

测试设置

Codex CLI支持

目录结构

可用的MCP工具

1.get_project_summary

2.分析文件_列表

3.分析目录

4.获取依赖关系图

5.get_module_structure

6.获取文件依赖关系

7.搜索_符号

语言支持

运作原理

1.启动

2.开发过程中

3.配置

测试

测试1：项目总结

测试2：文件分析

测试3：依赖关系图

测试4：符号搜索

故障排除

MCP服务器未加载

SessionStart钩子未运行

Python依赖关系问题

MCP工具未出现

性能提示

大型代码库

排除目录

第2和第3阶段路线图

第二阶段：代码库发现

第三阶段：专业工具

您的项目

高级用法

自定义文件扩展名

导出依赖关系图

图形可视化

为第二阶段做出贡献

支持

文件位置

版本

相关 MCP

代码索引分析工具

代码分析服务器

GitHub仓库解析工具

VSCode MCP桥接工具

语言服务协议MCP

上下文管理服务