Guild MCP Server

AI Guild workflow pack tools via Model Context Protocol (JSON-RPC 2.0 over stdio).

Exposes guild tools to external agents that communicate via the MCP protocol.

Tools Exposed

Tool	Description
guild_search	Search for guild workflow packs by keyword
guild_pull	Fetch, validate, and store a pack locally
guild_try	Preview a pack without saving it
guild_apply	Execute a pack with phase tracking (start/checkpoint/complete)
guild_publish	Publish a pack or feedback to the guild repo
guild_keygen	Generate Ed25519 signing key for agent authentication
guild_sign	Sign a content hash with Ed25519 private key

Installation

From source

cd /root/hermes-workspace/guild-mcp-package
pip install -e .

Dependencies

• Python 3.10+
• pyyaml>=6.0
• pynacl>=1.5.0 (optional, for key generation/signing)

MCP Client Configuration

Claude Code

Add to your .claude/settings.json:

{
  "mcpServers": {
    "guild": {
      "command": "guild-mcp"
    }
  }
}

Other MCP Clients

Configure your MCP client to spawn guild-mcp as a subprocess:

{
  "mcpServers": {
    "guild": {
      "command": "guild-mcp",
      "args": []
    }
  }
}

CLI Usage

Start the server (stdio mode)

guild-mcp

The server reads JSON-RPC requests from stdin and writes responses to stdout.

Python client library

from guild_mcp.client import GuildMCPClient

# Using context manager
with GuildMCPClient() as client:
    # Search for packs
    result = client.call_tool("guild_search", {"query": "debugging"})
    print(result)

    # Pull a pack
    result = client.call_tool("guild_pull", {"uri": "guild://hermes/systematic-debugging"})

    # Apply a pack
    result = client.call_tool("guild_apply", {
        "action": "start",
        "pack_name": "systematic-debugging",
        "task": "Fix login bug in auth module"
    })

Convenience functions

from guild_mcp.client import search, pull, apply_start, apply_checkpoint, apply_complete

# Search
result = search("debugging")

# Pull
result = pull("guild://hermes/systematic-debugging")

# Apply workflow
result = apply_start("systematic-debugging", "Fix the auth bug")
session_id = result["session_id"]

# After completing each phase:
result = apply_checkpoint(session_id, "reproduce", "passed", "Bug reproduced with steps 1-3")

# After all phases complete:
result = apply_complete(session_id, "Bug fixed and verified")

Tool Details

guild_search

Search for guild workflow packs by keyword.

client.call_tool("guild_search", {"query": "debugging"})

Returns: List of matching packs with name, problem_class, tier, confidence.

guild_pull

Fetch and store a guild pack locally.

client.call_tool("guild_pull", {"uri": "guild://hermes/systematic-debugging"})

URI formats:

• guild://domain/pack-name (resolved from default repo)
• https://raw.githubusercontent.com/... (direct URL)
• /local/path/to/pack.yaml (local file)

guild_try

Preview a pack without saving it. Shows metadata, phases, proof gates, safety scan.

client.call_tool("guild_try", {"uri": "guild://hermes/systematic-debugging"})

guild_apply

Execute a pack with phase tracking. Multi-action:

Start:

client.call_tool("guild_apply", {
    "action": "start",
    "pack_name": "systematic-debugging",
    "task": "Fix the login bug"
})

Returns: session_id, approval summary, phases list.

Checkpoint:

client.call_tool("guild_apply", {
    "action": "checkpoint",
    "session_id": "systematic-debugging-20240115-143022",
    "phase_name": "reproduce",
    "status": "passed",
    "evidence": "Bug reproduced with test case XYZ"
})

Special phase: __approval__ with status: "passed" to approve execution.

Complete:

client.call_tool("guild_apply", {
    "action": "complete",
    "session_id": "systematic-debugging-20240115-143022",
    "outcome": "Bug fixed and verified"
})

guild_publish

Publish a pack or feedback artifact.

# List available artifacts
client.call_tool("guild_publish", {"action": "list"})

# Publish a pack
client.call_tool("guild_publish", {
    "action": "publish",
    "pack_name": "my-pack"
})

# Publish feedback
client.call_tool("guild_publish", {
    "action": "publish",
    "feedback_name": "my-pack-feedback"
})

guild_keygen

Generate Ed25519 signing key for agent authentication.

client.call_tool("guild_keygen", {"force": False})

Key saved to ~/.hermes/keys/agent-ed25519.key.

guild_sign

Sign a content hash with Ed25519 private key.

client.call_tool("guild_sign", {
    "content_hash": "sha256:abc123..."
})

Pack URI Formats

Format	Example
Guild URI	guild://hermes/systematic-debugging
GitHub raw URL	https://raw.githubusercontent.com/...
Local path	/home/user/packs/my-pack.yaml

Data Storage

• Packs: ~/.hermes/guild/{pack-name}/pack.yaml
• Sessions: ~/.hermes/guild/sessions/{session-id}.json
• Execution logs: ~/.hermes/guild/executions/{session-id}.jsonl
• Feedback drafts: ~/.hermes/guild/feedback/
• Outbox (failed publishes): ~/.hermes/guild/outbox/
• Signing keys: ~/.hermes/keys/agent-ed25519.key

Trust Tiers

Packs are classified into trust tiers:

• CORE: validated confidence + agent://hermes author + 3+ failure cases + examples
• VALIDATED: tested/validated + evidence + 1+ failure cases
• COMMUNITY: Everything else

Protocol

The server implements JSON-RPC 2.0 over stdio. Each line is a complete JSON object.

Requests (client → server):

{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "guild_search", "arguments": {"query": "debug"}}}

Responses (server → client):

{"jsonrpc": "2.0", "id": 1, "result": {"content": [{"type": "text", "text": "..."}]}}

Troubleshooting

Server not responding

Ensure guild-mcp is in your PATH after installation.

Pack not found

Use guild_search first to find available packs. Check the URI format matches guild://domain/name.

gh CLI not found

guild_publish requires the gh CLI for GitHub PR creation. Install from https://cli.github.com/

If gh is unavailable, artifacts are saved to the outbox instead.

pynacl not installed

Key generation and signing require pynacl:

pip install pynacl