# hermes-conductor-mcp

MCP server that exposes [Conductor Cloud](https://www.conductor.build) as tools for
[Hermes Agent](https://hermes-agent.nousresearch.com), so Hermes (running as your Telegram
brain) can dispatch real coding work to Conductor's sandboxed developer agents.

```
Telegram  <->  Hermes Agent (brain)  <->  this MCP server  <->  Conductor Cloud (dev agents)
```

## Tools exposed

- `list_projects` — repos available to create a workspace from
- `create_workspace` — spin up a sandboxed workspace + first session (agent: `claude` | `codex` | `cursor` | `acp`)
- `get_workspace_status` — poll workspace lifecycle (`initializing` → `ready` → ...)
- `archive_workspace` — tear a workspace down when done
- `send_message` — send an instruction/prompt into a coding session
- `get_session_status` — poll whether the agent is `idle` | `working` | `error`
- `get_session_messages` — read the full transcript
- `cancel_session` — stop the agent mid-task

Typical flow a Hermes conversation would drive: `list_projects` → `create_workspace` →
`send_message` (the task) → poll `get_session_status` until `idle` → `get_session_messages`
for the result → `archive_workspace`.

## Setup

1. Get a Conductor API key (requires Conductor Pro): https://app.conductor.build/users/api-keys
2. Install and build:

   ```bash
   npm install
   npm run build
   ```

3. Register it in Hermes's `~/.hermes/config.yaml`:

   ```yaml
   mcp_servers:
     conductor:
       command: "node"
       args: ["/Users/rohanarora/Desktop/hermes-conductor-mcp/dist/index.js"]
       env:
         CONDUCTOR_API_KEY: "<your conductor api key>"
   ```

4. Restart Hermes. It should discover tools prefixed `mcp_conductor_*` (e.g.
   `mcp_conductor_create_workspace`).
5. Make sure Hermes's Telegram gateway is already configured (BotFather token + your user ID) —
   see https://hermes-agent.nousresearch.com/docs/user-guide/messaging/telegram. That part is
   independent of this server.

## Local dev

```bash
CONDUCTOR_API_KEY=sk-... npm run dev
```

Runs the server directly via `tsx` over stdio — pair with any MCP inspector/client to test tool
calls without going through Hermes.