@gitpagedocs/mcp

中文文档
0.0.26发布于 2026/11/09ISCTypeScriptES Module近 30 天下载 4295

Model Context Protocol server for Git Page Docs (delegates to @gitpagedocs/tools). Ships TypeScript source; run via tsx.

原始使用文档
文档目录7 节
  1. Install and connect
  2. Configure a provider
  3. Tool reference
  4. Resource reference
  5. Example workflow
  6. Limits and troubleshooting
  7. Package and validation

@gitpagedocs/mcp

The Model Context Protocol server exposes 20 tools and 7 resources over stdio. It starts as a child process of your MCP client. It does not open an HTTP port or run a background daemon.

Install and connect

Use Node.js 20+. Install the CLI in the project with npm install --save-dev @gitpagedocs/cli; this includes the server and its TypeScript runtime. A global installation also supports gitpagedocs mcp start. For a one-off run, use npx --yes @gitpagedocs/cli mcp start.

In VS Code, create .vscode/mcp.json with the following configuration. The process working directory is the project root; the MCP command has no --root or --cwd flag.

{
  "servers": {
    "gitpagedocs": {
      "type": "stdio",
      "command": "node",
      "args": [
        "${workspaceFolder}/node_modules/@gitpagedocs/cli/index.mjs",
        "mcp",
        "start"
      ],
      "cwd": "${workspaceFolder}"
    }
  }
}

Open the client's MCP server controls, start GitPageDocs and list its tools/resources. Test list_files with {"path":".","recursive":false} and read project://readme. These operations need no provider key. A terminal launched with mcp start waits for JSON-RPC; ordinary text typed into stdin is not a chat command. On a source checkout, the direct entry is node --import tsx mcp/src/bin.ts, not index.ts.

Configure a provider

Provider calls read credentials from the server process environment. MCP does not automatically load .env or the CLI's encrypted vault. Use the client's protected input/secret facility to inject environment values; never place real keys in a committed configuration. Restart the MCP process after changing its environment.

Select a provider using configure_ai_provider or .gitpagedocs-mcp.json at the project root:

{
  "provider": "ollama",
  "model": "llama3"
}
ProviderEnvironment
openaiOPENAI_API_KEY
anthropicANTHROPIC_API_KEY / CLAUDE_API_KEY
geminiGEMINI_API_KEY / GOOGLE_API_KEY
openrouterOPENROUTER_API_KEY
ollamaOLLAMA_BASE_URL
azure-openaiAZURE_OPENAI_API_KEY + AZURE_OPENAI_BASE_URL
mistralMISTRAL_API_KEY
deepseekDEEPSEEK_API_KEY
cohereCOHERE_API_KEY
groqGROQ_API_KEY
xaiXAI_API_KEY
togetherTOGETHER_API_KEY
fireworksFIREWORKS_API_KEY
perplexityPERPLEXITY_API_KEY

When the saved selection is absent, unreadable or invalid JSON, the default provider is OpenAI. An unknown provider ID in readable JSON produces an explicit error instead of selecting another provider. Ollama does not require an API key; its local service and chosen model must be available. OLLAMA_BASE_URL is optional. Azure's base URL is the complete chat-operation URL, including deployment and API-version query when required. Model listings are the bundled catalog, not a live availability check.

Tool reference

? marks an optional argument. Paths and content are strings; recursive is boolean. Provider identifiers come from the provider catalog. Call tools through the MCP client's tool interface.

ToolArgumentsBehavior
list_filespath?, recursive?List files (defaults: current directory, non-recursive)
read_filepathRead UTF-8 text
write_filepath, contentWrite the entire file; create parent directories
search_projectquery, extension?Case-insensitive substring search
list_ai_providers—Read the provider catalog
list_ai_modelsprovider?Read the local model catalog
configure_ai_providerprovider, model?Save .gitpagedocs-mcp.json
ask_aiprompt, provider?, model?, system?Return one response, without conversation history
generate_documentationpath, provider?Document one source file
generate_api_docspath, provider?Describe the API in one file
generate_database_docspath, provider?Describe data models in one file
analyze_source_codepath, provider?Analyze one source file
generate_readmeprovider?Use the tree and package.json
generate_architecture_docsprovider?Use the repository tree
analyze_repositoryprovider?Analyze the repository tree
analyze_projectprovider?Analyze the tree and package.json
generate_changelogprovider?Use up to 80 commits, falling back to the tree
generate_release_notesprovider?Use the same context as the changelog
validate_docsprovider?Ask the provider to review gathered Markdown
update_documentationpath, instructions?, provider?Generate and write a managed region

generate_*, analyze_*, ask_ai and validate_docs return text; they do not save it automatically. validate_docs is a provider review, not a deterministic link checker. Only write_file, configure_ai_provider and update_documentation write files. update_documentation preserves text outside <!-- gitpagedocs:start --> / <!-- gitpagedocs:end -->; it appends a region when a valid pair is absent. The server does not show its own confirmation prompt; configure permissions in the MCP client.

Resource reference

URIContent
project://structureRepository tree
project://docsCollected Markdown documents
project://configResolved configuration and sourcePath
project://repositorypackage.json content
project://readmeREADME.md
project://ai/providersProvider catalog
project://ai/modelsModel catalog by provider

Example workflow

  1. Read project://structure and project://readme.
  2. Call list_ai_providers and list_ai_models to select a provider/model.
  3. Call generate_api_docs with {"path":"src/index.ts"} to review the returned draft.
  4. Save approved text with write_file, or use update_documentation with {"path":"docs/api.md","instructions":"Document the public API in English."} for a managed region.

The generation step sends selected project content to the configured provider.

Limits and troubleshooting

  • File reads: up to 512,000 bytes. Listing: up to 2,000 entries; gathered project trees: 400 entries.
  • Search: up to 5,000 entries, 200 matches, 240 characters per matching line.
  • Documentation gathering: first 40 Markdown files among up to 2,000 entries; files over 40,000 bytes are skipped. Gathered file and Markdown context is limited to 24,000 characters. This is not a global prompt limit: tree/package context, an existing document and a caller-supplied question can add content according to the selected tool.
  • Listing skips build/dependency directories such as node_modules, .git, .next, out, dist, prebuilt, .turbo and coverage. It does not interpret .gitignore; files such as .env are not automatically excluded. Run only in a trusted project and select the content to expose.
  • Filesystem tools check both lexical paths and canonical filesystem paths. Reads and directory listings reject symlinks/junctions that resolve outside the project root. Writes also validate the nearest existing parent before creating directories and reject symbolic links at the destination, including links to internal files. Search skips linked files whose contents cannot be read safely.
  • These checks protect against links already present when a request is handled; they are not an operating-system sandbox against concurrent path replacement by another process. Run the server in a trusted project with appropriate filesystem permissions. Configuration loading and provider-selection persistence use separate filesystem paths; loading project://config can import JavaScript/TypeScript configuration.
  • Tool failures include isError: true. Missing resources return Unavailable: .... Check the client's stderr log for startup errors; stdout is reserved for JSON-RPC.
  • If tools work but generation fails, verify provider selection, environment credentials, model availability and service connectivity.

Package and validation

The package ships TypeScript source and delegates filesystem, configuration and provider work to @gitpagedocs/tools. The published CLI is the supported executable entry point. @gitpagedocs/mcp alone has no npm bin command.

From a repository checkout, run pnpm run smoke:mcp and pnpm exec vitest run mcp/tests. The tests exercise client/server requests over the MCP interfaces.

See the main project, CLI package and the official MCP TypeScript SDK for the surrounding packages and protocol implementation.

版本与发布记录

@gitpagedocs/mcp 共发布 50 个版本,首次发布于 2026/06/15;过去 12 个月发布了 50 个版本。

版本发布日期距今
0.0.26latest2026/11/097 天前
0.0.252026/11/097 天前
0.0.242026/11/097 天前
0.0.232026/11/097 天前
0.0.222026/11/088 天前
0.0.212026/11/088 天前

关于 @gitpagedocs/mcp 的常见问题

@gitpagedocs/mcp 是什么?

Model Context Protocol server for Git Page Docs (delegates to @gitpagedocs/tools). Ships TypeScript source; run via 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 和提交记录判断。