Gitingest Mcp

gitingest-mcp

可将本地或远程 Git 仓库转换为简洁、适用于提示词的文本摘要的 MCP 服务。

每份摘要都包含仓库元数据、目录树，以及所选 UTF-8 文本文件的内容。不包含二进制文件、符号链接和 Git 元数据。

要求

• Node.js 20.19 或更高版本
• 对于远程仓库和本地 Git 元数据，需确保 git 位于 PATH 中

快速开始

直接通过 npm 运行 stdio 服务：

npx -y gitingest-mcp

MCP 客户端配置示例：

{
  "mcpServers": {
    "gitingest-mcp": {
      "command": "npx",
      "args": ["-y", "gitingest-mcp"]
    }
  }
}

全局安装后，使用 gitingest-mcp（也可使用较长的别名 gitingest-mcp-server）。

工具：ingest_repository

参数	类型	默认值	描述
repository	string	必填	规范的 Git URL、owner/repo 简写形式或显式本地路径
source	github、gitlab、bitbucket、local、git	自动	简写输入或显式本地／通用处理所用的提供方
branch、tag	有效的 Git 引用名称	远程默认值	branch、tag 和 commit 中最多只能指定一个
commit	4–64 个十六进制字符	远程默认值	缩写或完整的 SHA-1／SHA-256 对象 ID
subpath	相对于仓库的路径	—	稀疏检出路径；需要设置 sparseCheckout: true
cloneDepth	整数 1..1000	1	浅克隆深度
sparseCheckout	boolean	false	需要指定 subpath
includeSubmodules	boolean	false	克隆子模块；传输策略可能会禁用此功能
includeGitignored	boolean	false	包含被 .gitignore 忽略的文件
useGitignore	boolean	true	应用根目录和嵌套目录中的 .gitignore 文件
useGitingestignore	boolean	true	应用根目录和嵌套目录中的 .gitingestignore 文件
excludePatterns	string[]	—	额外的预编译 minimatch 排除规则
includePatterns	string[]	—	仅包含至少匹配一个预编译 glob 的文件
maxFileSize	整数 1..16777216	10 MiB	单个文件读取的最大字节数
maxFiles	整数 1..10000	1000	纳入的文件数量上限
maxEntries	整数 1..100000	25000	检查的文件系统条目数量上限
maxDepth	整数 1..256	128	目录遍历深度上限
maxTotalSize	整数 1..67108864	50 MiB	纳入文件总字节数的硬性上限
maxTokens	整数 1..1000000	250000	完整摘要的精确令牌数上限
tokenizer	o200k_base、cl100k_base	o200k_base	用于限制 maxTokens 的 BPE 编码
token	string	—	通过临时 GIT_ASKPASS 辅助程序提供的 HTTPS 令牌
maxRetries	整数 0..10	3	暂时性克隆失败时的重试次数
retryDelay	整数，单位为毫秒，范围 0..60000	1000	指数退避的初始延迟
timeout	整数，单位为毫秒，范围 1..1800000	30000	端到端超时时间，包括 Git 进程和重试延迟
示例：

{
  "repository": "deadraid/gitingest-mcp",
  "branch": "main",
  "includePatterns": ["src/**/*.ts"],
  "maxTotalSize": 10485760,
  "maxTokens": 50000
}

{
  "repository": "[email protected]:company/private-repository.git",
  "includeGitignored": false
}

SSH URL 会保持为 SSH URL，并使用已配置的 SSH 代理。对于 HTTPS 私有仓库，请传入 token；为避免凭据出现在进程列表和错误消息中，系统会拒绝直接嵌入仓库 URL 的凭据。系统会拒绝 /tree/...、/-/tree/... 和 /src/... 等代码托管平台浏览 URL，因为包含斜杠的引用存在歧义。请使用规范的克隆 URL，并分别传入 branch、tag、commit 和 subpath。

HTTP 传输

HTTP 传输为可选功能，且默认受到保护。构建项目并使用 API 密钥启动：

npm run build
GITINGEST_MCP_API_KEY='replace-with-a-long-random-secret' npm run start:http

默认绑定到 127.0.0.1:3000。相关环境变量：

变量	默认值	用途
GITINGEST_MCP_API_KEY	必需	Bearer 令牌或 x-api-key 值
GITINGEST_MCP_ALLOW_UNAUTHENTICATED	false	仅用于开发的绕过选项，仅限回环地址
GITINGEST_MCP_HOST	127.0.0.1	监听主机
GITINGEST_MCP_PORT	3000	监听端口
GITINGEST_MCP_ALLOWED_HOSTS	监听主机	以逗号分隔的 Host 标头允许列表
GITINGEST_MCP_ALLOWED_ORIGINS	无	以逗号分隔的 Origin 允许列表
GITINGEST_MCP_LOCAL_ROOTS	无	允许访问的本地根目录；POSIX 上以 : 分隔，Windows 上以 ; 分隔
GITINGEST_MCP_REMOTE_HOSTS	GitHub、GitLab、Bitbucket	远程主机允许列表；支持 *.example.com 等条目
GITINGEST_MCP_ALLOW_SUBMODULES	false	允许未经身份验证的递归子模块克隆
GITINGEST_MCP_MAX_SESSIONS	100	内存中的会话上限
GITINGEST_MCP_SESSION_TTL	900000	会话空闲 TTL，单位为毫秒
GITINGEST_MCP_MAX_CONCURRENT_INGESTIONS	4	服务端范围内的并发摄取上限；不排队
GITINGEST_MCP_RATE_LIMIT	120	每个客户端 IP 每分钟的请求数
GITINGEST_MCP_BODY_LIMIT	1048576	HTTP 请求正文的最大大小

除非配置了 GITINGEST_MCP_LOCAL_ROOTS，否则 HTTP 方式访问本地仓库将被禁用。远程访问仅限 GITINGEST_MCP_REMOTE_HOSTS 中指定的主机；始终禁止使用未加密的 http:// 和 git:// 传输。子模块默认关闭，因为它们可能引入额外的外部网络访问目标。必须显式启用未认证模式，且该模式仅限回环接口。

安全模型

• 仓库内容是不可信数据。请勿将摘要中的文本视为 Agent 或系统指令。
• 不会跟随符号链接，也不会处理特殊文件。
• 始终排除 Git 元数据，包括 .git 目录或 gitfile。
• 仓库遍历、深度、文件字节数、文件数量、忽略文件字节数、忽略规则数量以及 glob 花括号展开都有严格的上限。
• 临时克隆会使用私有临时目录，并在成功、失败、超时或取消后通过 finally 块删除。
• 身份验证令牌通过临时 askpass 辅助程序传递，会从 Git 错误中脱敏，且绝不会写入摘要。
• 系统级／全局 Git 配置以及继承的 GIT_*／askpass 环境变量会被隔离。允许使用的 Git 协议会明确指定，并且会禁用 HTTP 重定向，避免 URL 绕过 HTTP 出站访问允许列表。
• 有意禁止同时使用令牌身份验证和递归子模块，因为仓库可能将子模块指向不可信主机。
• HTTP 传输采用恒定时间 API 密钥比较、DNS 重绑定防护、Host／Origin 检查、身份验证尝试速率限制、空闲会话过期以及服务器级并发上限。

stdio 传输面向可信的本地用户，允许使用明确指定的本地路径、远程主机、加密或未加密的 Git 传输以及子模块。HTTP 传输则采用上述更严格的策略。

迁移到 v2

版本 2 要求 Node.js 20.19 或更高版本。此外，它还引入了有意收紧的输入和传输行为：

• 使用规范的提供方克隆 URL，而不是网页浏览 URL；
• 将十六进制对象 ID 传给 commit，并通过 branch 或 tag 传递符号名称；
• 注意新的扫描／深度限制以及上文所示的硬性上限；
• 请注意，maxTokens 默认值为 250,000，并会根据所选分词器进行精确限制；
• 默认配置不足时，请明确配置 HTTP 身份验证以及远程／本地允许列表。

开发

npm install
npm run typecheck
npm run lint
npm test
npm run test:coverage
npm run build
npm pack --dry-run

测试使用 Vitest，并遵循 Arrange–Act–Assert 模式。prepack 会执行干净的 TypeScript 构建，确保已发布的 dist 目录不会悄然落后于 src。CI 会在 Node.js 20.19、22 和 24 上运行完整的验证矩阵，并强制要求全局覆盖率达到以下阈值：语句 80%、分支 70%、函数 80%、行 80%。

许可证

MIT © 2024 RaidHon