Skip to content

Manifest Reference

Jump to bottom
Z-M-Huang edited this page Apr 24, 2026 · 5 revisions

Manifest Reference

Complete reference for the manifest.yml schema. Every field, every option, with examples.

Top-Level Fields

schemaVersion: "1.0"          # Required. Schema version (format: "major.minor")
name: my-mcp-server           # Required. Server name (1-64 chars)
version: 1.0.0                # Required. Semver version (e.g., "1.0.0", "2.1.0-beta.1")
description: |                 # Optional. Multi-line description
  What this MCP server does.
  Displayed to users during setup.
instructions: |                # Optional. Instructions for AI assistants
  Use these tools when the user asks about X.
  Start with tool A, then use tool B for details.
secrets:                       # Optional. Secret declarations
  - ...
tools:                         # Optional. Tool definitions
  - ...
resources:                     # Optional. Static resources
  - ...
prompts:                       # Optional. Prompt templates
  - ...

Field Details

Field Type Required Constraints
schemaVersion string Yes Format: digits.digits (e.g., "1.0")
name string Yes 1-64 characters
version string Yes Semver: major.minor.patch[-prerelease]
description string No Free text, supports multi-line
instructions string No Guidance for AI on how to use the tools
secrets array No Secret declarations with scopes
tools array No Tool definitions. At least one of tools, resources, or prompts must be defined
resources array No Static resources
prompts array No Prompt templates

Name Constraints

  • name: 1-64 characters, free text
  • Tool name: 1-64 characters, regex [a-zA-Z0-9_-]+
  • Prompt name: 1-64 characters, regex [a-zA-Z0-9_-]+

Version Format

The version field must follow semver:

# Valid versions
version: 1.0.0
version: 2.1.3
version: 1.0.0-beta.1
version: 0.1.0-alpha

# Invalid versions
version: 1.0        # Missing patch
version: v1.0.0     # No "v" prefix
version: 1.0.0.1    # Too many segments

Secrets

Declare secrets your actions need. Required secrets must be provided via --secret flags or GIT_MCP_SECRET_* environment variables.

secrets:
  - name: GITHUB_TOKEN
    description: "GitHub personal access token"
    scope: "https://api.github.com/*"
    required: false

  - name: API_KEY
    description: "API key for the backend service"
    scope:
      - "https://api.example.com/*"
      - "https://staging.example.com/*"
    required: true
Field Type Required Description
name string Yes Secret identifier (used in ctx.getSecret)
description string No Human-readable description
scope string or string[] Yes URL pattern(s) where this secret can be used
required boolean No Default: false. If true, server exits with error if not provided

See Managing Secrets for scope pattern syntax and usage.

Tools

Tools are the primary interface. Each tool maps to an action script.

Note: The inputSchema is passed to MCP clients for AI-assisted tool calling. At runtime, git-doc-mcp validates type and required fields. Additional JSON Schema features (enum, default, etc.) are passed through as hints but are not enforced by the server. See Defining Tools for details.

tools:
  - name: fetch-data
    title: Fetch Data
    description: Retrieves data from the API by ID
    inputSchema:
      type: object
      properties:
        id:
          type: string
          description: Record identifier
        format:
          type: string
          description: "Output format (json, csv, or text)"
        include_metadata:
          type: boolean
          description: Whether to include metadata
      required: [id]
    action: https://raw.githubusercontent.com/you/repo/main/actions/fetch-data.v1.js
    # Or use a local file path (relative to manifest directory):
    # action: ./actions/fetch-data.v1.js
    actionHash: "sha256:a1b2c3d4e5f6..."
    annotations:
      readOnlyHint: true
      destructiveHint: false
      idempotentHint: true
      openWorldHint: true
Field Type Required Description
name string Yes 1-64 chars, [a-zA-Z0-9_-]+
title string No Human-readable display name
description string Yes What the tool does (shown to AI)
inputSchema object Yes JSON Schema for tool inputs
action string (URL or path) Yes URL or local file path to the action script
actionHash string Yes sha256: + 64 hex chars
annotations object No Hints for MCP clients

The action field accepts either an HTTP(S) URL or a local file path (absolute or relative). Relative paths are resolved against the manifest file's directory. Local file paths are only allowed when the manifest itself is loaded from a local file; remote manifests with local action paths are rejected. Local actions are re-read from disk on each invocation, so edits take effect without restarting the server.

See Defining Tools for input schema patterns and annotations.

Resources

Static resources exposed to MCP clients. Content is fetched from the URI or read from a local file path on demand.

resources:
  - name: readme
    uri: https://raw.githubusercontent.com/you/repo/main/README.md
    description: Project README
    mimeType: text/markdown

  - name: api-spec
    uri: https://raw.githubusercontent.com/you/repo/main/openapi.yaml
    description: OpenAPI specification
    mimeType: application/yaml

  - name: changelog
    uri: https://raw.githubusercontent.com/you/repo/main/CHANGELOG.md
    description: Release changelog
    mimeType: text/markdown

  # Local file path (relative to manifest directory):
  - name: local-readme
    uri: ./README.md
    description: Local project README
    mimeType: text/markdown
Field Type Required Description
name string Yes Resource identifier
uri string (URL or path) Yes URL or local file path to the resource content
description string No Human-readable description
mimeType string No MIME type (e.g., text/markdown, application/json)

Like action, the uri field accepts HTTP(S) URLs or local file paths. Relative paths resolve against the manifest file's directory. Remote manifests with local resource paths are rejected.

See Resources & Prompts for more details.

Prompts

Prompt templates with argument substitution. MCP clients can list and invoke these.

prompts:
  - name: explain-code
    title: Explain Code
    description: Explain a code file from the repository
    args:
      - name: path
        description: File path to explain
        required: true
      - name: focus
        description: Specific aspect to focus on (e.g., "error handling", "performance")
        required: false
    messages:
      - role: user
        content:
          type: resource
          resource:
            uri: "https://raw.githubusercontent.com/you/repo/main/{{path}}"
            mimeType: text/plain
      - role: user
        content:
          type: text
          text: "Explain the code above from {{path}}. Focus on: {{focus}}"
Field Type Required Description
name string Yes 1-64 chars, [a-zA-Z0-9_-]+
title string No Display name
description string Yes What this prompt does
args array No Prompt arguments
messages array No Message templates (min 1 if present)

Prompt Arguments

args:
  - name: topic
    description: The topic to discuss
    required: true    # User must provide this
  - name: depth
    description: Level of detail
    required: false   # Optional, has a sensible default

Message Content Types

Text content:

messages:
  - role: user
    content:
      type: text
      text: "Explain {{topic}} in detail."

Resource content (embeds a fetched resource):

messages:
  - role: user
    content:
      type: resource
      resource:
        uri: "https://example.com/docs/{{topic}}.md"
        mimeType: text/markdown

Arguments are substituted using {{arg_name}} syntax in both text and resource URIs. When resource.text is omitted, git-doc-mcp fetches the resolved URI and embeds the content in the prompt response. If resource.text is provided, it is preserved with argument substitution and the URI is not fetched.

See Resources & Prompts for advanced patterns.

Complete Manifest Example

schemaVersion: "1.0"
name: acme-api-tools
version: 1.0.0
description: |
  MCP server for the Acme API.
  Provides tools to search, read, and manage Acme resources.

instructions: |
  Use these tools when working with Acme data.
  Start with search-resources to find items, then use get-resource for details.
  Always check the user's permissions before using update-resource.

secrets:
  - name: ACME_API_KEY
    description: "Acme API key (get one at https://acme.example.com/settings)"
    scope: "https://api.acme.example.com/*"
    required: true

tools:
  - name: search-resources
    title: Search Resources
    description: Search Acme resources by query
    inputSchema:
      type: object
      properties:
        query:
          type: string
          description: Search query
        limit:
          type: number
          description: Max results (1-100)
      required: [query]
    action: https://raw.githubusercontent.com/acme/mcp/main/actions/search.v1.js
    actionHash: "sha256:..."
    annotations:
      readOnlyHint: true
      idempotentHint: true
      openWorldHint: true

  - name: get-resource
    title: Get Resource
    description: Get a specific Acme resource by ID
    inputSchema:
      type: object
      properties:
        id:
          type: string
          description: Resource ID
      required: [id]
    action: https://raw.githubusercontent.com/acme/mcp/main/actions/get.v1.js
    actionHash: "sha256:..."
    annotations:
      readOnlyHint: true
      idempotentHint: true

resources:
  - name: api-docs
    uri: https://raw.githubusercontent.com/acme/mcp/main/docs/api.md
    description: Acme API documentation
    mimeType: text/markdown

prompts:
  - name: troubleshoot
    title: Troubleshoot Issue
    description: Walk through troubleshooting an Acme resource issue
    args:
      - name: resource_id
        description: The resource ID having issues
        required: true
    messages:
      - role: user
        content:
          type: text
          text: "Help me troubleshoot issues with Acme resource {{resource_id}}. First search for it, then check its status and recent changes."

Clone this wiki locally