Metadata-Version: 2.4
Name: guild-mcp
Version: 1.0.0
Summary: Guild MCP Server — AI Guild workflow pack tools via Model Context Protocol
Author-email: Hermes Team <hermes@example.com>
License: MIT
Project-URL: Homepage, https://github.com/hermes-agent/guild-mcp
Project-URL: Repository, https://github.com/hermes-agent/guild-mcp
Keywords: guild,mcp,workflow,pack,model-context-protocol
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pyyaml>=6.0
Requires-Dist: pynacl>=1.5.0; platform_system != "Windows"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"

# 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

```bash
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`:

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

### Other MCP Clients

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

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

## CLI Usage

### Start the server (stdio mode)

```bash
guild-mcp
```

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

### Python client library

```python
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

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

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

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

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

### guild_apply

Execute a pack with phase tracking. Multi-action:

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

Returns: `session_id`, approval summary, phases list.

**Checkpoint:**
```python
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:**
```python
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.

```python
# 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.

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

```python
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):
```json
{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "guild_search", "arguments": {"query": "debug"}}}
```

Responses (server → client):
```json
{"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`:
```bash
pip install pynacl
```
