# @gitpagedocs/mcp 中文文档

规范地址：https://npmcn.com/package/%40gitpagedocs/mcp/

版本：0\.0\.26
npm 元数据更新时间：2026-11-09T11:28:09.522Z
中文译文更新时间：2026-11-16T14:49:49.056Z
软件包许可：ISC

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40gitpagedocs/mcp
原文对照：https://npmcn.com/package/%40gitpagedocs/mcp/?lang=original
项目主页：https://github.com/Vidigal-code/git-page-docs#readme
源码仓库：https://github.com/Vidigal-code/git-page-docs

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：29.1 kB，13 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：3 个
- 首次发布：2026-06-14T23:46:00.992Z
- 最新版本发布：2026-11-09T11:28:09.359Z
- 近 30 天下载量：4295（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：50（近 12 个月 50 个）

## 中文简介

Git Page Docs 的模拟上下文协议服务器( 委托给 @ gitpagedocs/ tools ) 。 舰船类型Script源;通过tsx运行.

## 安装

```sh
npm install @gitpagedocs/mcp
```

也可以使用：`pnpm add @gitpagedocs/mcp`、`yarn add @gitpagedocs/mcp`、`bun add @gitpagedocs/mcp`

## README

# @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` 旗帜.

```json
{
  "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` 项目根 :

```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` | 供应商的模型目录 |

## 工作流程示例

1.  读取 `project://structure` 财务报告和审定财务报表 `project://readme`。 。 。 .
2.  打电话 `list_ai_providers` 财务报告和审定财务报表 `list_ai_models` 选择提供者/模型.
3.  打电话 `generate_api_docs` 与 `{"path":"src/index.ts"}` 以审查退回的草稿.
4.  将核准的文本保存到 `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接口上的请求.

见 [主要项目](https://npmcn.com/package/%40gitpagedocs/README.md), (中文(简体) ), [CLI 软件包](https://npmcn.com/package/%40gitpagedocs/cli/README.md) 编辑 [官方 MCP 类型SDK](https://github.com/modelcontextprotocol/typescript-sdk) 用于周边软件包和协议的执行.

## 常见问题

### @gitpagedocs/mcp 是什么？

Git Page Docs 的模拟上下文协议服务器\( 委托给 @ gitpagedocs/ tools \) 。 舰船类型Script源;通过tsx运行\.

### 如何安装 @gitpagedocs/mcp？

在项目目录运行 npm install @gitpagedocs/mcp，或使用 pnpm add / yarn add / bun add。

### @gitpagedocs/mcp 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @gitpagedocs/mcp 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @gitpagedocs/mcp 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @gitpagedocs/mcp 可以商用吗？

@gitpagedocs/mcp 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @gitpagedocs/mcp 的下载量有多少？

根据 npm 官方下载统计，@gitpagedocs/mcp 在 2026/10/17 – 2026/11/15 这 30 天内被下载 4,295 次，日均约 143 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @gitpagedocs/mcp 还在维护吗？

最新版本 0\.0\.26 发布于 2026/11/09（7 天前）；至今共发布 50 个版本，其中过去 12 个月发布了 50 个；首次发布于 2026/06/15。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

