MCP 代码分析

一个强大的代码库分析工具包，利用模型上下文协议 (MCP) 进行 AI 辅助的代码理解和转换。

功能特性

• 代码分析: 使用抽象语法树解析和分析代码库
• 上下文生成: 为 AI 模型创建丰富的上下文信息
• 工具集成: 构建于 MCP SDK 之上，实现无缝的 AI 工具集成
• 可扩展架构: 基于插件的系统，用于自定义分析器

环境要求

• Node.js 18+
• NPM 9+
• Redis (可选，仅在生产环境需要)

安装

# 克隆仓库
git clone https://github.com/yourusername/mcp-codeanalysis.git
cd mcp-codeanalysis

# 安装依赖
npm install

# 构建项目
npm run build

Redis 配置 (可选)

Redis 用于生产环境中的会话存储。 对于开发和测试，如果 Redis 不可用，系统将自动回退到内存会话存储。

注意: Redis 连接存在已知问题，即使 Redis 正在运行，操作也可能失败。 有关详细信息，请参阅 plan.md 中的“技术债务”部分。 目前，您可以使用 ./use-memory-session.sh 脚本来运行带有内存会话存储的服务器。 有关更多信息，请参阅 Redis 故障排除指南。

要安装 Redis：

# Ubuntu/Debian
sudo apt-get install redis-server

# macOS
brew install redis

# Windows (建议使用 WSL)
# 对于原生 Windows，请从 https://redis.io/download 下载

默认情况下，应用程序尝试连接到 redis://localhost:6379 上的 Redis。 您可以使用环境变量配置 Redis 连接：

# 设置自定义 Redis URL
export REDIS_URL=redis://custom-host:6379

# 强制使用内存会话存储，即使 Redis 可用
export FORCE_MEMORY_SESSION=true

开发

# 在开发模式下运行
npm run dev

# 运行测试
npm test

# 运行代码检查
npm run lint

使用

# 启动 MCP 服务器
npm start

# 运行 CLI 工具
node ./tools/mcp-stdio-client.js --task "Analyze dependencies" --files "src/*.ts"

文档

• 会话存储架构
• Redis 集成
• MCP 协议

许可证

MIT

CodeAnalysis MCP 服务器

一个全面的模型上下文协议 (MCP) 服务器，用于高级代码分析，通过可扩展的架构提供工具和见解。

🚀 功能特性

• 基本代码分析: 语法和结构分析
• 代码指标: 复杂度、行数和代码质量指标
• 依赖分析: 包和导入关系可视化
• 知识图谱: 代码关系可视化和查询
• 内存系统: 存储和检索有关代码库的见解
• 可视化: 生成多种格式的图表 (Mermaid, DOT, ASCII)
• 社会技术分析: 了解团队和代码关系
• 多仓库分析: 跨仓库关系分析
• 演进规划: 代码改进建议
• 实时监控: 实时监控代码更改
• IDE 集成: 用于编辑器集成的工具
• 开发者工具: 增强的 AI 辅助开发工作流程支持

📋 前提条件

• Node.js 18+
• npm 或 yarn
• Redis (开发可选，生产推荐)

🛠️ 安装

# 克隆仓库
git clone https://github.com/your-username/codeanalysis-mcp.git
cd codeanalysis-mcp

# 安装依赖
pnpm install

# 构建项目
pnpm build

🖥️ 使用

CodeAnalysis MCP 服务器可以通过两种方式使用：

1. 作为 MCP 服务器

# 启动 MCP 服务器
pnpm start

这将启动 MCP 服务器，任何 MCP 客户端（如 Claude Desktop、Cursor 或其他客户端）都可以连接到该服务器。

2. 使用 CLI

该项目包含一个全面的 CLI，用于直接交互：

# 获取帮助
pnpm run cli --help

# 分析仓库或目录
pnpm run cli analyze repo ./src

# 检查代码质量
pnpm run cli quality analyze ./src

3. 使用开发者工具进行 AI 辅助开发

该项目包含专门用于增强 AI 辅助开发的工具：

# 为 AI 助手生成代码上下文
node tools/ai-dev-helper.js --task="Implement new feature" --search="related functionality"

# 运行示例客户端
node examples/dev-tools-client.js

有关详细信息，请参阅 开发者工具指南。

📊 示例命令

基本分析

# 分析本地目录
pnpm run cli analyze repo ./src

# 分析特定文件
pnpm run cli analyze file ./src/server.ts

代码指标

# 获取带有函数详细信息的代码指标
pnpm run cli metrics analyze ./src --functions

# 将指标保存到文件
pnpm run cli metrics analyze ./src -o metrics-report.json

依赖分析

# 以 Mermaid 格式分析依赖关系
pnpm run cli dependencies analyze ./src -f mermaid -o deps.mmd

# 可视化依赖关系
pnpm run cli visualize dependencies -p ./src --format mermaid

代码质量

# 运行质量分析
pnpm run cli quality analyze ./src

# 生成 HTML 报告
pnpm run cli quality analyze ./src --html -o quality-report.html

知识图谱

# 构建知识图谱
pnpm run cli knowledge build ./src

# 查询知识图谱
pnpm run cli knowledge query ./src "type:function AND complexity>5"

# 导出为图表
pnpm run cli knowledge export ./src -f mermaid

见解 & 内存

# 存储一个见解
pnpm run cli insights store -r ./src -t code-pattern -c "Refactoring opportunity"

# 检索见解
pnpm run cli insights retrieve -r ./src

开发者工具

# 为 AI 交互准备上下文
node tools/ai-dev-helper.js --task="Fix authentication bug" --files="src/auth/*.ts" --search="login"

# 与 AI 提示一起使用
# 将从生成的 ai-context.json 文件中的内容复制到您的 AI 助手提示中
# 或使用 templates/ai-prompt-template.md 中的模板

🏗️ 架构

该项目遵循 MCP 架构，包含以下组件：

1. MCP 服务器: 使用 MCP 协议的核心服务器实现
2. 分析功能: 模块化代码分析功能
3. CLI: 用于直接交互的命令行界面
4. 传输层: 通信机制（默认为 stdio）

🔌 与 MCP 客户端集成

此服务器与任何符合 MCP 的客户端兼容，包括：

• Claude Desktop App
• Cursor Editor
• Continue
• 其他 MCP 兼容工具

📝 路径规范

命令接受各种格式的路径：

• 本地目录：./src 或 /absolute/path/to/dir
• 本地文件：./src/file.ts 或 /path/to/file.ts
• 仓库 URL：https://github.com/username/repo

🤝 贡献

欢迎贡献！ 请随时提交 Pull Request。

📄 许可证

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。

MCP SDK 状态管理架构

该项目实现了模型上下文协议 (MCP) SDK 的有状态工具，为构建在调用之间保持上下文的工具提供了一个框架。

架构概述

状态管理架构组织成几个模块化组件：

src/state/
├── helpers/
│   └── statefulTool.ts       # 创建有状态工具的主要入口点
├── machines/
│   └── toolMachine.ts        # 用于工具执行流程的 XState 状态机
├── services/
│   ├── toolService.ts        # 工具的核心执行服务
│   ├── redisToolExecutionService.ts  # 分布式执行服务
│   ├── redisSessionStore.ts  # 基于 Redis 的会话持久化
│   └── types.ts              # 共享类型定义

核心组件

有状态工具助手 (statefulTool.ts)

与 MCP SDK 的中心集成点，提供：

• 带有会话管理的工具注册
• 符合 MCP 的响应格式
• 内存会话管理
• 用于会话访问和操作的辅助函数

// 创建具有状态持久性的有状态工具
createStatefulTool(server, "my-tool", schema, handler);

// 带有描述
createStatefulTool(server, "my-tool", "My stateful tool", schema, handler);

工具状态机 (toolMachine.ts)

基于 XState 的状态机，定义了工具的执行流程：

• 状态转换（空闲、toolSelected、parametersSet、执行中等）
• 用于参数、结果和历史记录的上下文管理
• 错误处理和恢复路径

此组件将会话管理委托给 statefulTool 实现。

工具服务 (toolService.ts)

协调工具状态转换的核心执行服务：

• 管理工具选择、参数验证和执行
• 跟踪执行历史记录
• 处理执行结果和错误

类型 (types.ts)

确保状态管理系统一致性的共享类型定义：

• SessionData：用于存储工具状态的结构
• SessionStore：用于会话存储实现的接口
• ExecutionResult：工具的标准响应格式

与 MCP SDK 集成

该架构通过以下方式与 MCP SDK 集成：

1. 使用状态管理扩展工具注册模式
2. 保持与 MCP 响应格式的兼容性
3. 为有状态操作提供会话和上下文跟踪

使用示例

import { createServer } from "@modelcontextprotocol/sdk";
import { createStatefulTool } from "./state/helpers/statefulTool";
import { z } from "zod";

const server = createServer();

// 注册一个有状态工具
createStatefulTool(
  server,
  "counter",
  "A tool that maintains a count between invocations",
  {
    action: z.enum(["increment", "decrement", "reset"]),
  },
  async (params) => {
    // 从参数中获取会话 ID（或将创建一个新的会话 ID）
    const sessionId = params.sessionId;

    // 处理操作
    let count = 0;

    // 带有状态操作的工具逻辑...

    return { count };
  }
);

server.listen(3000);

分布式状态管理

对于分布式环境，基于 Redis 的实现提供：

• 跨服务器重启的会话持久性
• 用于并发访问的分布式锁定
• 基于 TTL 的会话清理
• 网络/连接问题的错误处理

测试

这些组件包括全面的测试套件，以验证：

• 工具状态转换
• 会话管理
• 错误处理和恢复
• 响应格式
• 分布式操作（使用 Redis）

AI 开发工具

CodeAnalysis MCP 服务器为 AI 辅助开发提供专用工具。 这些工具可以帮助收集代码上下文，这些上下文可以提供给 AI 系统，以获得更有效的帮助。

客户端脚本

该仓库在 tools/ 目录中包含多个客户端脚本：

• HTTP 客户端 (tools/http-client.js): 通过 HTTP 传输（默认）连接到 MCP 服务器。

  node tools/http-client.js --task "Your task description" --files "src/features/*.ts" --search "session"
  

• 原始客户端 (tools/mcp-raw-client.js): 一个更简单的客户端，仅捕获服务器信息。

  node tools/mcp-raw-client.js --task "Your task description"
  

• 简单客户端 (tools/simple-client.js): 通过 stdio 与服务器通信。

  node tools/simple-client.js --task "Your task description" --files "src/features/*.ts"
  

所有客户端脚本都会在项目根目录中生成一个 ai-context.json 文件。 此文件包含有关您的代码库的宝贵上下文，可以与 AI 助手共享，以提供更明智的响应。

提示模板

AI 助手的提示模板位于 templates/ai-prompt-template.md。 此模板有助于使用来自 MCP 工具的适当上下文来构建对 AI 助手的请求。

服务器传输模式

MCP 服务器支持两种传输模式：

1. HTTP 传输（默认）：默认情况下在端口 3000 上运行。 最适合客户端-服务器架构。
2. Stdio 传输: 用于直接进程通信。 设置 STDIO_TRANSPORT=true 环境变量以启用。

会话存储架构

MCP 代码分析现在具有模块化会话存储架构，具有自动后端检测：

• 灵活存储: 自动在 Redis 和内存存储之间切换
• 开发友好: 在开发期间无需 Redis 即可运行
• 生产就绪: 在生产环境中使用 Redis 进行持久化
• 自动回退: 当 Redis 不可用时，优雅地回退到内存存储

有关更多详细信息，请参阅 会话存储架构 文档。

环境要求

• Node.js 18+
• npm 或 yarn
• Redis (开发可选，生产推荐)