AI导哈

代码结构图服务器

Codesteward是一款将代码库解析为可查询结构图的服务，通过Model Context Protocol工具为AI代理提供代码分析功能，支持多种编程语言和图数据库后端。

  • by Codesteward
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 bitkaio/codesteward

使用说明

Structural code graph server for AI agents.
Parse any repository into a queryable graph via tree-sitter AST — and expose it as an MCP tool interface your AI agent can call directly. Supports Neo4j, JanusGraph, or GraphQLite (embedded SQLite — zero setup for local dev).

它的作用

Codesteward将您的代码库解析为持久结构图，并公开四个 模型上下文协议 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）或在存根模式下运行
codebase_graph_query 通过命名模板查询(lexical, referential, semantic, dependency)或直接通过(cypher / gremlin)
graph_augment 将代理推断的关系（置信度<1.0）添加回图中
graph_status 返回元数据：节点/边计数、上次构建时间、Neo4j连接
taint_analysis （可选） 通过运行污染流分析 codesteward-taint 二进制和写入 TAINT_FLOW 边缘到Neo4j

Claude代码插件

将Codesteward与Claude Code结合使用的最快方法是使用官方插件——它连接MCP服务器并安装三个重点技能(/codesteward, /codesteward-security, /codesteward-deps):

claude plugin marketplace add codesteward/codesteward-plugin
claude plugin install codesteward@codesteward

不需要单独的服务器设置。插件自动启动 codesteward-mcp 通过GraphQLite后端 uvx。请参阅 codesteward插件 了解全部细节。

对于其他AI工具（Cursor、Cline、Codex、Gemini）或替代后端（Neo4j、JanusGraph），请使用下面的快速入门。

快速开始

自动设置（推荐）

一次性设置。无需任何项目配置，即可在计算机上的每个存储库中工作。

uvx --from "codesteward-mcp[graph-all,graphqlite]" codesteward-mcp setup

此功能会自动检测您的AI工具（Claude Code、Cursor、Cline、Codex CLI、Gemini CLI），全局注册MCP服务器，并将工作流指令合并到现有的配置文件中——不会覆盖任何内容。

用途 石墨烯 默认情况下：一个嵌入式SQLite图 ~/.codesteward/graph.db没有Docker，没有数据库服务器，没有后台进程。

要删除所有内容： uvx --from "codesteward-mcp[graph-all,graphqlite]" codesteward-mcp setup --uninstall

先决条件： 紫外线 · （可选） codesteward-taint 上 PATH

用法——打开任何仓库并开始询问

cd /path/to/your/project
claude   # or: cursor, cline, codex, gemini

# The agent will automatically:
graph_status(repo_id="my-project")
graph_rebuild(repo_path="/path/to/your/project", repo_id="my-project")   # if stale
codebase_graph_query(query_type="referential", query="authenticate", repo_id="my-project")

不 .mcp.json，没有每个项目的配置，没有重复的设置。

有关手动按工具设置、Docker部署和替代后端（Neo4j、JanusGraph），请参阅 设置指南.

手动设置--GraphQLite（本地开发，无服务器）

如果您更喜欢手动配置，请将此添加到MCP客户端配置中：

{
  "mcpServers": {
    "codesteward-graph": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from", "codesteward-mcp[graph-all,graphqlite]",
        "codesteward-mcp", "--transport", "stdio"
      ]
    }
  }
}

注： 克劳德代码要求 "type": "stdio" 在服务器配置中。其他工具 （Cursor，Cline）不需要它。

工具 配置文件
克劳德代码 ~/.claude.json （根据 mcpServers)
光标 ~/.cursor/mcp.json
克莱恩 cline_mcp_settings.json 在VS代码全局存储中
Codex CLI ~/.codex/config.yaml （根据 mcp_servers)
Gemini CLI ~/.gemini/settings.json （根据 mcpServers)

需要 紫外线. uvx 首次运行时下载并缓存该包。图表持续到 ~/.codesteward/graph.db 跨届会议。

Docker+Neo4j——持久图

# 1. Point the server at your repository
export REPO_PATH=/path/to/your/repository

# 2. Start Neo4j + MCP server
docker compose -f docker-compose.neo4j.yml up -d

# 3. Copy config templates into the repo you want to analyse
cp templates/.mcp.json /path/to/your/repository/
cp templates/CLAUDE.md /path/to/your/repository/

服务器运行在 http://localhost:3000/sse.致电 graph_rebuild() 没有参数——服务器已经知道卷装载的repo路径。

Docker+JanusGraph——持久图（Apache 2.0）

# 1. Point the server at your repository
export REPO_PATH=/path/to/your/repository

# 2. Start JanusGraph + MCP server
docker compose -f docker-compose.janusgraph.yml up -d

# 3. Copy config templates into the repo you want to analyse
cp templates/.mcp.json /path/to/your/repository/
cp templates/CLAUDE.md /path/to/your/repository/

与Neo4j堆栈相同的工作流程——所有命名查询模板的工作方式都相同。原始查询传递使用Gremlin而不是Cypher。

手动运行Docker

docker run -p 3000:3000 \
  -v /path/to/your/repo:/repos/project:ro \
  -e NEO4J_PASSWORD=secret \
  ghcr.io/codesteward/codesteward-graph:latest

有关涵盖所有AI工具的完整设置说明，请参阅 设置指南.

安装

# All 14 languages + GraphQLite (recommended for local dev)
uv pip install "codesteward-mcp[graph-all,graphqlite]"

# Core languages only (TypeScript, JavaScript, Python, Java) + GraphQLite
uv pip install "codesteward-mcp[graph,graphqlite]"

# Individual language extras
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 backend (alternative — requires a running Neo4j 5+ server)
uv pip install "codesteward-mcp[graph-all]"

# JanusGraph backend (alternative — requires a running JanusGraph 1.0+ server)
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，URL更改为JanusGraph，否则为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数据库路径 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没有它，服务器正常启动，其他四个工具不受影响。

码头工人

通过 --build-arg TAINT_VERSION=<version> 下载并捆绑二进制文件：

docker build --build-arg TAINT_VERSION=0.1.0 -t codesteward-mcp:taint .

独立

从下载预构建的二进制文件 codesteward污点发布 并将其放置 上 PATH:

# 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

工作流

graph_rebuild          # build the structural graph first
taint_analysis         # trace taint paths; writes TAINT_FLOW edges to Neo4j
codebase_graph_query   # query_type="semantic" to read findings

图形模型

节点-- 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，快递 router.use()Gin组，Actix范围，Laravel路由组，ASP。网 MapGroup().RequireAuthorization())
DEPENDS_ON 文件依赖于外部包
TAINT_FLOW 不受信任的输入到达危险的水槽（由 codesteward-taint；可通过以下方式查询 semantic)
calls / guarded_by / taint_flow /… 代理通过以下方式推断出边 confidence < 1.0 通过 graph_augment

发展

# Setup
uv venv && source .venv/bin/activate
uv sync --all-packages --extra graph-all

# Run tests
pytest tests/ -v

# Run the server locally
codesteward-mcp --transport sse --port 3000

# Lint + type-check
ruff check src/ tests/
mypy src/

发布

看 更改日志.md 查看完整历史记录或浏览 GitHub发布.

许可证

Apache许可证2.0--版权所有（c）2026，bitkaio LLC

相关 MCP