内容
# 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消费设计的标准成功/错误信封。
## 架构概述
```mermaid
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>`
## 示例提示
- "分析我的仓库"
- "获取事件"
- "修复此错误"
## 环境变量
参见`.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`
### 云运行
使用`deploy.sh`:
```bash
PROJECT_ID=<gcp-project> REGION=<region> SERVICE=nexus-core ./deploy.sh
```
此脚本：
1. 构建容器镜像
2. 推送到GCR
3. 部署到云运行
## 可靠性和错误模型
- 所有工具请求都使用Zod验证。
- 没有工具执行返回未处理的异常。
- 错误使用标准信封，包含：
- `code`
- `message`
- `retryable`
- `suggestedAction`
- `meta`（`requestId`，`toolName`，时间）
