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.0pynacl>=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:
validatedconfidence +agent://hermesauthor + 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
Metadata
Release files for guild-mcp 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| guild_mcp-1.0.0.tar.gz | 29.4 kB | Without provenance | Details for guild_mcp-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| guild_mcp-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for guild_mcp-1.0.0-py3-none-any.whl |
Total release size: 60.9 kB
Release files / guild_mcp-1.0.0.tar.gz
| Download URL | guild_mcp-1.0.0.tar.gz |
|---|---|
| Size | 29.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
161e2170dd27e71f3bc117b6758a58311a7da9a6f8d57aabb084fbc48342e993
|
|
BLAKE2b-256 checksum How to use checksums |
8b3ea4ab643365054cc4fd10cdbcc07c1752f2724bd68fa2b73341c31a33d6af
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Release files / guild_mcp-1.0.0-py3-none-any.whl
| Download URL | guild_mcp-1.0.0-py3-none-any.whl |
|---|---|
| Size | 31.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c461ae8aa2a451561f1158320e7978d103c884f38701ac0cfeac5870f9abf346
|
|
BLAKE2b-256 checksum How to use checksums |
091ef831fe31639e7541fc04d788eee4a68d03e77778187a48fa3e9b38590462
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Security for guild-mcp 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.