使用说明

git doc mcp-将任何清单转换为mcp服务器

编写清单，将其托管在任何地方，用户可以立即使用他们的AI工具。

什么是git doc mcp？

git doc mcp是一个 声明性MCP清单系统 它允许任何人在不运行基础设施的情况下创建和托管MCP服务器。它将任何清单URL转换为具有自定义工具、资源和提示的功能齐全的MCP服务器，所有这些都在YAML中定义。

主要特点：

无需主机 -使用GitHub Pages、GitLab Pages、S3、任何静态托管
自定义JavaScript操作 -定义自己的工具逻辑
能力范围的秘密 -具有URL模式匹配的细粒度访问控制
平台无关 -适用于GitHub、GitLab、S3、本地文件
TOFU清单验证 -首次使用时信任，采用故障关闭安全机制
三层隔离 -工作进程+隔离虚拟机+URL验证
跨平台 -Linux、macOS、Windows

快速开始

1.安装

# Using npm
npm install -g git-doc-mcp

# Using npx (no install needed)
npx git-doc-mcp --manifest https://example.com/.mcp/manifest.yml

2.使用Claude代码进行配置

添加 ~/.claude/config.json:

{
  "mcpServers": {
    "my-repo": {
      "command": "npx",
      "args": ["git-doc-mcp", "--manifest", "https://example.com/.mcp/manifest.yml"]
    }
  }
}

3.创建您的清单

创建 .mcp/manifest.yml 在您的存储库中：

schemaVersion: "1.0"
name: my-repo-mcp
version: 1.0.0
description: MCP server for my repository

tools:
  - name: fetch-file
    description: Fetch a file from the repository
    inputSchema:
      type: object
      properties:
        path: { type: string }
      required: [path]
    action: https://example.com/.mcp/actions/fetch-file.v1.js  # URL or local path
    actionHash: "sha256:..."
    annotations:
      readOnlyHint: true
      openWorldHint: true

行动可以参考 HTTP（S）URL 或 本地文件路径 （相对于清单文件的目录）：

# Remote action (hosted)
action: https://raw.githubusercontent.com/owner/repo/main/.mcp/actions/fetch-file.v1.js

# Local action (for development)
action: ./actions/fetch-file.v1.js

试试看——现场演示

该项目使用自己的清单系统来提供文档。将其添加到您的AI工具中，以查看git doc mcp的运行情况：

克劳德代码 --添加到您的项目 .mcp.json:

{
  "mcpServers": {
    "git-doc-mcp-docs": {
      "command": "npx",
      "args": [
        "git-doc-mcp",
        "--manifest",
        "https://raw.githubusercontent.com/Z-M-Huang/git-doc-mcp/main/.mcp/manifest.yml"
      ]
    }
  }
}

克劳德桌面 --添加到 ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "git-doc-mcp-docs": {
      "command": "npx",
      "args": [
        "git-doc-mcp",
        "--manifest",
        "https://raw.githubusercontent.com/Z-M-Huang/git-doc-mcp/main/.mcp/manifest.yml"
      ]
    }
  }
}

这为您提供了5个工具、3个资源和3个提示，用于从维基工程:

工具	说明
`list_topics`	浏览文档主题，按标签筛选
`get_guide`	获取特定指南（例如，入门指南、清单参考）
`search_docs`	按关键字搜索所有文档
`get_example`	获取完整的工作示例（GitHub工具、REST包装器等）
`get_action_api`	动作脚本API参考（ctx.fetch、ctx.getSecret等）

这清单来源和动作脚本作为构建自己的参考。

安装

npm

npm install -g git-doc-mcp

npx（不安装）

npx git-doc-mcp --manifest <url-or-path>

本地开发

git clone https://github.com/Z-M-Huang/git-doc-mcp.git
cd git-doc-mcp
npm install
npm run build

用法示例

公开清单

npx git-doc-mcp --manifest https://raw.githubusercontent.com/owner/repo/main/.mcp/manifest.yml

带身份验证的私有清单

npx git-doc-mcp --manifest https://private.example.com/.mcp/manifest.yml \
  --manifest-header "Authorization: Bearer $TOKEN"

本地开发

# Manifest and action scripts can all be local files
npx git-doc-mcp --manifest ./path/to/manifest.yml

当使用本地清单时， action 和 resource.uri 字段可以引用具有相对于清单目录的路径的本地文件。每次工具调用时，都会从磁盘重新读取本地操作，因此编辑无需重新启动服务器即可生效。

带有预先批准的秘密

# Via CLI flag
npx git-doc-mcp --manifest https://example.com/.mcp/manifest.yml \
  --secret GITHUB_TOKEN=$GITHUB_TOKEN

# Via environment variable
export GIT_MCP_SECRET_GITHUB_TOKEN=$GITHUB_TOKEN
npx git-doc-mcp --manifest https://example.com/.mcp/manifest.yml

哈希钉扎（用于CI/CD）

npx git-doc-mcp --manifest https://example.com/.mcp/manifest.yml \
  --manifest-hash sha256:abc123...

速率限制

# Limit to 30 tool calls per minute
npx git-doc-mcp --manifest https://example.com/.mcp/manifest.yml \
  --rate-limit 30

清单架构

schemaVersion: "1.0"           # Required - schema version
name: my-repo-mcp              # Required - server name
version: 1.0.0                 # Required - semantic version
description: Description       # Optional - shown to AI
instructions: Use when...      # Optional - helps AI understand when to use

secrets:                       # Optional - secrets needed
  - name: GITHUB_TOKEN
    description: GitHub token
    scope:
      - "https://api.github.com/*"
    required: false

tools:                         # Optional - tool definitions
  - name: fetch-file
    title: Fetch File          # Optional - human-readable title
    description: Fetch a file  # Required
    inputSchema:               # Required - JSON Schema
      type: object
      properties:
        path: { type: string }
      required: [path]
    action: https://...        # Required - URL or local file path to action script
    actionHash: sha256:...     # Required - SHA-256 hash of action content
    annotations:               # Optional - hints for AI
      readOnlyHint: true
      destructiveHint: false
      idempotentHint: true
      openWorldHint: true

resources:                     # Optional - static resources
  - name: readme
    uri: https://...           # URL or local file path
    description: README
    mimeType: text/markdown

prompts:                       # Optional - prompt templates
  - name: explain-code
    description: Explain code
    args:
      - name: path
        required: true
    messages:                    # Optional - MCP PromptMessage[]
      - role: user
        content:
          type: resource
          resource:
            uri: "https://example.com/{{path}}"
            mimeType: text/plain
      - role: user
        content:
          type: text
          text: "Explain the code above from {{path}}"

提示信息

提示支持完整的MCP PromptMessage 使用多消息模板的格式：

没有 messages：单用户消息由以下内容构建 description +args（简单模式）
随着 messages：消息直接返回 {{argName}} 替换
嵌入资源：如果资源消息省略 resource.text，git doc mcp读取URI，并在请求提示时嵌入获取的内容

每条消息都有一个 role (user 或 assistant)以及 content （要么 text 或嵌入式 resource):

messages:
  - role: user
    content:
      type: text
      text: "Analyze {{path}} for {{focus}}"
  - role: assistant
    content:
      type: text
      text: "I'll analyze the code structure first."
  - role: user
    content:
      type: resource
      resource:
        uri: "https://example.com/{{path}}"
        mimeType: text/plain

行动API

操作是导出默认异步函数的纯JavaScript文件：

export default async function myAction(input, ctx) {
  const { fetch, getSecret, log, manifest } = ctx;

  log('info', `Running action for ${manifest.name}`);

  // Get a secret scoped to the target URL
  const url = 'https://api.example.com/data';
  const token = getSecret('API_KEY', url);

  const response = await fetch(url, {
    headers: token ? { 'Authorization': `Bearer ${token}` } : {}
  });

  // response.text is a property (not a method)
  // response.json() is a synchronous method
  const data = response.json();

  return {
    content: [{ type: 'text', text: JSON.stringify(data, null, 2) }]
  };
}

上下文方法

方法	说明
`ctx.fetch(url, options)`	带SSRF保护和重定向验证的作用域获取
`ctx.getSecret(name, url)`	如果URL与secret的作用域模式匹配，则获取secret值
`ctx.log(level, message)`	日志记录（级别：调试、信息、警告、错误）
`ctx.manifest`	清单元数据(`{ name, version }`)

获取响应

ctx.fetch 返回序列化响应对象（不是本机对象 Response):

属性/方法	类型	描述
`response.ok`	`boolean`	`true` 如果状态为200-299
`response.status`	`number`	HTTP状态码
`response.statusText`	`string`	HTTP状态文本
`response.text`	`string`	响应体为字符串（属性，而非方法）
`response.json()`	`object`	将正文解析为JSON（同步方法）
`response.headers`	`object`	响应头作为键值对

返回格式

// Success
return {
  content: [{ type: 'text', text: 'Result' }]
};

// Error
return {
  content: [{ type: 'text', text: 'Error message' }],
  isError: true
};

CLI 参考

选项

选项	描述	默认值
`--manifest <path>`	manifest.yml	的URL或本地路径（必需）
`--manifest-header <header>`	用于获取清单的标头（可重复）
`--manifest-hash <hash>`	预期用于固定的清单哈希
`--action-code-header <header>`	下载操作脚本的标头（可重复）
`--resource-header <header>`	用于获取资源的标头（可重复）
`--secret <name=value>`	预先批准的秘密（可重复）
`--timeout <ms>`	工作器超时（毫秒）	`60000`
`--memory-limit <bytes>`	沙盒内存限制（8MB-1GB）	`134217728` （128 MB）
`--rate-limit <n>`	每分钟最大工具调用次数（0=无限制）	`0`
`--allow-http`	允许不安全的HTTP URL（默认情况下仅HTTPS）	`false`
`--trust-changed`	接受清单哈希更改（TOFU覆盖）	`false`

环境变量

可以通过前缀为的环境变量提供秘密 GIT_MCP_SECRET_:

export GIT_MCP_SECRET_GITHUB_TOKEN=ghp_abc123
export GIT_MCP_SECRET_API_KEY=sk-xyz789

这 --secret CLI标志优先于环境变量。

示例

# Basic usage
git-doc-mcp --manifest ./manifest.yml

# With authentication headers
git-doc-mcp --manifest https://... \
  --manifest-header "Authorization: Bearer $TOKEN" \
  --action-code-header "Authorization: Bearer $TOKEN"

# Separate resource headers
git-doc-mcp --manifest https://... \
  --resource-header "Authorization: Bearer $RESOURCE_TOKEN"

# With secrets and rate limiting
git-doc-mcp --manifest https://... \
  --secret GITHUB_TOKEN=$TOKEN \
  --rate-limit 60

# Hash pinned (for CI/CD)
git-doc-mcp --manifest https://... --manifest-hash sha256:abc123...

# Accept manifest changes (TOFU override)
git-doc-mcp --manifest https://... --trust-changed

# Custom memory limit (256MB)
git-doc-mcp --manifest https://... --memory-limit 268435456

# Allow HTTP (not recommended for production)
git-doc-mcp --manifest http://localhost:8080/manifest.yml --allow-http

比较

特性	git doc mcp	Context7	idosal/git doc mcp
托管	任何静态主机	托管服务	需要单独的服务器
自定义操作	用户自定义JS	固定工具	有限操作
私有仓库	身份验证标头	OAuth	未知
平台	任意（GitHub、GitLab、S3等）	任意	仅限GitHub
本地开发	本地文件	否	否
秘密范围界定	URL模式匹配	N/A	N/A
彰显诚信	TOFU+哈希钉扎	N/A	N/A

安全模型

可信清单系统

用户明确配置他们信任的清单URL。这与GitHub MCP Server的官方方法是一致的——用户配置要使用的服务器，因此他们信任服务器作者。

三层隔离

Layer 1: Worker Process (Primary Boundary)
  - Separate Node.js child process
  - Sanitized environment (no inherited credentials)
  - Crash in action doesn't kill CLI

Layer 2: isolated-vm (Defense-in-Depth)
  - Configurable memory limit (default: 128MB)
  - CPU timeout: 30s
  - No direct filesystem/network access

Layer 3: Controlled API Surface
  - ctx.fetch with SSRF protection
  - ctx.getSecret with URL scope validation
  - Audit logging of all network calls

SSRF保护

所有HTTP（S）URL在获取之前都会经过验证：

默认情况下仅使用HTTPS（使用 --allow-http 覆盖）
私有IP范围被阻止（10.x、172.16-31.x、192.168.x、本地主机）
连接前已验证DNS解析
每个重定向URL都经过重新验证
跨源重定向剥离敏感标头（授权、Cookie）

中的本地文件路径 action 和 resource.uri 直接从磁盘读取，不受SSRF验证。 ctx.fetch 内部操作脚本仍然是HTTP（S），无论操作是如何加载的。

能力范围的秘密

秘密仅限于特定的URL模式：

secrets:
  - name: GITHUB_TOKEN
    scope:
      - "https://api.github.com/*"
      - "https://raw.githubusercontent.com/*"

ctx.getSecret(name, url) 仅当URL与作用域模式匹配时才返回机密值。路径边界感知通配符匹配可防止 /repos-private 从匹配a /repos/* 范围。

TOFU（首次使用信任）

首次使用时，git doc mcp会存储清单的SHA-256哈希值。如果清单发生变化：

Warning: Manifest content has changed since last use!
  Previous: sha256:abc123...
  Current:  sha256:def456...

To accept this change, re-run with: --trust-changed
For CI pinning, use: --manifest-hash sha256:def456...

服务器以非零代码退出，除非 --trust-changed 提供。对于CI/CD，请使用 --manifest-hash 用于硬钉。

速率限制

滑动窗口速率限制器可防止过多的工具调用：

# 60 calls per minute
git-doc-mcp --manifest https://... --rate-limit 60

审计日志

全部 ctx.fetch 通话记录到 ~/.git-doc-mcp/logs/audit.jsonl:

URL、HTTP状态、持续时间
重定向跳转
秘密访问（允许/拒绝）
动作开始/结束与计时

贡献

分叉存储库
创建要素分支
进行更改
构建： npm run build
运行测试： npm test
提交拉取请求

开发设置

npm install        # Install dependencies
npm run build      # Build all packages
npm test           # Run all tests (298 tests)

项目结构

git-doc-mcp/
  packages/
    core/          # Manifest loading, sandbox, worker, MCP server
    cli/           # CLI entry point and serve command
    template/      # Example manifest and actions

文档

完整文档可在 GitHub维基:

入门指南 --创建您的第一个MCP服务器
清单参考 --完整的架构文档
写作动作 -动作脚本API
示例 --完整的工作示例
安全模型 --隔离架构
故障排除 --常见问题

许可证

MIT许可证-请参阅许可证了解详情。

使用说明

git doc mcp-将任何清单转换为mcp服务器

什么是git doc mcp？

快速开始

1.安装

2.使用Claude代码进行配置

3.创建您的清单

试试看——现场演示

安装

npm

npx（不安装）

本地开发

用法示例

公开清单

带身份验证的私有清单

本地开发

带有预先批准的秘密

哈希钉扎（用于CI/CD）

速率限制

清单架构

提示信息

行动API

上下文方法

获取响应

返回格式

CLI 参考

选项

环境变量

示例

比较

安全模型

可信清单系统

三层隔离

SSRF保护

能力范围的秘密

TOFU（首次使用信任）

速率限制

审计日志

贡献

开发设置

项目结构

文档

许可证

相关 MCP

AKShare One MCP 股市数据服务

实时网络搜索服务

arXiv 论文检索 MCP 服务器

移动自动化MCP服务器

AI持久记忆服务器

Git仓库管理MCP服务器