codelibrarian

代码管理员

通过MCP和CLI为LLM和人工查询提供自我维护的代码索引。

Codelibrarian为您的代码库（函数、方法、类、模块）建立索引，并允许您使用自然语言或关键字进行搜索。它构建调用图，跟踪继承层次结构，并映射导入依赖关系。结果可以通过MCP服务器（适用于Claude等LLM客户端）或命令行界面获得。

Codelibrarian

运作原理

Codelibrarian将您的源文件解析为SQLite数据库，其中包含：

• 符号提取 --具有完整签名、文档字符串、参数、装饰器和返回类型的函数、方法、类和模块
• 混合搜索 --将语义向量搜索（通过嵌入）与BM25全文搜索相结合，以获得排名结果
• 调用图 --跟踪哪个函数调用哪个函数，可遍历到任意深度。自动过滤掉噪声（内置、stdlib、外部依赖项），因此只显示项目内部调用
• 继承层次结构 --映射父/子类关系
• 导入图形 --显示每个文件导入的内容以及导入的内容
• 增量索引 --仅重新索引已更改的文件（SHA256哈希比较）
• 美人鱼图 --以Mermaid语法生成类层次结构、调用图和模块导入图，可在GitHub、VS Code和任何markdown工具中渲染。还可以生成带有嵌入式Mermaid.js的自包含HTML页面，以便在任何浏览器中离线查看

图表

Codelibrary可以直接从索引生成Mermaid图，不需要额外的依赖关系。输出是Mermaid文本，它在GitHub markdown、VS Code预览和大多数文档工具中以本机方式呈现。

# Class hierarchy with methods, parents, and children
codelibrarian diagram class Animal

# Call graph: what does index_root call, 2 hops deep
codelibrarian diagram calls index_root --depth 2

# Call graph: what calls process_payment (reverse direction)
codelibrarian diagram calls process_payment --direction callers

# Module import dependencies (whole project)
codelibrarian diagram imports

# Module import dependencies (scoped to one file)
codelibrarian diagram imports --file src/codelibrarian/searcher.py

HTML输出

添加 --html 使用任何图表命令生成内嵌Mermaid.js的自包含HTML页面，无需互联网连接。该页面包括一个亮/暗主题切换。

# Generate an HTML file and open it in the browser
codelibrarian diagram class SQLiteStore --html -o class.html
codelibrarian diagram calls index_root --html -o calls.html
codelibrarian diagram imports --html -o imports.html

没有 -o，HTML被写入stdout，因此您可以对其进行管道传输：

codelibrarian diagram class MyClass --html > diagram.html

通过MCP工具可以获得相同的图表(generate_class_diagram, generate_call_graph, generate_import_graph)，因此任何LLM客户端都可以请求它们。通过 format: "html" 以获得一个自包含的HTML页面，而不是原始的Mermaid文本。

支持的语言

Python得到了更深入的分析（参数默认值、装饰器、调用提取），因为它使用了Python自己的AST模块。Swift和Kotlin有丰富的提取器（协议/接口、扩展、数据类、挂起函数、文档注释）。其他语言使用具有基本类/方法提取的树型语法。

安装

需要Python 3.11+和 紫外线.

git clone https://github.com/hherb/codelibrarian.git
cd codelibrarian
uv tool install .

这将安装 codelibrarian 作为PATH上的独立命令，使用uv的托管Python，其中包括SQLite-vec所需的SQLite扩展支持。

发展：

uv sync
uv run codelibrarian --help

注： pip install . 也可以工作，但需要启用SQLite扩展加载的Python构建。macOS系统Python和pyenv默认版本缺少这一点。如果你击中 enable_load_extension 错误，请使用 uv tool install 上面的方法。

嵌入服务器（可选）

对于语义搜索，代码库需要一个与OpenAI兼容的嵌入API。默认情况下，它预期 奥拉玛 在本地运行：

# Install and start Ollama, then pull the embedding model
ollama pull nomic-embed-text-v2-moe

如果没有嵌入服务器，codelibrarian仍然可以工作——它只能退回到全文搜索。

快速开始

看 QUICKSTART.md 以逐步演练。

cd /path/to/your/project

# Initialize the index
codelibrarian init

# Index the codebase
codelibrarian index

# Search for code
codelibrarian search "parse configuration file"

# Look up a specific symbol
codelibrarian lookup MyClass.my_method

# Check index statistics
codelibrarian status

MCP服务器

Codelibrarian公开了一个MCP服务器，以便LLM客户端（Claude Desktop、Claude Code等）可以直接查询您的代码库。

codelibrarian serve

服务器在stdio上运行，并提供以下工具：

Claude桌面配置

添加到您的Claude Desktop MCP配置(claude_desktop_config.json):

{
  "mcpServers": {
    "codelibrarian": {
      "command": "codelibrarian",
      "args": ["serve", "--path", "/path/to/your/project"]
    }
  }
}

CLI参考

codelibrarian init [--path DIR]
    Create .codelibrarian/ directory with default config and database.

codelibrarian index [--full] [--reembed] [--files FILE...] [--path DIR]
    Index the codebase. By default, skips unchanged files.
    --full       Reindex all files, ignoring hash cache.
    --reembed    Regenerate all embeddings.
    --files      Index only specific files (used by git hooks).

codelibrarian search QUERY [--limit N] [--semantic-only] [--text-only] [--path DIR]
    Search the index with natural language or keywords.

codelibrarian lookup NAME [--path DIR]
    Show full details for a symbol by name or qualified name.

codelibrarian callers NAME [--depth N] [--path DIR]
    Find all functions/methods that call the named symbol.

codelibrarian callees NAME [--depth N] [--path DIR]
    Find all functions/methods called by the named symbol.

codelibrarian status [--path DIR]
    Display index statistics (files, symbols by kind, embeddings).

codelibrarian hooks install [--path DIR]
    Install git post-commit and post-merge hooks for automatic
    incremental reindexing after each commit.

codelibrarian diagram class NAME [--html] [--output FILE] [--path DIR]
    Generate a Mermaid class hierarchy diagram.
    --html       Output self-contained HTML instead of Mermaid text.
    --output/-o  Write output to a file instead of stdout.

codelibrarian diagram calls NAME [--depth N] [--direction callees|callers] [--html] [--output FILE] [--path DIR]
    Generate a Mermaid call graph diagram.

codelibrarian diagram imports [--file PATH] [--html] [--output FILE] [--path DIR]
    Generate a Mermaid module import dependency diagram.

codelibrarian serve [--path DIR]
    Start the MCP server on stdio.

配置

之后 codelibrarian init，编辑 .codelibrarian/config.toml:

[index]
root = "."
exclude = [
    "node_modules/",
    ".git/",
    "__pycache__/",
    "dist/",
    "build/",
    ".codelibrarian/",
    "*.min.js",
]
languages = ["python", "typescript", "javascript", "rust", "java", "cpp", "swift", "kotlin"]

[embeddings]
api_url    = "http://localhost:11434/v1/embeddings"  # Ollama default
model      = "nomic-embed-text-v2-moe"
dimensions = 768
batch_size = 32
max_chars  = 1600   # ~400 tokens per symbol
enabled    = true    # Set to false to disable semantic search entirely

[database]
path = ".codelibrarian/index.db"

这 api_url 接受任何与OpenAI兼容的嵌入端点——Ollama、vLLM、LiteLLM、OpenAI等。

VS代码扩展

这 vscode-extension/ 该目录包含一个VSCode扩展，它在codelibrarian索引之上提供了一个丰富的UI。

特性

• MCP自动发现 --该扩展使用VS Code的内置MCP支持注册MCP服务器，因此GitHub Copilot Chat和Claude Code可以自动使用所有代码库工具，无需配置。
• CodeLens注释 --内联调用者计数高于每个函数、方法和类。单击打开调用图。
• 符号搜索 --快速挑选(Ctrl+Shift+P → “Codelibraryer:搜索符号”），使用取消发音的混合搜索，然后单击进行导航。
• 调用图树视图 --Explorer侧边栏面板显示任何符号的调用者和被调用者，可扩展到多个跃点。
• 保存时自动索引 --更改的文件在保存时会自动重新索引（2秒去抖动）。
• 状态栏 --显示与codelibrarian MCP服务器的连接状态。

从源代码安装

需要Node.js 18+和 codelibrarian CLI已安装。

cd vscode-extension
npm install
npm run compile

然后按 F5 在VS Code中启动扩展开发主机，或打包 .vsix:

npx vsce package
code --install-extension codelibrarian-vscode-0.1.0.vsix

设置

建筑

扩展产生 codelibrarian serve 作为子进程，使用MCP stdio协议进行通信 @modelcontextprotocol/sdk。主管以指数回退方式处理崩溃恢复。扩展需要一个已初始化的项目 codelibrarian init --如果 .codelibrarian/ 目录丢失，它提供初始化。

Git挂钩

安装挂钩以自动更新索引：

codelibrarian hooks install

这将安装 post-commit 和 post-merge 跑钩 codelibrarian index --files 在每次提交或合并后的后台。

许可证

AGPL 3.0——见 许可证.