内容
<p align="center">
<img src="assets/codesteward-logo.png" alt="Codesteward" width="320" />
</p>
<p align="center">
<a href="https://pypi.org/project/codesteward-mcp/"><img src="https://img.shields.io/pypi/v/codesteward-mcp?color=0078d4&label=codesteward-mcp" alt="PyPI codesteward-mcp"></a>
<a href="https://pypi.org/project/codesteward-graph/"><img src="https://img.shields.io/pypi/v/codesteward-graph?color=00b4d8&label=codesteward-graph" alt="PyPI codesteward-graph"></a>
<a href="https://github.com/Codesteward/codesteward-graph/releases"><img src="https://img.shields.io/github/v/release/Codesteward/codesteward-graph?color=1a1a2e&label=release" alt="GitHub Release"></a>
<a href="https://pypi.org/project/codesteward-mcp/"><img src="https://img.shields.io/pypi/pyversions/codesteward-mcp" alt="Python Versions"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue" alt="License"></a>
</p>
<p align="center">
<strong>结构化代码图服务器，适用于 AI 代理。</strong><br>
将任何代码仓库解析为可查询的图，借助 tree-sitter AST — 并将其作为 MCP 工具接口暴露给 AI 代理直接调用。支持 Neo4j、JanusGraph 或 GraphQLite（嵌入式 SQLite — 零设置本地开发）。
</p>
---
## 功能介绍
Codesteward 将您的代码库解析为持久的结构图，并暴露四个 [模型上下文协议](https://modelcontextprotocol.io) 工具，AI 代理（Claude Code、Cursor、Windsurf、Copilot 等）可以调用这些工具来回答问题，例如：
- *"哪些函数受 JWT 身份验证保护？*"
- *"`process_payment` 调用哪些函数，传递？*"
- *"哪些文件依赖于此外部包？*"
- *"此路由是否受身份验证中间件保护？*"
代理不会重复扫描文件，而是查询预建的图 — 跨文件关系、调用链、身份验证保护和依赖边框在单个查询中全部解析。
**支持的语言：** TypeScript · JavaScript · Python · Java · Go · Rust · PHP · C# · Kotlin · Scala · C · C++ · SQL *(上下文标记)* · COBOL *(正则表达式)*
## MCP 工具
| 工具 | 描述 |
| ---- | ----------- |
| `graph_rebuild` | 解析代码仓库并将结构图写入配置的后端（Neo4j、JanusGraph 或 GraphQLite）或运行 stub 模式 |
| `codebase_graph_query` | 通过命名模板（`lexical`、`referential`、`semantic`、`dependency`）或原始直通（`cypher` / `gremlin`）查询 |
| `graph_augment` | 将代理推断的关系（置信度 < 1.0）添加到图中 |
| `graph_status` | 返回元数据：节点/边计数、最后构建时间、Neo4j 连接性 |
| `taint_analysis` | *(可选)* 通过 `codesteward-taint` 二进制文件运行污点流分析，并将 `TAINT_FLOW` 边写入 Neo4j |
## Claude Code 插件
使用 Claude Code 的最快方式是官方插件 — 它连接 MCP 服务器并安装三个专注的技能（`/codesteward`、`/codesteward-security`、`/codesteward-deps`）：
```bash
claude plugin marketplace add codesteward/codesteward-plugin
claude plugin install codesteward@codesteward
```
不需要单独的服务器设置。插件自动启动 `codesteward-mcp`，并通过 `uvx` 使用 GraphQLite 后端。有关详细信息，请参阅 **[codesteward-plugin](https://github.com/codesteward/codesteward-plugin)**。
对于其他 AI 工具（Cursor、Cline、Codex、Gemini）或替代后端（Neo4j、JanusGraph），请使用下面的快速入门。
---
## 快速入门
### 自动设置（推荐）
一次性设置。在您的机器上所有代码仓库都适用，无需每个项目配置。
```bash
uvx --from "codesteward-mcp[graph-all,graphqlite]" codesteward-mcp setup
```
此操作会自动检测您的 AI 工具（Claude Code、Cursor、Cline、Codex CLI、Gemini CLI），在全局注册 MCP 服务器，并将工作流指令合并到现有的配置文件中 — 不会覆盖任何内容。
默认使用 **GraphQLite**：一个嵌入式 SQLite 图，它持续到 `~/.codesteward/graph.db`。无需 Docker，无需数据库服务器，无需后台进程。
要删除所有内容：`uvx --from "codesteward-mcp[graph-all,graphqlite]" codesteward-mcp setup --uninstall`
**前提条件：** [uv](https://docs.astral.sh/uv/) · *(可选)* [`codesteward-taint`](https://github.com/Codesteward/codesteward-taint/releases) 在 `PATH`
#### 用法 — 打开任何代码仓库并开始提问
```bash
cd /path/to/your/project
claude # 或：cursor, cline, codex, gemini
```
```text
# 代理将自动：
graph_status(repo_id="my-project")
graph_rebuild(repo_path="/path/to/your/project", repo_id="my-project") # 如果过期
codebase_graph_query(query_type="referential", query="authenticate", repo_id="my-project")
```
无需 `.mcp.json`，无需每个项目配置，无需重复设置。
有关手动工具设置、Docker 部署和替代后端（Neo4j、JanusGraph）的详细信息，请参阅 **[设置指南](docs/setup/)**。
### 手动设置 — GraphQLite（本地开发，无服务器）
如果您更喜欢手动配置，请在 MCP 客户端配置文件中添加以下内容：
```json
{
"mcpServers": {
"codesteward-graph": {
"type": "stdio",
"command": "uvx",
"args": [
"--from", "codesteward-mcp[graph-all,graphqlite]",
"codesteward-mcp", "--transport", "stdio"
]
}
}
}
```
> **注意：** Claude Code 需要在服务器配置中设置 `"type": "stdio"`。其他工具
> （Cursor、Cline）不需要。
| 工具 | 配置文件 |
| ---- | ----------- |
| Claude Code | `~/.claude.json`（在 `mcpServers` 下） |
| Cursor | `~/.cursor/mcp.json` |
| Cline | VS Code 全局存储中的 `cline_mcp_settings.json` |
| Codex CLI | `~/.codex/config.yaml`（在 `mcp_servers` 下） |
| Gemini CLI | `~/.gemini/settings.json`（在 `mcpServers` 下） |
需要 [uv](https://docs.astral.sh/uv/)。`uvx` 在首次运行时下载并缓存软件包。图持续到 `~/.codesteward/graph.db`，跨会话。
### Docker + Neo4j — 持久图
```bash
# 1. 将服务器指向您的代码仓库
export REPO_PATH=/path/to/your/repository
# 2. 启动 Neo4j + MCP 服务器
docker compose -f docker-compose.neo4j.yml up -d
# 3. 将配置文件模板复制到要分析的代码仓库中
cp templates/.mcp.json /path/to/your/repository/
cp templates/CLAUDE.md /path/to/your/repository/
```
服务器运行在 **`http://localhost:3000/sse`**。调用 `graph_rebuild()` 时不带参数 — 服务器已经知道仓库路径从卷 mount。
### Docker + JanusGraph — 持久图（Apache 2.0）
```bash
# 1. 将服务器指向您的代码仓库
export REPO_PATH=/path/to/your/repository
# 2. 启动 JanusGraph + MCP 服务器
docker compose -f docker-compose.janusgraph.yml up -d
# 3. 将配置文件模板复制到要分析的代码仓库中
cp templates/.mcp.json /path/to/your/repository/
cp templates/CLAUDE.md /path/to/your/repository/
```
与 Neo4j 堆栈相同的工作流程 — 所有命名查询模板的工作方式相同。原始查询直通使用 Gremlin 代替 Cypher。
### 手动 Docker 运行
```bash
docker run -p 3000:3000 \
-v /path/to/your/repo:/repos/project:ro \
-e NEO4J_PASSWORD=secret \
ghcr.io/codesteward/codesteward-graph:latest
```
有关涵盖所有 AI 工具的完整设置说明，请参阅 **[设置指南](docs/setup/)**。
## 安装
```bash
# 所有 14 种语言 + GraphQLite（推荐用于本地开发）
uv pip install "codesteward-mcp[graph-all,graphqlite]"
# 核心语言（TypeScript、JavaScript、Python、Java）+ GraphQLite
uv pip install "codesteward-mcp[graph,graphqlite]"
# 单个语言扩展
uv pip install "codesteward-mcp[graph-go,graphqlite]" # Go
uv pip install "codesteward-mcp[graph-rust,graphqlite]" # Rust
uv pip install "codesteward-mcp[graph-csharp,graphqlite]" # C#
uv pip install "codesteward-mcp[graph-kotlin,graphqlite]" # Kotlin
uv pip install "codesteward-mcp[graph-scala,graphqlite]" # Scala
uv pip install "codesteward-mcp[graph-c,graphqlite]" # C
uv pip install "codesteward-mcp[graph-cpp,graphqlite]" # C++
uv pip install "codesteward-mcp[graph-php,graphqlite]" # PHP
# Neo4j 后端（替代方案 — 需要运行的 Neo4j 5+ 服务器）
uv pip install "codesteward-mcp[graph-all]"
# JanusGraph 后端（替代方案 — 需要运行的 JanusGraph 1.0+ 服务器）
uv pip install "codesteward-mcp[graph-all,janusgraph]"
```
需要 Python 3.12+。GraphQLite 是本地开发的默认后端 — 一个嵌入式 SQLite 图数据库，无需外部服务。图持续到 `~/.codesteward/graph.db`，跨会话。
## 配置
所有设置都可以通过环境变量、YAML 配置文件或 CLI 标志提供。
优先级：**CLI 标志 > 环境变量 > YAML 文件 > 默认值**。
| 设置 | 环境变量 | 默认值 | 描述 |
| ------- | ------- | ------- | ----------- |
| 传输 | `TRANSPORT` | `sse` | `sse`、`http` 或 `stdio` |
| 主机 | `HOST` | `0.0.0.0` | HTTP 绑定主机 |
| 端口 | `PORT` | `3000` | HTTP 绑定端口 |
| 图后端 | `GRAPH_BACKEND` | `auto` | `auto`、`neo4j`、`janusgraph` 或 `graphqlite`。自动检测：Neo4j 如果设置密码，JanusGraph 如果 URL 更改，否则 GraphQLite |
| Neo4j URI | `NEO4J_URI` | `bolt://localhost:7687` | Neo4j 连接 URI |
| Neo4j 用户 | `NEO4J_USER` | `neo4j` | Neo4j 用户名 |
| Neo4j 密码 | `NEO4J_PASSWORD` | *(空)* | 设置以启用 Neo4j 后端 |
| JanusGraph URL | `JANUSGRAPH_URL` | `ws://localhost:8182/gremlin` | Gremlin 服务器 WebSocket URL |
| GraphQLite DB 路径 | `GRAPHQLITE_DB_PATH` | `~/.codesteward/graph.db` | SQLite 数据库文件路径 |
| 默认租户 | `DEFAULT_TENANT_ID` | `local` | 租户命名空间 |
| 默认代码仓库 | `DEFAULT_REPO_ID` | *(空)* | 代码仓库 ID |
| 默认代码仓库路径 | `DEFAULT_REPO_PATH` | `/repos/project` | `graph_rebuild` 的服务器端路径 |
| 工作空间 | `WORKSPACE_BASE` | `workspace` | 构建元数据目录 |
| 日志级别 | `LOG_LEVEL` | `INFO` | `DEBUG` / `INFO` / `WARNING` / `ERROR` |
## 污点分析（可选）
`taint_analysis` 工具在 `codesteward-taint` 二进制文件位于
`PATH` 时自动注册。没有它，服务器正常启动，其他四个工具不受影响。
### Docker
将 `--build-arg TAINT_VERSION=<version>` 传递以下载和绑定二进制文件：
```bash
docker build --build-arg TAINT_VERSION=0.1.0 -t codesteward-mcp:taint .
```
### 独立
从
[codesteward-taint 发行版](https://github.com/Codesteward/codesteward-taint/releases) 下载预构建的二进制文件并将其放在
`PATH` 上：
```bash
# macOS (Apple Silicon)
curl -L https://github.com/Codesteward/codesteward-taint/releases/latest/download/codesteward-taint-darwin-arm64 \
-o /usr/local/bin/codesteward-taint
chmod +x /usr/local/bin/codesteward-taint
```
### 工作流程
```text
graph_rebuild # 首先构建结构图
taint_analysis # 跟踪污点路径；将 TAINT_FLOW 边写入 Neo4j
codebase_graph_query # 查询类型="semantic" 读取查找结果
```
## 图模型
### 节点 — `LexicalNode`
每个解析的符号成为一个 `LexicalNode`：
| 属性 | 描述 |
| -------- | ----------- |
| `node_id` | 稳定唯一 ID：`{node_type}:{tenant_id}:{repo_id}:{file}:{name}` |
| `node_type` | `function`、`class`、`method`、`file`、`module`、`external` |
| `name` | 符号名称 |
| `file` | 仓库相对文件路径 |
| `line_start` / `line_end` | 源位置 |
| `language` | 检测到的语言 |
| `tenant_id` / `repo_id` | 多租户命名空间 |
| `confidence` | `1.0` 为解析器发出；`< 1.0` 为代理推断 |
### 边
| 边类型 | 含义 |
| --------- | ------- |
| `CALLS` | 函数 A 调用函数 B（跨文件解析） |
| `IMPORTS` | 文件/模块导入另一个 |
| `EXTENDS` | 类继承自另一个 |
| `GUARDED_BY` | 函数受装饰器/注解保护（`@login_required`、`@UseGuards`、FastAPI `Depends`、`@PreAuthorize`、…） |
| `PROTECTED_BY` | 函数受路由器范围中间件保护（`APIRouter`、Express `router.use()`、Gin group、Actix scope、Laravel route group、ASP.NET `MapGroup().RequireAuthorization()`） |
| `DEPENDS_ON` | 文件依赖外部包 |
| `TAINT_FLOW` | 不受信任的输入到达危险的接收点（由 `codesteward-taint` 编写；可通过 `semantic` 查询） |
| `calls` / `guarded_by` / `taint_flow` / … | 代理推断边，置信度 < 1.0 通过 `graph_augment` |
## 开发
```bash
# 设置
uv venv && source .venv/bin/activate
uv sync --all-packages --extra graph-all
# 运行测试
pytest tests/ -v
# 本地运行服务器
codesteward-mcp --transport sse --port 3000
# Lint + 类型检查
ruff check src/ tests/
mypy src/
```
## 发行版
查看 [CHANGELOG.md](CHANGELOG.md) 获取完整历史记录或浏览 [GitHub Releases](https://github.com/Codesteward/codesteward-graph/releases)。
## 许可证
Apache License 2.0 — Copyright (c) 2026, bitkaio LLC
