MCP 服务器代码库分析器

一个生产级的 MCP（模型上下文协议）服务器，用于分析 TypeScript 代码库、检测代码健康问题、获取系统事件并生成可执行的补救计划。支持双重传输（用于本地开发的 STDIO 和用于云部署的 SSE）。基于 ts-morph、Express 和 Zod 验证构建。

🚀 功能

三大核心工具：

1. analyze_codebase_health — 扫描 TypeScript 仓库以查找：

   • 大文件（潜在的重构候选对象）

   • 缺失的显式函数类型（弱类型）

   • 循环依赖（架构问题）

   • 使用 ts-morph 进行 AST 级分析

2. fetch_system_incidents — 返回结构化的事件数据：

   • 模拟事件数据（非常适合测试/演示）

   • 可配置的延迟和故障模式

   • 对 LLM 友好的 JSON 响应

3. generate_remediation_plan — 创建可执行的修复计划：

   • 基于堆栈跟踪的根本原因分析

   • 分步补救措施

   • 代码建议和最佳实践

   • 风险等级评估

所有工具均返回专为 LLM 使用而设计的结构化成功/错误信封。

架构概览

flowchart LR
    Client[McpClient] --> Runtime[RuntimeSelector]
    Runtime -->|stdio| Stdio[StdioTransportAdapter]
    Runtime -->|sse| Sse[SseTransportAdapter]
    Stdio --> Server[McpServer]
    Sse --> Server
    Server --> Registry[ToolRegistry]
    Registry --> ToolA[analyze_codebase_health]
    Registry --> ToolB[fetch_system_incidents]
    Registry --> ToolC[generate_remediation_plan]

本地运行 (STDIO)

1. 安装依赖：

   • npm install

2. 启动服务器：

   • npm run dev:stdio

3. 服务器通过 stdin/stdout 启动，并准备好供本地 MCP 客户端使用。

使用 SSE (Express) 运行

1. 设置环境变量：

   • TRANSPORT=sse

   • 可选：AUTH_TOKEN=your-secret-token

2. 启动服务器：

   • npm run dev:sse

3. 端点：

   • GET /events 用于 SSE 流

   • POST /messages?sessionId=... 用于 MCP JSON-RPC 消息

从 Cursor 连接

对于本地使用，将 Nexus-Core 注册为 stdio MCP 服务器：

• 命令：node

• 参数：dist/index.js（构建后）或 tsx src/index.ts（开发环境）

• 环境变量：TRANSPORT=stdio

对于托管使用，配置您的 MCP 客户端以使用 SSE 端点：

• 流 URL：https://<host>/events

• 消息 URL：https://<host>/messages?sessionId=<session-id>

• 如果启用了令牌认证，请添加 Authorization: Bearer <AUTH_TOKEN>。

示例提示词

• "Analyze my repo"

• "Fetch incidents"

• "Fix this error"

环境变量

查看 .env.example 获取所有支持的设置。重要的控制项：

• TRANSPORT: stdio 或 sse

• TOOL_TIMEOUT_MS: 每个工具调用的硬超时时间

• TS_MORPH_MAX_FILES, TS_MORPH_MAX_DEPTH: 分析防护栏

• INCIDENT_API_TIMEOUT_MS, INCIDENT_API_RETRIES: 外部依赖控制

• SSE_HEARTBEAT_MS, SSE_SESSION_TTL_MS: SSE 会话生命周期

生产部署

Docker

• 构建镜像：docker build -t nexus-core .

• 运行容器：

  • docker run -e TRANSPORT=sse -e PORT=8080 -p 8080:8080 nexus-core

Cloud Run

使用 deploy.sh：

PROJECT_ID=<gcp-project> REGION=<region> SERVICE=nexus-core ./deploy.sh

此脚本：

1. 构建容器镜像

2. 推送到 GCR

3. 部署到 Cloud Run

可靠性和错误模型

• 所有工具请求均通过 Zod 进行验证。

• 工具执行不会返回未处理的异常。

• 错误使用标准信封，包含：

  • code

  • message

  • retryable

  • suggestedAction

  • meta (requestId, toolName, 时间)