Kodama MCP

儿玉MCP

木霊 — tree spirit

用于AI代理的AST感知代码探索MCP服务器，针对令牌效率进行了优化。

为什么是儿玉？

AI代理浪费令牌读取整个文件并猜测代码结构。Kodama使用树状图解析您的代码，将其索引到SQLite中，并精确地提供代理所需的服务——仅此而已。

• 三策略搜索 --使用交互排名融合（RRF）同时搜索符号名称、文档字符串和完整源代码，以及支持导入的重新排名
• **每个结果\

bunx kodama-mcp          # one-off run from npm
bun add -g kodama-mcp    # global install

MCP客户端配置

使用 bun x （带空格）而不是 bunx.MCP主机启动器（Claude Desktop、Cursor等）继承了一个最小的PATH，该PATH通常不包括 ~/.bun/bin，所以 bunx 可能无法解决 bun 它本身通常会这样做。如果两者都不起作用，请回到绝对路径——参见 故障排除.

{
  "mcpServers": {
    "kodama": {
      "command": "bun",
      "args": ["x", "kodama-mcp"]
    }
  }
}

要使用全局存储模式（所有项目共享一个数据库）：

{
  "mcpServers": {
    "kodama": {
      "command": "bun",
      "args": ["x", "kodama-mcp"],
      "env": { "KODAMA_STORAGE": "global" }
    }
  }
}

从源代码运行（开发）

git clone https://github.com/krazke/kodama-mcp.git
cd kodama-mcp
bun install
bun run start

然后将您的MCP客户端指向 bun run /absolute/path/to/kodama-mcp/src/index.ts.

工具

儿玉公开了5个MCP工具。Claude Code自动延迟MCP工具模式——它们是根据需要从延迟目录加载的，而不是生活在实时系统提示符中。

kodama_explore

从四个细节层次探索代码结构。

• 概述 （无路径）--项目统计信息：文件数、符号数、语言
• 树 （目录路径）--包含符号计数的文件列表
• 轮廓 （文件路径）--文件中带有签名和行号的符号
• 细节 （文件路径）--文件的完整源代码

kodama_search

按名称、内容或概念搜索代码。自动对查询意图进行分类，并选择最佳搜索策略。

kodama_index

为项目建立索引或重新建立索引。通常在第一次探索/搜索呼叫时自动触发。

对于monorepos， kodama_index 自动检测工作区包并为每个包建立索引。输出显示每个包的细分：

Indexed 3 workspace packages (73 files, 161 symbols, 340ms)
  packages/core: 25 files, 62 symbols
  packages/server: 15 files, 28 symbols
  packages/shared: 4 files, 15 symbols

kodama_get_symbol

按ID获取一个或多个符号的完整源代码。

kodama_relationships

获取符号的调用者、被调用者、继承、一致性等。

关系类型： calls, called_by, inherits, inherited_by, conforms, conformed_by, implements, implemented_by, overrides, overridden_by, contains, contained_in

工作流示例

explore (overview)     → see project stats, confirm indexing
  ↓
search "AuthManager"   → find symbols by name
  ↓
get_symbol [id]        → read full source of a match
  ↓
relationships [id]     → see what calls it, what it inherits

支持的语言

第一阶段 --TypeScript(.ts, .tsxpython.py)，斯威夫特(.swift)

第2阶段 --去吧(.go)，生锈(.rsJava.java)，科特林(.kt, .ktsC.cC.cpp, .cxx, .cc, .hpp, .hxxC.cs)，Objective-C(.m, .mm, .h)

第三期 --红宝石(.rb, .rake)，PHP(.php)，卢(.lua)，壳牌(.sh, .bash, .zsh)，灵丹妙药(.ex, .exs)，Scala(.scala)

特别支持： Swift协议/扩展/参与者，Objective-C类别，Python方法与函数检测，Kotlin数据类。

运作原理

+--------------+     +---------------+     +-----------------+
|  MCP Client  |---->|  Tool Router  |---->|  Auto-Indexer   |
|  (AI Agent)  || |fts_symbol|fts_docs| |
                  +---------+         | | unicode61| porter | |
                                      | +----------+--------+ |
                                      | |fts_src |file_import| |
                                      | | trigram|   graph   | |
                                      | +--------+-----------+ |
                                      +------------------------+

搜索管道

1. 意图分类 --查询被分类为 symbol_name （CamelCase、snake_case）， literal （引用字符串、路径），或 concept （自然语言）
2. 三索引查询 --每个查询最多运行三个FTS5索引：

- fts_symbols --unicode61标记器，匹配符号名称和签名 - fts_docs --波特词干，匹配文档字符串和摘要 - fts_source --三元组标记器，匹配原始源内容

1. RRF融合 --结果与意图调整的权重合并：

导入感知评分

当 context_file 提供给 kodama_search，根据导入图的接近度对结果进行重新排序。由上下文文件直接导入（或导入）的文件得到增强；远处的文件会受潮。

升压使用衰减函数： boost(d) = max(0.3, 0.7^d) 哪里 d 是导入图中的最短路径距离：

目前支持导入提取 TypeScript 和 python。其他语言工作正常——它们只是不提供导入边，所以没有应用增强。

Monrepo/工作区支持

Kodama会自动检测并索引monorepo工作区包。当您对monorepo根进行索引时，所有包都会被发现并作为单独的项目进行索引，这些项目按其共享的git根进行分组。

支持的工作区类型：

所有搜索和浏览命令都会自动跨越工作区中的所有包。独立（非工作区）项目的工作方式与以前相同。

已知限制：

• 每个项目的导入图保持不变（计划用于第6b阶段的跨项目边）
• 没有TOML/YAML/XML解析器deps——所有清单解析都使用正则表达式/逐行

增量索引

儿玉尽可能避免完全重新索引：

1. Git 差异 （首选）--比较HEAD SHA以检测添加/修改/删除的文件
2. 哈希差异 （非git repos的回退）——存储与当前文件哈希的SHA-256比较
3. 全文索引 （冷启动）——仅当不存在先前指标时

设计说明

• 测试文件按设计显示0个符号。 测试框架调用(describe, test, it)都是 call_expression AST节点，而不是声明——它们不是作为可索引符号提取的。测试文件仍被索引以进行源代码搜索：使用 kodama_search 随着 scope: "source" 在测试体中查找代码。
• 未解决的跨包关系 不显示行号。当被调用方是外部的或未解析的（在任何索引项目中都找不到）时，无法查找其目标——关系仅按名称显示，没有文件路径或行引用。
• 模块级变量声明 （例如，Zod模式、箭头函数组件、导出常量）不作为符号提取。这些是 variable_declaration AST节点——只有命名声明（函数、类、类型、接口）被索引。使用 kodama_search 随着 scope: "source" 找到基于变量的定义。

文件监视

文件监视器以300ms的去抖动时间监视源文件，触发对更改的增量重新索引。标准目录(node_modules, .git, build, dist, __pycache__, target等等）被排除在外。

演出

在您的机器上运行基准测试：

bun run benchmark                    # Default benchmarks
bun run benchmark -- --project .     # Benchmark against current directory
bun run benchmark:scale              # Large-scale benchmarks

安全

儿玉包括 文件管理员，一个防止不安全文件访问的安全层：

• 二进制检测 --75个被阻止的扩展（可执行文件、图像、存档、字体、编译的字节码等）加上基于内容的二进制检测
• Symlink防逃逸 --所有符号链接都已解析和验证，以保持在项目根目录中
• 机密文件过滤 — .env 文件、SSH密钥、凭据、证书和其他敏感文件被排除在索引之外
• 文件大小限制 --跳过超过1MB的文件
• 路径验证 --全部 detail-根据安全策略验证级别读取

存储

Kodama将索引持久化到磁盘，因此后续会话跳过重新索引。有三种存储模式可供选择：

配置

添加 .kodama/ 到你的项目 .gitignore:

.kodama/

架构版本控制

Kodama在数据库中跟踪模式版本。启动时，如果存储的版本与当前代码不匹配，则会删除所有表，并自动运行完整的重新索引。不需要手动迁移。

陈旧指数警告

如果索引在24小时内没有更新， kodama_explore 和 kodama_search 在输出前添加警告。跑 kodama_index 刷新。

MCP客户端设置

克劳德桌面版

增添 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "kodama": {
      "command": "bun",
      "args": ["x", "kodama-mcp"]
    }
  }
}

克劳德代码

增添 .mcp.json 在项目根目录中：

{
  "mcpServers": {
    "kodama": {
      "command": "bun",
      "args": ["x", "kodama-mcp"]
    }
  }
}

从本地克隆运行

如果你克隆了repo并想直接将客户端指向源代码（而不是已发布的npm包），请使用：

{
  "mcpServers": {
    "kodama": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/kodama-mcp/src/index.ts"]
    }
  }
}

可选择添加到项目的 CLAUDE.md 改进刀具布线：

## Code Exploration
Use kodama tools (kodama_explore, kodama_search, kodama_get_symbol) for code discovery,
symbol lookup, and understanding code structure. Use built-in Read/Grep for reading
specific known files.

故障排除

“生成进程失败：没有这样的文件或目录”

这通常意味着MCP主机找不到 bun 二元的。MCP客户端不会继承您的完整shell PATH——它们通常只会看到 /usr/local/bin, /opt/homebrew/bin, /usr/bin, /bin, /usr/sbin, /sbin.

如果你通过官方安装程序安装了Bun，它位于 ~/.bun/bin/bun，它不在这些路径上。

修复：使用绝对路径 bun 在您的配置中。

找到你的发髻路径：

which bun

然后更新你的MCP配置（npm安装路径）：

{
  "mcpServers": {
    "kodama": {
      "command": "/Users/yourname/.bun/bin/bun",
      "args": ["x", "kodama-mcp"]
    }
  }
}

或者对于本地克隆：

{
  "mcpServers": {
    "kodama": {
      "command": "/Users/yourname/.bun/bin/bun",
      "args": ["run", "/absolute/path/to/kodama-mcp/src/index.ts"]
    }
  }
}

备选方案： 将符号链接bun放入标准PATH目录：

sudo ln -s $(which bun) /usr/local/bin/bun

服务器启动后立即断开连接

检查：

1. 您的Bun版本≥1.2(bun --version)
2. 对于npm安装：包已正确解析(bunx kodama-mcp --help 来自终端不应出错）
3. 对于本地克隆：您运行 bun install 里面 kodama-mcp/，以及其中的路径 args 指向实际 src/index.ts 文件（不是目录）

发展

bun run start          # Start MCP server (stdio transport)
bun run dev            # Start with --watch
bun test               # Run tests (296 tests across 27 files)
bun run lint           # Biome check
bun run lint:fix       # Biome auto-fix
bun run typecheck      # TypeScript type check
bun run benchmark      # Performance benchmarks
bun run benchmark:scale # Large-scale benchmarks

技术栈