# CodeInsight-MCP

> 基于 [MCP（Model Context Protocol）](https://modelcontextprotocol.io/) 协议的代码分析 Agent，让 LLM 读懂任意代码库并输出深度分析（≥1500 字报告，含代码片段 + 行号 + 优先级建议）。

---

## 🎯 一句话定位

```
用户输入 GitHub URL
    ↓
Agent 自动 fetch_url 下载源码
    ↓
LangGraph 编排 7 个 MCP 工具（read_file / search_code / find_definition / 
analyze_complexity / get_git_history / suggest_refactor）
    ↓
输出 ≥1500 字深度报告（含真实代码片段 + 行号 + 优先级建议）
```

---

## 🏆 真实 GitHub 项目分析案例（5/5 全 4.80+ 通过）

| 项目 | Stars | 分析文件 | 关键发现 | 得分 |
|---|---|---|---|---|
| [langchain-ai/langgraph](https://github.com/langchain-ai/langgraph) | 23K+ | `state.py` (1978 行) | `add_node CCN=44`、`compile CCN=43` | **4.80** |
| [deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness) | 189K+ | `continuation.ts` (1545 行) | `settlementSummary CCN=31` | **4.80** |
| [microsoft/autogen](https://github.com/microsoft/autogen) | 36K+ | `_assistant_agent.py` (1704 行) | AssistantAgent 核心 | **4.80** |
| [crewAIInc/crewAI](https://github.com/crewAIInc/crewAI) | 30K+ | `core.py` (1800 行) | Crew AI Agent 编排 | **4.80** |
| [openai/openai-python](https://github.com/openai/openai-python) | 7K+ | `_base_client.py` (2200 行) | LLM SDK 通用 base | **4.80** |

---

## 🎯 端到端工作流

```
用户输入：https://github.com/langchain-ai/langgraph/blob/main/libs/langgraph/langgraph/graph/state.py
    ↓
Agent 内部执行：
  ① fetch_url(url) → 下载到 examples/fetched/，返回 local_path
  ② read_file(path=local_path) → 读完整 1978 行
  ③ search_code(directory=..., pattern="^(class|def|async def)") → 列出骨架
  ④ analyze_complexity(file_path=local_path) → 找出 CCN > 10 的函数
  ⑤ find_definition(symbol="add_node", file_path=local_path) → 定位
  ⑥ read_file(start_line=667, end_line=926) → 读 add_node 函数体
  ⑦ search_code(pattern="except\\s*:\\s*\\n\\s*pass|global\\s+") → 反模式
  ⑧ respond_node → 生成深度报告
```

**真实执行：17 次工具调用，6 分钟内完成**

---

## 🏗 架构

```
┌─────────────────────────────────────────┐
│  Claude Desktop / 自研 Agent / curl   │  ← 任意 MCP Client
└────────────┬────────────────────────────┘
             │ MCP 协议 (JSON-RPC over stdio)
             ▼
┌─────────────────────────────────────────┐
│  CodeInsight-MCP Server                │
│  ├ read_file                           │
│  ├ search_code                         │
│  ├ find_definition                     │
│  ├ get_git_history                     │
│  ├ analyze_complexity  (Python/TS/Java/Go) │
│  ├ suggest_refactor                    │
│  └ fetch_url  ← 新增：GitHub URL → 本地  │
└────────────┬────────────────────────────┘
             │ langchain-mcp-adapters
             ▼
┌─────────────────────────────────────────┐
│  LangGraph Agent 状态机                │
│  plan → execute → reflect → respond   │
│  + 5 套工作流模板（见下）            │
└─────────────────────────────────────────┘
```

---

## 🤖 4 节点状态机

```
plan → execute → reflect → (plan | respond) → END
```

| 节点 | 职责 |
|---|---|
| **plan** | Orchestrator LLM 决策下一步调哪个工具 |
| **execute** | 调 MCP 工具（含参数名容错 + fetched_files 路径跟踪）|
| **reflect** | Reflect LLM 评估信息是否足够回答用户问题 |
| **respond** | 基于工具结果生成 ≥1500 字深度报告 |

**5 套工作流模板：**

| 模板 | 用途 | 强约束 |
|---|---|---|
| `code_review` | 代码走查 + 复杂度 + 重构 | 6 阶段深度流程 |
| `onboarding` | 新员工了解项目 | 必须读完 + 列出全部工具 |
| `bug_investigation` | 排查 bug | 必须读完全部相关文件 + 至少 3 个根因假设 |
| `deep_review` | 深度审查（最严格） | 完整 6 阶段：fetch → 整体理解 → 复杂度 → 深入阅读 → 反模式 → 综合报告 |
| `general` | 通用代码分析 | 灵活选择工具组合 |

---

## 🛠 7 个 MCP 工具

| 工具 | 用途 | 关键技术 |
|---|---|---|
| `read_file` | 读取文件片段（支持大文件分片） | UTF-8 / GBK 自动检测 |
| `search_code` | 代码模式搜索（字面量 / 正则） | 支持 Python / TS / JS / 多语言 |
| `find_definition` | 符号定位 | tree-sitter AST + 正则兜底（兼容中英文） |
| `get_git_history` | Git 提交历史 | git log --follow |
| `analyze_complexity` | 圈复杂度分析 | lizard（支持 Python/TS/Java/Go 等） |
| `suggest_refactor` | LLM 重构建议 | 提示词工程 + 关注点（general/performance/readability） |
| `fetch_url` | 远程文件下载 | GitHub blob → raw 转换 + 本地缓存 + 扩展名保留 |

---

## 🧪 评估体系（12 个用例 · 通过率 75.0% · 平均分 4.56）

### 总览

| 用例 | 类型 | 平均分 | 通过 |
|---|---|---|---|
| case_001 复杂度分析 | 本地功能 | 4.75 | ✅ |
| case_002 符号搜索 | 本地功能 | 3.75 | ❌ |
| case_003 模式搜索 | 本地功能 | 3.00 | ❌ |
| case_004 多步走查 | 本地功能 | 4.20 | ❌ |
| case_005 错误处理 | 异常场景 | 5.00 | ✅ |
| case_006 Onboarding | 综合 | 5.00 | ✅ |
| case_007 你的项目 | paper-factor-system | 5.00 | ✅ |
| **case_008 LangGraph** | **GitHub 真实** | **4.80** | **✅** |
| **case_009 DeepSeek Harness** | **GitHub 真实** | **4.80** | **✅** |
| **case_010 AutoGen** | **GitHub 真实** | **4.80** | **✅** |
| **case_011 CrewAI** | **GitHub 真实** | **4.80** | **✅** |
| **case_012 OpenAI SDK** | **GitHub 真实** | **4.80** | **✅** |

**5 个 GitHub 真实项目用例全部 ≥4.80** —— Agent 能分析真实生产级代码。

### 评估方法（LLM-as-Judge）

```python
# eval/judge.py：LLM-as-Judge 评估器
JUDGE_SYSTEM = """你是 CodeInsight Agent 的质量评估专家...
按 5 个标准给 Agent 输出打分（1-5），每个标准独立评分"""
```

- 4 重 fallback JSON 解析（markdown 代码块 / 尾逗号 / 注释等）
- 每个用例 4-5 个评估标准
- pass = 所有标准 ≥3 分

### 报告格式（DEEP_ANALYSIS_REPORT_TEMPLATE）

所有模板输出强制包含：

1. **总结**（150-300 字 + 整体评级 A/B/C/D）
2. **关键发现表**（高复杂度函数 + 位置行号）
3. **核心模块解读**（≥3 个真实代码片段，```代码``` 包裹 + 行号引用）
4. **优先级建议**（≥5 条 + 🔴/🟡/🟢 标注）
5. **后续步骤**

---

## 🚀 快速开始

```bash
# 安装依赖
pip install -r requirements.txt

# 配置 .env
cp .env.example .env
# 编辑 .env 填入 OPENAI_API_KEY（必须）和 LANGFUSE_*（可选）

# 跑 Agent（CLI）
python -m agent.main --goal "分析 https://github.com/langchain-ai/langgraph/blob/main/libs/langgraph/langgraph/graph/state.py" --template deep_review

# 启动 FastAPI 服务（含 Web UI）
uvicorn api.server:app --host 0.0.0.0 --port 8000

# 跑评估
跑 eval/run_eval.py
```

---

## 🌐 FastAPI + Web UI

```bash
curl -X POST http://localhost:8000/agent/run \
  -H "Content-Type: application/json" \
  -d '{"goal": "https://github.com/...", "template": "deep_review"}'
```

接口：
- `POST /agent/run` 同步
- `POST /agent/stream` SSE 流式
- `GET /tools` 列出 MCP 工具
- `GET /sessions/{id}` 查询会话状态

---

## 📦 项目结构

```
CodeInsight-MCP/
├── mcp_server/
│   └── server.py           # MCP Server（7 个 tool）
├── agent/
│   ├── mcp_client.py       # MCP 客户端封装
│   ├── state.py            # AgentState schema
│   ├── prompts.py          # 5 套模板 + DEEP_ANALYSIS_REPORT_TEMPLATE
│   ├── graph.py            # LangGraph 状态机
│   ├── observability.py    # Langfuse 集成
│   └── main.py             # CLI 入口
├── api/
│   ├── server.py           # FastAPI 服务
│   ├── stream.py
│   └── static/index.html   # Web UI（深色主题）
├── eval/
│   ├── test_cases.json     # 12 个测试用例
│   ├── judge.py            # LLM-as-Judge
│   └── run_eval.py         # 跑全部 + 生成报告
├── tests/
│   ├── test_server.py
│   └── test_agent.py
├── examples/
│   ├── sample_repo/        # 简单示例
│   ├── langgraph_state.py  # LangGraph 真实源码（缓存）
│   └── fetched/            # fetch_url 下载缓存
├── Dockerfile              # 多阶段构建
├── docker-compose.yml
└── requirements.txt
```

---

## 🔬 关键技术点

### MCP 协议集成
- `langchain-mcp-adapters` 把 MCP 工具转为 LangChain tools
- `MultiServerMCPClient` 支持 stdio 多 server
- 自动处理 JSON-RPC 协议包装（`[{type: text, text: ...}]` → `dict`）

### 路径跟踪（fetched_files）
- Agent 在 state 里跟踪 fetch_url 下载的本地路径
- 后续工具用错路径（用 GitHub URL 而非本地路径）问题彻底解决

### 参数名容错
- LLM 写错参数名（path / file_path / local_path / filepath / dir / file）自动映射到正确参数
- 多重 fallback 确保即使 LLM 用非标准参数名也能调用成功

### 多语言支持
- `analyze_complexity` 借助 lizard 支持 Python / TypeScript / JavaScript / Java / Go / C++ / Rust
- `find_definition` 用 tree-sitter AST（Python）+ 正则兜底（其他语言）

### 可观测性（Langfuse）
- `@observe_node()` 装饰器自动追踪每个 LangGraph 节点
- 无 Langfuse 凭证时 graceful fallback
- `get_callbacks()` 注入 LLM call 的 token / latency 追踪

---

## 📝 简历项目说明

`paper-factor-system` 已覆盖：LangGraph 流水线 / interrupt 人机协同 / MemorySaver / 真实数据回测 / 多 Agent 协作（5 类Agent）。

`CodeInsight-MCP` 差异化补充：
- **MCP 协议标准工具**（行业趋势）
- **多 Agent 角色协作 + GitHub URL → 自动分析**
- **真实 GitHub 项目分析能力**（5/5 ≥4.80）
- **LLM-as-Judge 评估 pipeline**（质量可量化）

---

## 📜 License

MIT