# mcp-backend-trace

**Repository Path**: le0zj/mcp-backend-trace

## Basic Information

- **Project Name**: mcp-backend-trace
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-31
- **Last Updated**: 2026-05-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# @le0zj/mcp-backend-trace

MCP Server for Java Spring Cloud 后端链路追踪。

扫描 `@RequestMapping` Controller，沿 Spring 调用链追踪 Service → Feign → 子服务实现，支持跨微服务 Feign 调用链追踪。

## Tools

| 工具 | 说明 |
|------|------|
| `index_backend` | 初始化后端链路追踪索引（扫描 Controller，生成端点索引） |
| `search_endpoints` | 按 URL / 关键词 / HTTP 方法搜索端点 |
| `trace_call_chain` | 从 Controller 追踪完整调用链（Service → Feign → 子服务） |
| `get_code_block` | 读取指定文件的代码块 |
| `list_projects` | 显示当前目录的索引状态 |

## Install

```bash
npm install -g @le0zj/mcp-backend-trace
# 或直接用 npx
```

## 快速开始

### 1. 全局注册一次

```bash
claude mcp add backend-trace -- npx @le0zj/mcp-backend-trace
```

### 2. 进到项目目录，启动 Claude Code

```bash
cd D:/code/edu-platform
claude
```

### 3. 直接对话

```
> 初始化后端索引

> 只扫描 api-gateway 和 user-service 的 Controller
→ index_backend({ modules: ["api-gateway", "user-service"] })

> 追踪 /v3/channel/list 的调用链
> 搜索包含 "user" 的端点
> 读取 UserController.java 第 50-80 行
```

所有工具的 `project` 参数可选，默认用当前目录。

## modules 参数

`index_backend` 支持 `modules` 参数，只扫描指定的入口子目录。链路追踪从 Controller 入口出发即可，不需要扫描所有子项目的 Controller：

```
D:/code/edu-platform/
├── api-gateway/       ← 入口项目，有 Controller
├── user-service/      ← 入口项目，有 Controller
├── order-service/     ← 内部服务，没有对外的 Controller
└── channel-service/   ← 入口项目，有 Controller
```

```bash
# 只扫描入口项目的 Controller（更快、结果更精准）
> 只扫描 api-gateway、user-service 和 channel-service

# 扫描全部（默认）
> 初始化后端索引
```

## 项目结构说明

每个"项目"是一个 **Spring Cloud 微服务集合**（一组有互相调用关系的子服务放在同一目录下）。工具会递归扫描目录下所有 `.java` 文件，自动识别跨服务 Feign 调用链。

```
D:/code/edu-platform/              ← 一个项目（cd 进这里）
├── user-service/                  ← 微服务 A
├── order-service/                 ← 微服务 B（Feign 调用 A）
├── channel-service/               ← 微服务 C（Feign 调用 B）
└── api-gateway/
```

调用链追踪示例：

```
[v3/channel/list] ChannelController.list()          ← channel-service
├── [service] ChannelServiceImpl.queryChannels()
│   ├── [api] UserFeignClient.getUsers()             ← Feign 跨服务调用
│   │   └── [service] UserServiceImpl.getUsers()     ← user-service
│   └── [mapper] ChannelMapper.selectList()
```

## 索引数据

索引文件存在项目目录的 `.index/` 下，各项目独立：

```
D:/code/edu-platform/.index/controller_urls.json    ← edu-platform 的索引
D:/code/another-system/.index/controller_urls.json  ← another-system 的索引
```

进到不同项目目录，各自维护自己的索引，互不影响。

## Environment Variables

| 变量 | 必须 | 说明 |
|------|------|------|
| — | — | 无需环境变量 |

## Requirements

- Node.js >= 18
- Java source projects with Spring `@RequestMapping` annotations

## License

MIT