使用说明

本地MCP服务器（Git和文件读取器）

本地人 模型上下文协议 （MCP）服务器，将您的AI客户端（Claude Desktop、Claude Code、Cursor、VS Code Continue/Cline等）转换为本地git存储库的高级用户。克隆转发、浏览代码、搜寻符号、跟踪引用和检查提交历史记录—所有这些都无需在远程获取时燃烧API令牌。

v4.0 船舶 24个工具+MCP资源+精心策划的提示 跨仓库管理、git检查、文件/代码探索和代码导航。

✨ 功能概览

回购管理

工具	目的
`add_repo`	在本地克隆公共仓库（支持 `tree/<branch>`, `commit/<sha>`, `releases/tag/<tag>` URL；可选的 `depth`)
`add_local_folder`	将磁盘上已有的文件夹（git或非git）注册为跟踪条目
`sync_repo`	`git pull` 一个或所有仓库（跳过本地文件夹条目）
`list_repos`	列出跟踪的存储库，包括 `filter` 子字符串+ `sort` 按名称/lastSync/branch
`remove_repo`	解开并删除（或保留文件 `keep_files=true`)；本地文件夹永远不会被删除

Git检查

工具	目的
`git_log`	提交历史；筛选依据 `file` 或 `since` （“2周前”）
`git_show`	民政事务局局长一次提交的全部细节/差异
`git_diff`	引用之间的差异（分支、标签、提交）； `stat_only` 对于较大的差异
`git_blame`	每行作者/提交注释（可选行范围）
`git_status`	工作树状态（对您编辑的本地文件夹条目有用）
`git_grep`	快速文本搜索荣誉 `.gitignore` （比原来快5-10倍 `search_code` 大型回购）
`list_branches`	当地分支机构（或所有分支机构，包括。 `origin/*` 随着 `include_remote`)
`list_tags`	标签/发布排序最新的第一

文件和代码探索

工具	目的
`list_files`	带有ext+size+深度过滤器+分页的递归列表(`offset` / `limit` / `hasMore`)
`read_file`	全/线范围/ `around_line` 窗户/ `function_at_line` 封闭块提取；负面的 `start_line` 尾式阅读
`search_code`	文本/正则表达式grep；二进制跳跃； `group=true` 逐文件存储； `format="json"`
`get_tree`	可视化ASCII目录树
`find_docs`	智能README/文档发现，排名+预览
`batch_read`	在一次调用中读取多个文件（每个文件上限）
`find_files`	按glob名称查找（例如。 `*/Config*.ts`)带分页
`find_symbol`	定位定义跨TS/JS、Python、Go、Rust、Java、Kotlin、C#、PHP、Ruby、Swift——包括函数/方法/类/接口/特质/类型/枚举/结构/内建/常量；包含范围的报告
`find_references`	定位呼叫者/用法标识符；可选注释/字符串剥离和 `exclude_definitions`
`search_all_repos`	一次跨每个跟踪的仓库运行查询

MCP资源和提示

资源 --每个跟踪的回购都公开为 localrepo://<repo> （元数据blob）+ localrepo://<repo>/<path> （文件模板）。客户可以 @-在没有工具调用的情况下提及文件。
提示（斜线命令） — explore-repo, find-impl, find-callers, changes-since, debug-symbol每一个都将一个多步骤的工作流程打包成一个镜头。

为什么这比原始的“让AI读取远程仓库”要好

无API代币成本 用于获取文件。
更快：本地磁盘上的glob+grep与往返GitHub。
分支/提交/标签感知：固定特定版本(tree/5.x, commit/<sha>, releases/tag/v1.4).
符号感知: find_symbol 跳到定义， find_references 枚举调用者。
AI友好错误：每个错误都会返回 [CODE] message +可选提示——易于扩展。

📋 先决条件

包子 v1.0+
Git打开 PATH

🚀 安装

git clone https://github.com/az-ka/my-local-mcp.git
cd my-local-mcp
bun install
bun run build       # produces server.exe (Windows) or server (macOS/Linux)

为了发展而不重建：

bun run start       # runs src/index.ts directly
bun run typecheck   # tsc --noEmit
bun run test.ts     # 74 integration tests (auto-clones the test repo on first run)

🔧 环境变量

变量	默认值	目的
`MCP_DEBUG`	未设置	何时 `1` / `true` / `yes`，将每个工具调用+持续时间记录到stderr
`MCP_GITHUB_TOKEN` / `GITHUB_TOKEN`	unset	克隆时注入HTTPS GitHub URL的令牌（从未存储在 `settings.json`)
`MCP_CLONE_DEPTH`	`0` （完整历史记录）	在以下情况下应用默认浅克隆深度 `add_repo` 不传递显式 `depth`
`MCP_MAX_REPO_BYTES`	`2 GB`	警告阈值后 `add_repo`；仅供参考，不会失败

🔌 连接您的AI客户端

将示例路径替换为 绝对的 通往你的路 server.exe （Windows）或 server 二元的。

克劳德桌面版

编辑：

视窗: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "local-docs": {
      "command": "D:/Ngoding/Bun/my-local-mcp/server.exe",
      "args": [],
      "env": {
        "MCP_GITHUB_TOKEN": "ghp_xxx"
      }
    }
  }
}

在Windows JSON上，转义反斜杠(\\) 或使用正斜杠。保存后重新启动应用程序。

克劳德代码（CLI）

claude mcp add local-docs "D:/Ngoding/Bun/my-local-mcp/server.exe"
claude mcp list   # verify

光标

Settings → Features → MCP → + Add New MCP Server

名称: local-docs
类型: command
命令: D:/Ngoding/Bun/my-local-mcp/server.exe

VS代码——Cline/Roo代码

打开 MCP服务器 侧边栏中的面板→ Edit MCP Settings → 添加与Claude Desktop相同的JSON形状。

验证是否已加载

启动时，服务器会记录到stderr：

Local MCP Server v4.0.0 running on StdIO — 24 tools + resources + prompts loaded

Claude桌面日志位于 %APPDATA%\Claude\logs\mcp-server-local-docs.log （Windows）。如果没有出现工具：检查路径是否为绝对路径，运行 server.exe 手动确认它启动，然后重新启动客户端。

更新二进制文件：客户端保持可执行文件打开。为了安装新版本， 先关闭客户端那么 bun run build，然后重新打开。

💬 示例提示

"Add https://github.com/sveltejs/svelte."
"Add https://github.com/filamentphp/filament/tree/5.x as filament-v5."
"Add https://github.com/joho/godotenv/releases/tag/v1.4.0 — only that tag."
"Register C:/projects/my-app as a local folder named my-app."

"Sync all my local repositories."

"Where is `useAuth` defined in better-auth-docs?"          → find_symbol
"Who calls `useAuth`?"                                     → find_references with exclude_definitions
"Read the function around line 142 of src/auth.ts."        → read_file with function_at_line=142
"Show me 10 lines around line 80 of config.go."            → read_file with around_line=80, context_lines=5

"Who last touched lines 40-60 of godotenv.go?"             → git_blame
"What's the status of my-app working tree?"                → git_status
"git_grep 'rate_limit' in convex-backend."                 → git_grep

"Diff v1.5.0 vs v2.0.0 in drizzle-orm — stat only."        → git_diff with stat_only=true
"Show me last 10 commits to src/index.ts in atlas."        → git_log with file filter

"Find all files matching **/test_*.py under src/."         → find_files
"Search for 'rate limit' across all my repos."             → search_all_repos
"Read the last 100 lines of CHANGELOG.md in effect."       → read_file with start_line=-100

服务器显示的Slash命令（在支持提示的客户端中运行）：

/explore-repo <name> --引导旅行
/find-impl <symbol> --查找并阅读实现
/find-callers <symbol> --列举用法
/changes-since <ref> --总结最近的变化
/debug-symbol <symbol> --定义+调用者+最近历史演练

🌿 分支/提交/标记URL

add_repo 接受以下任何一项：

{ "url": "https://github.com/filamentphp/filament", "name": "filament-v5", "branch": "5.x" }
{ "url": "https://github.com/filamentphp/filament/tree/5.x", "name": "filament-v5" }
{ "url": "https://github.com/joho/godotenv/commit/aabbccdd1122", "name": "godotenv-pinned" }
{ "url": "https://github.com/joho/godotenv/releases/tag/v1.4.0", "name": "godotenv-1.4" }

使用克隆分支URL --single-branch 以节省空间和速度。提交/标记URL检查请求的引用（提交=分离的HEAD）。

🗒️ 每次回购 `.mcpignore`

放下一个 .mcpignore 在任何克隆仓库的根目录下添加文件，以添加额外的忽略模式（与内置默认值合并，如 node_modules/, target/，锁文件）：

# example .mcpignore
bazel-bin/
generated/
fixtures

普通文件夹名称会自动包装到 **/<name>/**.Glob模式按原样使用。缓存60秒；删除文件是在缓存到期后或之后进行的 sync_repo.

🛡️ 安全和安保注意事项

路径遍历被阻止：每个文件op在repo根目录下通过以下方式解析 path.relative 并拒绝 [PATH_TRAVERSAL] 错误。
跳过二进制文件 在 search_code / find_references （扩展块列表+前4KB中的空字节嗅探）。
标识符验证: find_symbol 和 find_references 拒绝任何不符合的东西 [A-Za-z_$][A-Za-z0-9_$]*.
SHA验证: git_show 和 commit/<sha> URL只接受4-40个十六进制字符，没有shell注入表面。
差分截断：过大的差异/文件将被截断，并使用清晰的 [WARNING: ...] 标记。
令牌从未存储: MCP_GITHUB_TOKEN 仅在克隆URL构建时注入； settings.json 保留公共URL。
没有对代码的写入权限：服务器克隆、拉取和读取。它不会修改克隆的存储库或您的本地文件夹条目。

🗂️ 项目结构

my-local-mcp/
├── src/
│   ├── index.ts        # MCP server entry — registers tools, resources, prompts
│   ├── config.ts       # settings.json + env var resolution
│   ├── shared.ts       # ToolError, debug log, TTL cache, ignore loader, path guards
│   ├── resources.ts    # Resource templates (localrepo://...)
│   ├── prompts.ts      # Curated slash-commands
│   └── tools/
│       ├── git.ts      # repo + history + blame/status/grep
│       └── files.ts    # file + symbol + references + cache invalidation
├── storage/            # cloned repos live here (gitignored)
├── settings.json       # auto-generated tracked-repo registry (gitignored)
├── test.ts             # 74 integration tests (self-bootstraps test repo)
├── server.exe          # compiled binary (after bun run build)
└── package.json

🧪 测试

bun run test.ts

套房 自靴带：如果 godotenv 还没进去 storage/，它在第一次运行时就克隆了它。涵盖所有24种端到端工具：

树、提交、发布/标记和标记URL的URL规范化
每个标记的文件列表/读取/搜索（分页，格式=json，组）
read_file 模式：满、范围、负尾、， around_line 窗口， function_at_line 区块提取
路径遍历拒绝, 正则表达式拒绝无效, 二进制文件跳过
find_symbol 快乐+无效标识符+范围感知JSON输出路径
find_references 随着 exclude_definitions 和 exclude_comments_and_strings
git_log / git_show / git_diff / git_blame / git_status / git_grep / list_branches / list_tags
add_local_folder 快乐+失落之路拒绝
.mcpignore 扫描时应用的额外图案
结构化的 ToolError 有效载荷(describeError, formatErrorText)

🛠️ 科技

包子 --运行时+bundler+独立二进制编译器
模型上下文协议SDK
简单git --包裹系统 git
快速地球仪 --快速文件定位
黄道带 --输入模式验证

🙏 学分

灵感源自更好的上下文用于本地上下文管理。
建立在官方模型上下文协议SDK.

📜 许可证

麻省理工学院