ironmunch (Cmillstead)

codesight mcp

Security-hardened, token-efficient code intelligence for AI assistants.

一 MCP服务器 它通过树型AST解析对本地和GitHub代码库进行索引，然后公开34个用于符号检索、代码图遍历和影响分析的工具——所有这些工具都具有字节偏移精度，与发送完整文件相比，可以将令牌成本降低约99%。支持66种语言。

______________________________________________________________________

快速导航

• 特性
• 支持的语言
• 快速开始
• 工具参考
• 代码图和关系分析
• 安全模型
• Git挂钩
• 语义搜索
• 环境变量

______________________________________________________________________

特性

代码索引和检索

• 树型AST解析 跨66种语言进行字节偏移O（1）符号检索
• 增量索引 通过内容哈希——在重新索引时跳过未更改的文件
• 本地+GitHub存储库索引 --索引磁盘上的文件夹或从GitHub获取
• 人工智能生成的摘要 -用于符号描述的可选Anthropic API集成
• 全文搜索 通过支持编校的匹配跨索引文件内容
• 语义搜索 --通过设备嵌入进行混合关键字+矢量评分（可选 [semantic] 额外）

代码图和关系分析

• 呼叫者和街道 --谁调用函数，它调用什么？
• 呼叫链 --追踪任意两个符号之间的完整路径
• 类型层次结构 --继承树和接口实现
• 导入图形 --哪些文件导入什么，从哪里导入？
• 影响分析 --更改功能，查看下游受影响的所有内容

安全

• 6步路径验证链 --空字节、遍历、限制、解析、包含、符号链接
• 内容边界标记 --间接快速注射防御（微软重点研究）
• 错误清理 --原始异常永远不会到达人工智能；系统路径总是被剥离
• MCP工具注释 --readOnlyHint、destructiveHint、幂等Hint、openWorldHint在所有34个用于客户端权限决策的工具上
• 2495次测试 --具有真实临时目录的对抗性、安全性、集成性、基准测试、模糊性和压力覆盖

______________________________________________________________________

支持的语言

codesight mcp支持 66种编程语言 通过树形图，包括Python、JavaScript、TypeScript、Go、Rust、Java、C/C++、C#、Ruby、Swift、Kotlin、PHP、Dart、Perl、Haskell、Scala、Erlang等49种语言。请参阅 完整语言列表 了解详情。

每种语言解析器都提取函数、类、方法、参数、调用关系、导入和继承，以构建一个全面的代码图。

______________________________________________________________________

快速开始

步骤1：安装

# From source (recommended — not published to PyPI)
git clone https://github.com/cmillstead/codesight-mcp.git
cd codesight-mcp
uv sync            # recommended — uses lockfile with pinned versions
# or: pip install -e .  (uses version ranges, not the lockfile)

步骤2：注册MCP服务器

使用 claude mcp add 注册。这是Anthropic推荐的方法 使用MCP执行代码 模式——服务器通过MCP协议自行描述其工具，您的客户端通过以下方式自动发现它们 tools/list。不需要手动工具列表或每个工具的权限配置。

claude mcp add codesight-mcp \
  -e CODESIGHT_ALLOWED_ROOTS=/Users/you/src \
  -e GITHUB_TOKEN=ghp_... \
  -- /path/to/codesight-mcp/.venv/bin/codesight-mcp

所有34个工具包括 MCP工具注释 --每个工具都声明它是只读的、破坏性的、幂等的，还是访问外部服务的。您的MCP客户端使用这些注释自动做出权限决策，因此您不需要为每个工具单独配置权限：

步骤3：为存储库建立索引

在任何其他工具工作之前，您必须至少索引一个存储库。问你的AI：

• 本地文件夹： *“将仓库索引到~/src/myproject”*
• GitHub仓库： *“索引GitHub仓库所有者/myproject”*

AI呼叫 index_folder 或 index_repo，它获取文件、解析AST并将符号提取到 ~/.code-index/。后续调用会自动跳过未更改的文件。

第四步：探索

一旦被索引，AI就会使用 get_repo_outline, search_symbols，以及 get_symbol 导航代码库——只检索所需的符号，而不是整个文件。

步骤5（可选）：将CLAUDE.md添加到索引存储库

添加一个 CLAUDE.md 对于每个索引仓库，Claude Code更喜欢codesight mcp而不是读取完整文件：

## Code Navigation

This repo is indexed in codesight-mcp. Use codesight-mcp MCP tools for code
exploration instead of reading full files:

- `search_symbols` — find functions/classes/types by name or description
- `get_file_outline` — all symbols in a file with signatures
- `get_symbol` — full source of a specific symbol
- `get_repo_outline` — directory structure and language breakdown
- `get_callers` / `get_callees` — call graph navigation
- `get_call_chain` — trace execution paths between two symbols
- `get_impact` — see what's affected by changing a symbol

Use `Read` only for content that isn't a named symbol (config files, etc).

______________________________________________________________________

工具

codesight mcp曝光 34个MCP工具 分为八类：

索引

导航

搜索

代码图

分析和可视化

安全

依赖和困难

______________________________________________________________________

自然语言示例

索引后，使用简单的英语通过您的AI助手进行交互：

查找代码

• *“在哪里 process_payment 功能？"*
• *“显示与身份验证相关的所有类”*
• *“查找处理数据库连接的任何代码”*

理解关系

• *“什么函数调用 validate_input?"*
• *“什么 initialize_system 打电话？"*
• *“向我展示来自的完整呼叫链 main 到 process_data"*
• *“继承层次是什么 BaseController?"*

影响分析

• *“如果我改变 calculate_tax，还有什么受到影响？"*
• *“哪些文件导入 utils 模块？"*
• *“让我看看下游的一切 authenticate_user"*

探索结构

• *“请概述此存储库”*
• *“里面有什么符号 src/server.py?"*
• *“列出所有索引仓库”*

______________________________________________________________________

代码图和关系分析

codesight mcp根据AST解析过程中提取的关系构建内存中的代码图。不需要外部图数据库——图使用在查询时根据符号索引构造的集合邻接表的字典。

它是如何工作的：

1. 在索引过程中，AST解析器提取 calls, imports，以及 inherits_from 每个符号的关系
2. 这些关系与JSON索引中的符号元数据一起存储
3. 在查询时， CodeGraph.build(symbols) 从符号字典构造图
4. 图形工具（调用者、被调用者、调用链、影响）使用具有循环检测的BFS遍历此结构

与...相比 CodeGraphContext: codesight mcp不使用外部数据库（FalkorDB/Neo4j）。权衡是简单性和零配置与处理大量图形的能力。对于大多数项目（数千个文件），内存中的方法是快速且足够的。

______________________________________________________________________

Git钩子：提交和推送时自动重新索引

codesight mcp包括自动保持索引最新的git挂钩：

在任何仓库中安装：

cp /path/to/codesight-mcp/hooks/post-commit .git/hooks/post-commit
cp /path/to/codesight-mcp/hooks/post-push   .git/hooks/post-push
chmod +x .git/hooks/post-commit .git/hooks/post-push

这两个钩子都在后台运行，因此它们永远不会阻塞您的工作流程。移除 --no-ai 如果你想自动更新人工智能生成的摘要，可以从任一钩子中选择。

一次性设置 --git钩子不继承shell环境，因此凭据和二进制路径必须单独提供：

mkdir -p ~/.config/codesight-mcp
cat > ~/.config/codesight-mcp/env <<'EOF'
export GITHUB_TOKEN=ghp_...
export CODESIGHT_BIN=/path/to/.venv/bin/codesight-mcp
EOF
chmod 600 ~/.config/codesight-mcp/env

您还可以直接从命令行进行索引：

codesight-mcp index ~/src/myproject              # index a local folder
codesight-mcp index ~/src/myproject --no-ai     # skip AI summaries (faster)
codesight-mcp index-repo owner/myproject        # index a GitHub repo

______________________________________________________________________

安全模型

codesight mcp将连接的AI视为不受信任的主体。每个工具参数在使用前都经过验证。索引中的每个文件路径在检索时都会重新验证。错误消息经过净化，因此系统路径永远不会泄漏。

看 安全.md 了解完整的威胁模型、防御矩阵和验证链的详细信息。关键安全决策的架构决策记录在 文件/决定/.

______________________________________________________________________

数据处理

当 ANTHROPIC_API_KEY 设置时，codesight-mcp将函数和类签名发送到Anthropic API，用于索引期间生成的AI摘要。不发送源代码，只发送签名。要禁用，请省略 ANTHROPIC_API_KEY 环境变量。

______________________________________________________________________

环境变量

______________________________________________________________________

语义搜索

按意图搜索，而不是按确切名称搜索。需要 semantic 额外：

pip install codesight-mcp[semantic]   # adds fastembed (~100MB ONNX runtime + model weights)

如果没有这个额外的参数，传递语义参数会返回一个有用的错误，解释要安装什么。

参数

例子

# Find by intent, not exact name
search_symbols(query="the function that validates credentials", semantic=True)

# Pure semantic search
search_symbols(query="password hashing utility", semantic_only=True)

环境变量

运作原理

嵌入在第一个语义查询上延迟生成，并与索引一起缓存在gzip JSON sidecar文件中。重新索引时，缓存会自动失效。默认提供程序完全在设备上运行，没有API调用。当 semantic=false （默认设置），开销为零——嵌入从不加载或计算。

关键字评分包括复合标识符拆分(hash_password → {hash, password}, AuthManager → {auth, manager})后缀词干(hashing → hash, validates → validate)，因此即使没有启用语义搜索，基于意图的查询也会匹配。

______________________________________________________________________

归因

许可证

麻省理工学院——见 许可证.