Common issues and how to fix them.

The manifest doesn't match the expected schema. Common causes:

Missing required fields:

# ERROR: Manifest must define at least one tool, resource, or prompt
schemaVersion: "1.0"
name: my-mcp
version: 1.0.0
# No tools, resources, or prompts defined!

# FIX: Add at least one tool, resource, or prompt
tools:
  - name: my-tool
    description: Does something useful
    inputSchema:
      type: object
      properties: {}
    action: https://example.com/action.js
    actionHash: "sha256:..."

Invalid version format:

# ERROR
version: 1.0       # Missing patch
version: v1.0.0    # No "v" prefix allowed

# FIX
version: 1.0.0

Invalid tool name:

# ERROR
name: "my tool"     # Spaces not allowed
name: "my.tool"     # Dots not allowed

# FIX
name: my-tool       # Use hyphens
name: my_tool       # Or underscores

Invalid action hash format:

# ERROR
actionHash: "abc123"                    # Missing sha256: prefix
actionHash: "sha256:ABC123"            # Must be lowercase
actionHash: "sha256:abc123"            # Must be exactly 64 hex chars

# FIX
actionHash: "sha256:a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"

The manifest content has changed since it was first used.

# Option 1: Accept the change (if you trust it)
git-doc-mcp --manifest https://example.com/manifest.yml --trust-changed

# Option 2: Pin to a known hash
git-doc-mcp --manifest https://example.com/manifest.yml --manifest-hash "sha256:..."

The fetched action code doesn't match the hash in the manifest.

# Recompute the hash
shasum -a 256 .mcp/actions/my-tool.v1.js
# Output: a1b2c3d4... my-tool.v1.js

# Update manifest
actionHash: "sha256:a1b2c3d4..."

Common cause: editing the action file without updating the hash. Even whitespace changes produce a different hash.

The action script is missing or has the wrong export format.

// ERROR: Missing export
async function myAction(input, ctx) { ... }

// ERROR: Named export
export async function myAction(input, ctx) { ... }

// FIX: Default export
export default async function myAction(input, ctx) { ... }

The action function returned something other than the expected format.

// ERROR: Wrong return format
return "hello";
return { text: "hello" };
return { content: "hello" };

// FIX: Content must be an array of typed objects
return {
  content: [{ type: 'text', text: 'hello' }],
};

The action exceeded the wall time limit (default 60s).

# Increase timeout
git-doc-mcp --manifest ./manifest.yml --timeout 120000

Or optimize the action to make fewer/faster requests.

The fetched content exceeded the size limit (default 10MB).

// Limit response size in the action
const response = await ctx.fetch(url, {
  maxSize: 5 * 1024 * 1024,  // 5MB
});

The URL resolved to a private/internal IP address.

// These are blocked by default:
// http://localhost:3000
// http://127.0.0.1:8080
// http://10.0.0.1/api
// http://192.168.1.1/data

For local development, use --allow-http but be aware this only relaxes the HTTPS requirement, not the private IP block.

Action tried to fetch an HTTP URL.

# For development only:
git-doc-mcp --manifest ./manifest.yml --allow-http

For production, always use HTTPS URLs in manifests and action scripts.

The URL triggered more than 5 redirects. Check the URL — it may be a redirect loop.

Possible causes:

1. Secret not provided at startup:

   git-doc-mcp --manifest ./manifest.yml --secret MY_SECRET=value

2. URL doesn't match scope:

   # Manifest declares scope
   scope: "https://api.example.com/*"

   // Action uses a different URL
   ctx.getSecret('MY_SECRET', 'https://other.example.com/api');
   // → Returns undefined because URL doesn't match scope

3. Secret name doesn't match:

   # Manifest declares
   name: GITHUB_TOKEN

   // Action uses different name
   ctx.getSecret('github_token', url);  // Case-sensitive!

Server refuses to start because a required secret is missing.

# Provide via flag
git-doc-mcp --manifest ./manifest.yml --secret API_KEY=your-key

# Or via environment variable
export GIT_MCP_SECRET_API_KEY=your-key
git-doc-mcp --manifest ./manifest.yml

Tool calls are being throttled.

# Increase the limit
git-doc-mcp --manifest ./manifest.yml --rate-limit 120

# Or disable (for development)
git-doc-mcp --manifest ./manifest.yml --rate-limit 0

isolated-vm requires native compilation. Ensure you have:

# macOS
xcode-select --install

# Ubuntu/Debian
sudo apt-get install build-essential python3

# The package needs Node.js 18+
node --version  # Must be >= 18

# Install globally
npm install -g git-doc-mcp

# Or use npx
npx git-doc-mcp --manifest ./manifest.yml