内容
# 代码异味检测MCP
静态分析/代码异味检测的MCP服务器。最小的TypeScript标准输入输出传输实现和工具注册 stubs。
## 目标
- 将CodeVi内部的`codevi-metrics-server.ts`单一文件中心实现分离为独立的MCP工具服务器。
- 排除CodeVi本体依赖项，如NestJS、TypeORM、MySQL、Docker配置等。
- 首先以npm发布/使用为目标（PyPI后续考虑Python移植时）。
## 使用方法
1. 安装
```bash
npm install
```
2. 开发模式
```bash
npm run dev
```
3. 构建
```bash
npm run build
```
4. 测试
```bash
npm run test:stdio
npm run test:advanced-pyexamine
npm run test:advanced-pyexamine:http
```
5. 运行（构建后）
```bash
npm start
```
## 环境变量
复制并使用`.env`：
- `ANALYSIS_API_BASE_URL`（例：http://localhost:13000/api）
- `REQUEST_TIMEOUT_MS`
- `METRICS_API_BASE_URL`（例：http://localhost:14000）
- `METRICS_API_KEY`（需要时）
- `METRICS_DEFAULT_TEAM_PROJECT_ID`
- `METRICS_REQUEST_TIMEOUT_MS`
- `ADVANCED_PYEXAMINE_BIN`（默认值：`python`）
- `ADVANCED_PYEXAMINE_ARGS`（默认值：`-m,advanced_pyexamine`）
- `ADVANCED_PYEXAMINE_CWD`（例：advanced_pyexamine仓库根目录）
- `ADVANCED_PYEXAMINE_TIMEOUT_MS`
- `ADVANCED_PYEXAMINE_MODE`（`cli`或`http`，默认值：`cli`）
- `ADVANCED_PYEXAMINE_SERVICE_URL`（HTTP模式，例：http://localhost:18080）
- `ADVANCED_PYEXAMINE_SERVICE_TIMEOUT_MS`
- `ADVANCED_PYEXAMINE_SOURCE_DIR`（服务运行时advanced_pyexamine原始仓库路径）
- `ADVANCED_PYEXAMINE_E2E_PROJECT_PATH`（实际服务E2E测试対象Python项目路径）
## 提供工具
### 指标分析
- `list_metric_analyses`：查询CodeVi指标分析历史记录列表
- `run_metric_analysis`：执行并保存CodeVi指标分析
- `get_metric_analysis`：查询保存的指标分析单条记录
### PyExamine / 代码分析
- `get_latest_pyexamine_result`：查询最新PyExamine结果
- `get_pyexamine_result_by_commit`：根据提交哈希查询PyExamine结果
- `get_high_severity_smells`：查询高严重性代码异味
- `get_smells_by_file`：根据文件路径查询代码异味
### 高级PyExamine
- `analyze_python_smells`：返回Python项目代码异味结果为JSON
- `ADVANCED_PYEXAMINE_MODE=cli`：以子进程执行`advanced_pyexamine`CLI
- `ADVANCED_PYEXAMINE_MODE=http`：调用`services/advanced-pyexamine`HTTP服务的`/analyze`
CLI模式示例：
```bash
printf '%s\n' '{"id":"py-smell-1","tool":"analyze_python_smells","params":{"projectPath":"/path/to/python/project"}}' \
| ADVANCED_PYEXAMINE_MODE=cli \
ADVANCED_PYEXAMINE_BIN=python \
ADVANCED_PYEXAMINE_ARGS=-m,advanced_pyexamine \
ADVANCED_PYEXAMINE_CWD="/path/to/pyexamine 2" \
node dist/server.js
```
HTTP模式示例：
```bash
printf '%s\n' '{"id":"py-smell-5","tool":"analyze_python_smells","params":{"projectPath":"/path/to/python/project","summaryOnly":true}}' \
| ADVANCED_PYEXAMINE_MODE=http \
ADVANCED_PYEXAMINE_SERVICE_URL=http://localhost:18080 \
node dist/server.js
```
运行HTTP服务：
```bash
ADVANCED_PYEXAMINE_SOURCE_DIR="/path/to/pyexamine 2" npm run service:advanced-pyexamine
```
以Docker运行HTTP服务：
```bash
docker build -t advanced-pyexamine-service:local services/advanced-pyexamine
docker run --rm \
-p 18080:18080 \
-e ADVANCED_PYEXAMINE_SOURCE_DIR=/opt/advanced-pyexamine-source \
-v "/path/to/pyexamine 2:/opt/advanced-pyexamine-source:ro" \
advanced-pyexamine-service:local
```
详细Docker工作流程请参考`docs/advanced-pyexamine-service-docker.md`。
使用Docker Compose运行MCP服务器和HTTP服务：
```bash
printf '%s\n' '{"id":"compose-e2e-1","tool":"analyze_python_smells","params":{"projectPath":"/opt/advanced-pyexamine-source/advanced_pyexamine","only":"long_method,data_clumps","summaryOnly":true}}' \
| ADVANCED_PYEXAMINE_HOST_SOURCE_DIR="/path/to/pyexamine 2" \
docker compose -f docker-compose.example.yml run --rm -T mcp-server
```
集成Compose工作流程请参考`docs/mcp-advanced-pyexamine-compose.md`。
在CodeVi后端调用`advanced-pyexamine-service`：
```bash
ADVANCED_PYEXAMINE_HOST_SOURCE_DIR="/path/to/pyexamine 2" \
npm run compose:codevi-runtime:up
```
此Compose将`advanced-pyexamine-service`连接到外部Docker网络`shared-net`，并为CodeVi后端固定network alias，以便其可以调用`http://advanced-pyexamine-service:18080`。
传递给CodeVi后端的分析路径使用容器路径，而不是主机路径。
```text
/opt/advanced-pyexamine-source/advanced_pyexamine
```
停止：
```bash
ADVANCED_PYEXAMINE_HOST_SOURCE_DIR="/path/to/pyexamine 2" \
npm run compose:codevi-runtime:down
```
详细CodeVi运行时工作流程请参考`docs/advanced-pyexamine-codevi-runtime.md`。
实际HTTP服务E2E验证：
```bash
ADVANCED_PYEXAMINE_SERVICE_URL=http://localhost:18080 \
ADVANCED_PYEXAMINE_E2E_PROJECT_PATH="/path/to/python/project" \
npm run test:advanced-pyexamine:service
```
若要运行特定检测器，请传递`only`参数。
```json
{ "id": "py-smell-2", "tool": "analyze_python_smells", "params": { "projectPath": "/path/to/python/project", "only": "orphan_module,data_clumps" } }
```
若响应过大，可以使用`summaryOnly`或`limitPerGroup`。
```json
{ "id": "py-smell-3", "tool": "analyze_python_smells", "params": { "projectPath": "/path/to/python/project", "summaryOnly": true } }
```
```json
{ "id": "py-smell-4", "tool": "analyze_python_smells", "params": { "projectPath": "/path/to/python/project", "limitPerGroup": 5 } }
```
`summary`始终基于整个检测结果，而`limitPerGroup`仅限制返回的`smellGroups`。
`test:advanced-pyexamine`在没有实际`advanced_pyexamine`仓库的情况下，使用mock CLI验证`summary`、`summaryOnly`和`limitPerGroup`响应处理。
`test:advanced-pyexamine:http`使用mock HTTP服务验证MCP HTTP模式转发和响应处理。
`test:advanced-pyexamine:service`针对已运行的实际FastAPI服务，验证`/health`、`/analyze`和MCP HTTP模式。
CodeVi后端联动合同请参考`docs/codevi-smell-analysis-contract.md`。
## 原始代码分离指南
- 复制文件：`code-vi-internal/code-vi-back/src/mcp/codevi-metrics-server.ts`
- 移动项目：
- axios 기반 REST 调用逻辑 → `src/clients/analysis-client.ts`
- 工具注册部分 → `src/tools/*.ts`
- 类型定义（接口）→ `src/types/*`
- stdio传输或MCP SDK初始化部分 → `src/stdio/stdio-transport.ts`
- 排除项目：
- NestJS模块/控制器整体
- TypeORM实体/DB设置
- Docker/Jenkins配置
- 现有CodeVi前端/后端依赖项
## Cursor / Codex / Claude 运行示例
- 在使用Cursor/Codex等工具时，通过stdio交换JSON消息。
- 消息格式示例：
```json
{ "id": "uuid-1234", "tool": "get_latest_pyexamine_result", "params": { "repo": "owner/repo", "ref": "main" } }
```
- 响应格式示例：
```json
{ "id": "uuid-1234", "result": { /* 结果载荷 */ } }
```
## 后续工作
- 从原始`codevi-metrics-server.ts`迁移实际处理逻辑
- 错误/类型再检视，追加测试案例
- 需要时转换为MCP官方SDK（stdio以外）的传输
- npm包化和发布
- CodeVi后端代码异味分析合同对应的存储/API实现在单独的后端仓库中进行
