Git Doc MCP

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

](https://www.npmjs.com/package/git-doc-mcp)  ](https://nodejs.org/)    

编写清单，将其托管在任何地方，用户可以立即使用他们的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个提示，用于从 维基工程:

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

安装

npm

npm install -g git-doc-mcp

npx（不安装）

npx git-doc-mcp --manifest 

本地开发

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 返回序列化响应对象（不是本机对象 Response):

返回格式

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

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

CLI 参考

选项

环境变量

可以通过前缀为的环境变量提供秘密 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

比较

安全模型

可信清单系统

用户明确配置他们信任的清单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状态、持续时间
• 重定向跳转
• 秘密访问（允许/拒绝）
• 动作开始/结束与计时

贡献

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

开发设置

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

文档

完整文档可在 :

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

许可证

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