@gitpagedocs/ mcp (英语)
模式背景协议服务器曝光20个工具和7个资源 静态。它从您 MCP 客户端的幼年过程开始。 它不打开 HTTP 端口或运行背景守护进程 .
安装和连接
使用节点.js 20+. 在工程中安装 CLI npm install --save-dev @gitpagedocs/cli;这包括服务器及其TypeScript运行时间. 全球安装也支持 gitpagedocs mcp start。用于一次性运行,使用 npx --yes @gitpagedocs/cli mcp start。 。 。 .
在 VS 代码中,创建 .vscode/mcp.json 带有以下配置。 进程工作目录是工程根; MCP 命令没有 --root 或者说 --cwd 旗帜.
{
"servers": {
"gitpagedocs": {
"type": "stdio",
"command": "node",
"args": [
"${workspaceFolder}/node_modules/@gitpagedocs/cli/index.mjs",
"mcp",
"start"
],
"cwd": "${workspaceFolder}"
}
}
}
打开客户端的MCP服务器控制,启动 GitPage Docs并列出其工具/资源. 测试 list_files 与 {"path":".","recursive":false} 读取 project://readme。这些操作不需要提供者的钥匙。 启用的终端 mcp start 等待 JSON- RPC; 输入 stdin 的普通文本不是一个聊天命令 。 直接输入是 node --import tsx mcp/src/bin.ts没有 index.ts。 。 。 .
配置一个提供者
提供者从服务器进程环境调用读取证书 。 MCP 不自动加载 .env 或CLI的加密金库。 使用客户端的保护输入/秘密设施来注入环境值;从不将真实的密钥放入承诺的配置中. 改变 MCP 环境后重新启动进程 .
选择使用 configure_ai_provider 或者说 .gitpagedocs-mcp.json 项目根 :
{
"provider": "ollama",
"model": "llama3"
}
| 提供者 | 环境 |
|---|---|
openai | OPENAI_API_KEY |
anthropic | ANTHROPIC_API_KEY / CLAUDE_API_KEY |
gemini | GEMINI_API_KEY / GOOGLE_API_KEY |
openrouter | OPENROUTER_API_KEY |
ollama | OLLAMA_BASE_URL |
azure-openai | AZURE_OPENAI_API_KEY + AZURE_OPENAI_BASE_URL |
mistral | MISTRAL_API_KEY |
deepseek | DEEPSEEK_API_KEY |
cohere | COHERE_API_KEY |
groq | GROQ_API_KEY |
xai | XAI_API_KEY |
together | TOGETHER_API_KEY |
fireworks | FIREWORKS_API_KEY |
perplexity | PERPLEXITY_API_KEY |
当所保存的选择缺失,无法读取或无效的JSON时,默认提供者是OpenAI. 在可读的JSON中一个未知的提供者ID产生一个明显的错误,而不是选择另一个提供者. Ollama不需要 API 密钥;其本地服务和所选模式必须可用. OLLAMA_BASE_URL 是可选的。 Azure的基础URL是完整的聊天操作URL,包括需要时的部署和API版本查询. 模型列表是捆绑的目录,而不是现场的可用性检查.
工具参考
? 标记可选参数。 路径和内容是字符串; recursive 是布尔。 提供者的识别资料来自提供者目录。 通过MCP客户端的工具界面调用工具.
| 工具 | 参数 | 行为 |
|---|---|---|
list_files | path?, recursive? | 列出文件( 默认: 当前目录, 非重复) |
read_file | path | 读取 UTF-8 文本 |
write_file | path, content | 写入整个文件; 创建父目录 |
search_project | query, extension? | 不区分大小写子字符串搜索 |
list_ai_providers | — | 读取提供者目录 |
list_ai_models | provider? | 读取本地模式目录 |
configure_ai_provider | provider, model? | 保存.gitpagedocs-mcp.json 数据 |
ask_ai | prompt, provider?, model?, system? | 返回一个回应,没有对话历史 |
generate_documentation | path, provider? | 文档一源文件 |
generate_api_docs | path, provider? | 在一个文件中描述 API |
generate_database_docs | path, provider? | 在一个文件中描述数据模型 |
analyze_source_code | path, provider? | 分析一个源文件 |
generate_readme | provider? | 使用树和包.json |
generate_architecture_docs | provider? | 使用寄存器树 |
analyze_repository | provider? | 分析寄存器树 |
analyze_project | provider? | 分析树和包.json |
generate_changelog | provider? | 用到80个,倒回树上 |
generate_release_notes | provider? | 使用与更改日志相同的上下文 |
validate_docs | provider? | 要求供应商审查收集的Markdown |
update_documentation | path, instructions?, provider? | 生成并写入管理的区域 |
generate_*, (中文(简体) ), analyze_*, (中文(简体) ), ask_ai 财务报告和审定财务报表 validate_docs 返回文本;它们不会自动保存文本. validate_docs 是一个提供者审查,而不是一个决定性的链接检查器。 仅 write_file, (中文(简体) ), configure_ai_provider 财务报告和审定财务报表 update_documentation 编写文件. update_documentation 保存外部文本 <!-- gitpagedocs:start --> 编号 : <!-- gitpagedocs:end -->;当无效配对不存在时,它会附加一个区域。 服务器不显示自己的确认提示; 在 MCP 客户端中配置权限 .
资源参考
| URI 资源 | 内容 |
|---|---|
project://structure | 仓库树 |
project://docs | 收集了 Markdown 文档 |
project://config | 已解析配置和源文件 |
project://repository | 软件包.json 内容 |
project://readme | 读取 |
project://ai/providers | 提供者目录 |
project://ai/models | 供应商的模型目录 |
工作流程示例
- 读取
project://structure财务报告和审定财务报表project://readme。 。 。 . - 打电话
list_ai_providers财务报告和审定财务报表list_ai_models选择提供者/模型. - 打电话
generate_api_docs与{"path":"src/index.ts"}以审查退回的草稿. - 将核准的文本保存到
write_file,或使用update_documentation与{"path":"docs/api.md","instructions":"Document the public API in English."}管理区域.
生成步骤向配置的提供者发送选中的项目内容 .
限制和解决问题
- 文件读取:最多为51.2万字节. 上市:最多2000个条目;收集的项目树:400个条目.
- 搜索:最多可有5000个条目,200个匹配,每个匹配行240个字符.
- 文件收集:在最多2,000个条目中,前40个Markdown文件;超过40,000字节的文件被跳过. 集合的文件和Markdown上下文仅限于24000个字符. 这不是一个全局的即时限制:树/包上下文,一个已存在的文档和一个呼叫者提供的问题可以根据所选工具添加内容.
- 列出构建/ 依赖性目录等
node_modules, (中文(简体) ),.git, (中文(简体) ),.next, (中文(简体) ),out, (中文(简体) ),dist, (中文(简体) ),prebuilt, (中文(简体) ),.turbo财务报告和审定财务报表coverage它不解释.gitignore; 诸如.env不得自动排除。 只在信任的项目中运行,并选择要曝光的内容. - 文件系统工具既检查了词汇路径,也检查了词汇文件系统路径. 读取和目录列表拒绝在项目根外解决的同义链接/连接. 写法在创建目录之前还验证了最近的已存在的父目录,并拒绝目的地的符号链接,包括与内部文件的链接. 搜索跳过无法安全读取的链接文件 .
- 这些检查可以防止处理请求时已经存在的链接;它们不是一个操作系统沙盒来防止同时被另一个进程所取代。 在信任的项目中运行服务器, 并有适当的文件系统权限 。 配置加载和提供者选择的持续使用单独的文件系统路径; 加载
project://config可以导入JavaScript/TypeScript配置. - 工具失败包括:
isError: true缺少资源Unavailable: ...。检查客户端的 stderr 日志以识别启动错误; stdout 保留给 JSON- RPC . - 如果工具工作但生成失败,则核查提供者的选择、环境证书、模型可用性和服务连接性.
软件包和验证
包船 TypeScript 源码和代表文件系统、配置和提供者的工作 @gitpagedocs/tools。公布的CLI是支持的可执行条目. @gitpagedocs/mcp 一个人没有npm bin 命令.
从仓库取出, 运行 pnpm run smoke:mcp 财务报告和审定财务报表 pnpm exec vitest run mcp/tests。测试活动客户端/服务器在MCP接口上的请求.
见 主要项目, (中文(简体) ), CLI 软件包 编辑 官方 MCP 类型SDK 用于周边软件包和协议的执行.