git-doc-mcp - Turn Any Manifest into an MCP Server

Write a manifest, host it anywhere, and users can instantly use it with their AI tools.

What is git-doc-mcp?

git-doc-mcp is a declarative MCP manifest system that lets anyone create and host MCP servers without running infrastructure. It turns any manifest URL into a fully-functional MCP server with custom tools, resources, and prompts - all defined in YAML.

Key features:

• No hosting required - Use GitHub Pages, GitLab Pages, S3, any static hosting
• Custom JavaScript actions - Define your own tool logic
• Capability-scoped secrets - Fine-grained access control with URL pattern matching
• Platform-agnostic - Works with GitHub, GitLab, S3, local files
• TOFU manifest verification - Trust-on-first-use with fail-closed security
• Three-layer isolation - Worker process + isolated-vm + URL validation
• Cross-platform - Linux, macOS, Windows

Quick Start

1. Install

# 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. Configure with Claude Code

Add to ~/.claude/config.json:

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

3. Create Your Manifest

Create .mcp/manifest.yml in your repository:

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

Actions can reference HTTP(S) URLs or local file paths (relative to the manifest file's directory):

# 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

Try It — Live Demo

This project uses its own manifest system to serve documentation. Add it to your AI tool to see git-doc-mcp in action:

Claude Code — add to your project's .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 Desktop — add to ~/.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"
      ]
    }
  }
}

This gives you 5 tools, 3 resources, and 3 prompts that fetch documentation from the project wiki:

Tool	Description
list_topics	Browse documentation topics, filter by tag
get_guide	Fetch a specific guide (e.g., Getting-Started, Manifest-Reference)
search_docs	Search across all documentation by keyword
get_example	Get complete working examples (GitHub tools, REST wrapper, etc.)
get_action_api	Action scripting API reference (ctx.fetch, ctx.getSecret, etc.)

The manifest source and action scripts serve as a reference for building your own.

Installation

npm

npm install -g git-doc-mcp

npx (no install)

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

Local Development

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

Usage Examples

Public Manifest

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

Private Manifest with Authentication

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

Local Development

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

When using a local manifest, action and resource.uri fields can reference local files with paths relative to the manifest's directory. Local actions are re-read from disk on each tool call, so edits take effect without restarting the server.

With Pre-approved Secrets

# 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

Hash Pinning (for CI/CD)

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

Rate Limiting

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

Manifest Schema

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}}"

Prompt Messages

Prompts support the full MCP PromptMessage format with multi-message templates:

• Without messages: A single user message is built from description + args (simple mode)
• With messages: Messages are returned directly with {{argName}} substitution
• Embedded resources: If a resource message omits resource.text, git-doc-mcp reads the URI and embeds the fetched content when the prompt is requested

Each message has a role (user or assistant) and content (either text or embedded 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

Action API

Actions are plain JavaScript files that export a default async function:

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) }]
  };
}

Context Methods

Method	Description
ctx.fetch(url, options)	Scoped fetch with SSRF protection and redirect validation
ctx.getSecret(name, url)	Get a secret value if the URL matches the secret's scope pattern
ctx.log(level, message)	Logging (levels: debug, info, warn, error)
ctx.manifest	Manifest metadata ({ name, version })

Fetch Response

ctx.fetch returns a serialized response object (not a native Response):

Property/Method	Type	Description
response.ok	boolean	true if status is 200-299
response.status	number	HTTP status code
response.statusText	string	HTTP status text
response.text	string	Response body as a string (property, not method)
response.json()	object	Parse body as JSON (synchronous method)
response.headers	object	Response headers as key-value pairs

Return Format

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

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

CLI Reference

Options

Option	Description	Default
--manifest <path>	URL or local path to manifest.yml	(required)
--manifest-header <header>	Header for fetching manifest (repeatable)
--manifest-hash <hash>	Expected manifest hash for pinning
--action-code-header <header>	Header for downloading action scripts (repeatable)
--resource-header <header>	Header for fetching resources (repeatable)
--secret <name=value>	Pre-approved secret (repeatable)
--timeout <ms>	Worker timeout in milliseconds	60000
--memory-limit <bytes>	Sandbox memory limit (8MB - 1GB)	134217728 (128MB)
--rate-limit <n>	Max tool calls per minute (0 = unlimited)	0
--allow-http	Allow insecure HTTP URLs (HTTPS-only by default)	false
--trust-changed	Accept manifest hash changes (TOFU override)	false

Environment Variables

Secrets can be provided via environment variables prefixed with GIT_MCP_SECRET_:

export GIT_MCP_SECRET_GITHUB_TOKEN=ghp_abc123
export GIT_MCP_SECRET_API_KEY=sk-xyz789

The --secret CLI flag takes precedence over environment variables.

Examples

# 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

Comparison

Feature	git-doc-mcp	Context7	idosal/git-doc-mcp
Hosting	Any static host	Hosted service	Needs separate server
Custom actions	User-defined JS	Fixed tools	Limited actions
Private repos	Auth headers	OAuth	Unknown
Platform	Any (GitHub, GitLab, S3, etc.)	Any	GitHub only
Local development	Local files	No	No
Secret scoping	URL pattern matching	N/A	N/A
Manifest integrity	TOFU + hash pinning	N/A	N/A

Security Model

Trusted-Manifest System

Users explicitly configure manifest URLs they trust. This is consistent with the official GitHub MCP Server's approach — the user configures which server to use, so they trust the server author.

Three-Layer Isolation

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 Protection

All HTTP(S) URLs are validated before fetch:

• HTTPS-only by default (use --allow-http to override)
• Private IP ranges blocked (10.x, 172.16-31.x, 192.168.x, localhost)
• DNS resolution validated before connection
• Every redirect URL re-validated
• Cross-origin redirects strip sensitive headers (Authorization, Cookie)

Local file paths in action and resource.uri are read directly from disk and are not subject to SSRF validation. ctx.fetch inside action scripts remains HTTP(S)-only regardless of how the action was loaded.

Capability-Scoped Secrets

Secrets are scoped to specific URL patterns:

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

ctx.getSecret(name, url) only returns the secret value if the URL matches the scope pattern. Path-boundary-aware wildcard matching prevents /repos-private from matching a /repos/* scope.

TOFU (Trust-on-First-Use)

On first use, git-doc-mcp stores the manifest's SHA-256 hash. If the manifest changes:

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...

The server exits with a non-zero code unless --trust-changed is provided. For CI/CD, use --manifest-hash for hard pinning.

Rate Limiting

Sliding-window rate limiter prevents excessive tool calls:

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

Audit Logging

All ctx.fetch calls are logged to ~/.git-doc-mcp/logs/audit.jsonl:

• URL, HTTP status, duration
• Redirect hops
• Secret access (allowed/denied)
• Action start/end with timing

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Build: npm run build
5. Run tests: npm test
6. Submit a pull request

Development Setup

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

Project Structure

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

Documentation

Full documentation is available on the GitHub Wiki:

• Getting Started — Create your first MCP server
• Manifest Reference — Complete schema docs
• Writing Actions — Action scripting API
• Examples — Complete working examples
• Security Model — Isolation architecture
• Troubleshooting — Common issues

License

MIT License - see LICENSE for details.