LLMScribe

LLMScribe

将任意代码仓库转换为简洁、结构化且确定性的数据。 不使用 AI、嵌入或隐藏排名。开源，并提供免费托管的 MCP。

嘿，说的就是你，来加入我们的星标支持者吧 :)

为什么选择 LLMScribe？

• 确定性：相同输入，输出可预测。不使用 LLM、嵌入或 AI 排名
• 以仓库为先：支持本地项目和公开 GitHub 仓库，无需克隆
• 结构化输出：每项操作都提供机器可读的 JSON
• 快速发现：映射项目、搜索项目，然后准确获取所需内容
• 感知依赖关系：了解本地、外部和未解析的依赖项
• 感知 Git：检查状态和统一差异
• 已为 Agent 做好准备：通过一个配置块，即可将 LLMScribe 连接到任何 AI Agent 或 MCP 客户端
• 多种接口：CLI、MCP、GUI 和可编程核心，共享同一引擎
• 开源：采用 Apache-2.0 许可证，可自托管，永久免费

LLMScribe 并不试图成为智能本身，而是提供智能所需的数据。

功能概览

核心工具

更多功能

快速开始

从 PyPI 安装 LLMScribe：

pip install llmscribe

然后将它指向任意项目目录，或（通过 MCP 工具）指向公开的 GitHub 仓库。无需 API 密钥。

下方的 project_map(...)、search(...)、read(...) 代码片段展示了 MCP 工具调用。CLI（用于本地目录）和 Python（通过 llmscribe.core，参见 Python API）也支持相同的操作。

Map

生成不含文件内容的清晰目录树。探索陌生代码库时，这是最佳的第一步。

project_map()

# or a public GitHub repo, no clone needed
project_map(repo="owner/repo")

llmscribe map
llmscribe map --json

project_map

输出：

src/
├── api/
│   ├── routes.py
│   └── auth.py
├── models/
│   └── user.py
└── main.py

搜索

搜索文件路径、文件名、文件内容和单独的行。搜索结果有意保持确定性：LLMScribe 不会试图猜测你的意图。

search(query="authentication")

# or a public GitHub repo
search(query="authentication", repo="owner/repo")

llmscribe search "authentication"
llmscribe search "authentication" --json

search

每条匹配结果都包含文件路径、行号、匹配行、匹配文本和匹配类型（filename 或 content）。结果按路径和行号排序，最多显示 1,000 条匹配结果；二进制文件和超大文件会被跳过。

输出（--json，data.matches）：

[
  {
    "file_path": "src/auth/service.py",
    "line_number": 12,
    "line_content": "def authenticate(user, password):",
    "match_type": "content",
    "matched_text": "authenticate"
  }
]

读取

安全地获取指定文件的内容。LLMScribe 会验证路径，防止路径遍历到项目之外。

read(file_path="src/auth/service.py")

# or a public GitHub repo
read(file_path="src/main.py", repo="owner/repo")

llmscribe read src/auth/service.py

read

path 和 repo 不能同时使用。本地项目使用 path，公开的 GitHub 代码库使用 repo。

为 Agent 提供支持

与其将整个代码库塞进上下文窗口，不如让 Agent 逐步检索所需内容：

1. project_map()
      ↓
2. search("authentication")
      ↓
3. read("src/auth/service.py")
      ↓
4. project_dependencies("src/auth/service.py")
      ↓
5. read_many([...])

MCP

将任何兼容 MCP 的客户端（Cursor、Claude、Windsurf 等）连接到你的代码库。

免费托管 MCP。 无需安装：

{
  "mcpServers": {
    "llmscribe": {
      "url": "https://llmscribe.onrender.com/mcp"
    }
  }
}

对于支持自定义远程连接器的客户端，只需提供端点：https://llmscribe.onrender.com/mcp

公共端点适合试用。对于私有代码或生产工作负载，请改为自托管 LLMScribe。

本地 MCP。 在你的计算机上通过 stdio 运行：

{
  "mcpServers": {
    "llmscribe": {
      "command": "llmscribe-mcp"
    }
  }
}

{
  "mcpServers": {
    "llmscribe": {
      "command": "python",
      "args": ["-m", "llmscribe.mcp"]
    }
  }
}

可用工具

project_map
project_overview
search
read
read_many
project_dependencies
project_diff

更多工具

批量读取

通过单次操作获取多个文件。支持部分成功，因此一个有问题的文件不会导致整个请求失败。

read_many([
    "src/auth/service.py",
    "src/auth/models.py",
    "src/api/login.py"
])

llmscribe read-many src/auth/service.py src/api/login.py

依赖项

检查某个文件周围的依赖关系。LLMScribe 会识别本地依赖项、外部依赖项、未解析的依赖项，以及依赖于此文件的文件。

project_dependencies("src/auth/service.py")

llmscribe dependencies src/auth/service.py --json

输出：

src/auth/service.py
│
├── depends on
│   ├── auth/models.py
│   ├── auth/config.py
│   └── auth/utils.py
│
└── used by
    ├── api/login.py
    └── tests/test_auth.py

在判断修改某个文件可能造成的影响时，这尤其有用。

差异

使用 Git 检查代码库变更。支持 Git 状态、未暂存的变更、已暂存的变更、指定提交和统一差异。

llmscribe diff

这样，应用和 Agent 不仅能了解代码库的当前状态，还能了解发生了哪些变化。

概览

生成完整的项目快照，其中包含目录结构、受支持的文本文件内容和结构化项目信息。

llmscribe overview

最适合小型和中型项目。对于大型代码库，请改用推荐的工作流：

map → search → read

CLI

每条命令都可以通过 --json 返回机器可读的 JSON，使 CLI 成为脚本、自动化流程和开发者工具的基础构件。

llmscribe map
llmscribe overview
llmscribe search "authentication"
llmscribe read src/auth/service.py
llmscribe read-many src/auth/service.py src/api/login.py
llmscribe dependencies src/auth/service.py
llmscribe diff

# machine-readable output
llmscribe map --json
llmscribe search "auth" --json
llmscribe dependencies src/auth/service.py --json

自托管

为私有代码库、团队、内部开发者工具和生产应用运行自己的 HTTP MCP 服务。

本地运行

pip install llmscribe

MCP_TRANSPORT=http MCP_ALLOW_LOCAL_PATHS=1 llmscribe-mcp

服务将在 http://localhost:8000/mcp 上提供，并提供用于监控的 GET /health 和 GET /info。

通过 HTTP 访问时，默认禁用 path 参数，以免托管服务暴露自身磁盘。设置 MCP_ALLOW_LOCAL_PATHS=1 以允许使用任何本地路径（仅限可信任的计算机），或者设置 MCP_ALLOWED_ROOTS=/srv/a:/srv/b 以允许访问指定目录。GitHub 代码库（repo=）始终可用。

Docker

docker build -t llmscribe-mcp .

docker run -p 8000:8000 -e MCP_ALLOWED_HOSTS="localhost,localhost:*,mcp.example.com" llmscribe-mcp

该镜像以非特权用户身份运行 python -m llmscribe.mcp，并设置 MCP_TRANSPORT=http，同时提供带有 healthcheck 的 /health。

Railway

railway up

环境变量

运行单个进程（缓存和 MCP 会话都保存在内存中）。未设置 MCP_TRANSPORT 时，PORT 仍会为向后兼容而选择 HTTP，但请明确设置 MCP_TRANSPORT=http。

Python API

from pathlib import Path
from llmscribe.core import project_map, search_project, read_file, read_files, analyze_dependencies, get_git_diff, LLMScribeError

root = Path(".")
print(project_map(root).tree)
print(search_project("auth", root).to_dict())
print(read_files(["README.md", "missing.py"], root).to_dict())   # per-file errors, never raises
try:
    analyze_dependencies("src/app.py", root)
except LLMScribeError as err:      # err.code is a stable machine-readable code
    print(err.code, err.message)

行为参考

忽略规则。 默认规则（.git、node_modules、venv、dist、build、.env、*.log 等）、根目录下的 .gitignore 和嵌套的 .gitignore 文件均按照真实的 Git 语义应用（通配符、目录、! 否定规则、根目录锚定模式）。除非被忽略，否则包含隐藏文件；绝不跟随或列出符号链接。

支持的文本文件。 已知的源代码／配置／文档扩展名，以及 Dockerfile、Makefile、LICENSE、.gitignore 等文件名。其他文件会显示在目录树中，但无法读取或搜索。

限制（唯一来源：llmscribe.core.limits）：每次概览／read_many 最多 400,000 个内容字符；每次 read_many 最多 50 个文件；1,000 个搜索匹配项；20,000 个映射条目；每个文件 2 MiB；差异内容 200,000 个字符；归档下载 100 MiB；每个归档 250 MiB / 100,000 个条目。任何截断内容都会通过 truncated、truncation_note、omitted_files 报告。

错误。 每种失败都有稳定的代码：invalid_argument、invalid_path、file_not_found、unsupported_file_type、binary_file、file_too_large、read_error、repository_not_found、not_a_repository、repository_too_large、github_rate_limited、github_auth_required、github_unavailable、git_unavailable、unsupported_operation、internal_error。JSON：{"ok": false, "tool": "...", "error": {"code": "...", "message": "..."}}。

依赖项。 Python、JavaScript/TypeScript、Java、Go、Rust、C/C++。每个引用属于 local、stdlib、external（不在仓库中，视为第三方）或 unresolved（找不到匹配项的相对／本地引用）；used_by 列出反向依赖项。本地和 GitHub 源的处理方式相同。

GitHub。 公共仓库（以及使用 GITHUB_TOKEN 的私有仓库）会作为单个 zip 归档获取，并按所有者／仓库／引用／凭据缓存在内存中。不会克隆仓库，也不会写入磁盘。GitHub 上的 project_diff 使用 compare API，并要求提供 commit（基准），ref（目标）可选；staged 仅适用于本地。

Git diff（本地）。 使用参数列表运行 git，超时时间为 30 秒，采用最小环境，且不使用外部 diff／textconv 驱动程序。

迁移说明

• 旧版工具名称（project_get_file、project_get_files、project_search、project_list_files）已移除；请改用 read、read_many、search。
• 错误代码 path_traversal 现在为 invalid_path；not_text_file 现在为 unsupported_file_type。
• project_dependencies 的结果：all_local_files/all_external_deps/all_unresolved 已由 used_by 和按类别划分的列表取代（新增了 stdlib_dependencies）。
• llmscribe.core 函数在根路径无效时会抛出 LLMScribeError（而非 FileNotFoundError）；依赖提供程序类和 llmscribe.github.provider 辅助函数已移除。
• 通过 HTTP 访问本地 path 现在需要设置 MCP_ALLOW_LOCAL_PATHS 或 MCP_ALLOWED_ROOTS。

架构

所有接口共用一个核心引擎，因此各处行为保持一致。

                         Repository
                             │
               ┌─────────────┴─────────────┐
               │                           │
          Local Project               GitHub Repo
               │                           │
               └─────────────┬─────────────┘
                             ▼
                     LLMScribe Core
                             │
       ┌─────────────────────┼─────────────────────┐
       │                     │                     │
       ▼                     ▼                     ▼
      CLI                   MCP                   GUI
       │                     │
       └──────────────┬──────┘
                      ▼
              Structured Output
                   / JSON

理念

LLMScribe 有意保持简单。目标不是让代码仓库变得“更聪明”，而是让代码仓库能够被软件访问。

我们提供

• 代码仓库提取
• 确定性搜索
• 结构化项目数据
• 文件检索
• 依赖信息
• Git 信息
• 多种接口

我们不提供

• ❌ AI 生成的答案
• ❌ 基于嵌入的搜索
• ❌ 语义排序
• ❌ 自主编码
• ❌ AI 编码 Agent
• ❌ 通用 Git 客户端

使用场景

• AI 编码 Agent
• MCP 应用
• 开发者工具
• 代码搜索界面
• 代码仓库浏览器
• 文档系统
• 代码分析流水线
• 自动化脚本
• 本地大模型应用
• 探索陌生的开源项目

开源版与托管版

LLMScribe 基于 Apache License 2.0 开源。你可以在本地运行、查看源代码、修改、自托管，并构建自己的集成。

托管的 MCP 端点提供便捷的零安装选项，方便试用；开源项目则让你拥有完全的控制权。

资源

• 网站： https://llmscribe.vercel.app
• GitHub： https://github.com/AMRITO-KUNDU/llmscribe
• PyPI： https://pypi.org/project/llmscribe/
• 公共 MCP： https://llmscribe.onrender.com/mcp
• 问题反馈： https://github.com/AMRITO-KUNDU/llmscribe/issues
• 贡献指南： https://github.com/AMRITO-KUNDU/llmscribe/blob/main/CONTRIBUTING.md

贡献

欢迎贡献。如果你想改进代码仓库提取、搜索、依赖分析、接口、集成或文档，请在提交拉取请求前查看贡献指南。

许可证

LLMScribe 基于 Apache License 2.0 授权。详情请参阅 LICENSE 文件。