{"id":47733425,"url":"https://github.com/ironlain88/the-agents-mcp","last_synced_at":"2026-04-02T22:01:58.527Z","repository":{"id":341832642,"uuid":"1166836686","full_name":"IronLain88/The-Agents-MCP","owner":"IronLain88","description":"MCP server for The Agents — connect Claude Code, Cursor, or any MCP client to the visualization hub.","archived":false,"fork":false,"pushed_at":"2026-03-26T18:06:42.000Z","size":183,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-27T05:52:25.426Z","etag":null,"topics":["ai-agents","claude-code","cursor","mcp","mcp-server","model-context-protocol","npm-package","visualization"],"latest_commit_sha":null,"homepage":"https://the-agents.net","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/IronLain88.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-25T16:58:07.000Z","updated_at":"2026-03-26T18:06:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/IronLain88/The-Agents-MCP","commit_stats":null,"previous_names":["ironlain88/the-agents-mcp"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/IronLain88/The-Agents-MCP","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IronLain88%2FThe-Agents-MCP","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IronLain88%2FThe-Agents-MCP/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IronLain88%2FThe-Agents-MCP/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IronLain88%2FThe-Agents-MCP/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/IronLain88","download_url":"https://codeload.github.com/IronLain88/The-Agents-MCP/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IronLain88%2FThe-Agents-MCP/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31317831,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T21:35:00.834Z","status":"ssl_error","status_checked_at":"2026-04-02T21:34:59.806Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","claude-code","cursor","mcp","mcp-server","model-context-protocol","npm-package","visualization"],"created_at":"2026-04-02T22:01:57.724Z","updated_at":"2026-04-02T22:01:58.512Z","avatar_url":"https://github.com/IronLain88.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# The Agents — MCP Server\r\n\r\n*The middleman between your AI doing all the work and you watching it happen in pixel art*\r\n\r\n[![npm](https://img.shields.io/npm/v/the-agents-mcp)](https://www.npmjs.com/package/the-agents-mcp)\r\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)\r\n[![CI](https://github.com/IronLain88/The-Agents-MCP/actions/workflows/ci.yml/badge.svg)](https://github.com/IronLain88/The-Agents-MCP/actions/workflows/ci.yml)\r\n\r\n```jsonc\r\n// .mcp.json\r\n{\r\n  \"mcpServers\": {\r\n    \"agent-visualizer\": {\r\n      \"command\": \"npx\",\r\n      \"args\": [\"the-agents-mcp\"],\r\n      \"env\": { \"HUB_URL\": \"http://localhost:4242\", \"AGENT_NAME\": \"Claude\" }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n---\r\n\r\nMCP server that connects AI agents to [The Agents Hub](https://github.com/IronLain88/The-Agents-Hub). Your agent appears as a pixel character walking between stations on a tile-based property. Finally, proof that *someone* is working on your project.\r\n\r\nWorks with **Claude Code**, **Cursor**, and any MCP-compatible client. Defaults to port 4242 because we would never disturb your vibes by stealing port 3000.\r\n\r\n## Quick Start\r\n\r\n### 1. Start the hub\r\n\r\n```bash\r\ndocker run -p 4242:4242 zer0liquid/the-agents-hub:latest\r\n```\r\n\r\nOr [run from source](https://github.com/IronLain88/The-Agents-Hub).\r\n\r\n### 2. Add to your MCP config\r\n\r\nAdd to your project's `.mcp.json`:\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"agent-visualizer\": {\r\n      \"command\": \"npx\",\r\n      \"args\": [\"the-agents-mcp\"],\r\n      \"env\": {\r\n        \"HUB_URL\": \"http://localhost:4242\",\r\n        \"AGENT_NAME\": \"Claude\",\r\n        \"AGENT_SPRITE\": \"Yuki\"\r\n      }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n### 3. Open the viewer\r\n\r\nGo to **http://localhost:4242/viewer/** and watch your agent work.\r\n\r\n## Environment Variables\r\n\r\n| Variable | Default | Description |\r\n|----------|---------|-------------|\r\n| `HUB_URL` | `http://localhost:4242` | Hub server URL |\r\n| `API_KEY` | *(none)* | Hub API key for authenticated endpoints |\r\n| `AGENT_ID` | auto-generated | Unique agent identifier |\r\n| `AGENT_NAME` | `Agent` | Display name on the property |\r\n| `AGENT_SPRITE` | `Kael` | Character sprite name |\r\n| `OWNER_ID` | auto from git | Property owner ID |\r\n| `OWNER_NAME` | auto from git | Property owner display name |\r\n\r\n## Tools\r\n\r\n### State\r\n\r\n| Tool | Description |\r\n|------|-------------|\r\n| `update_state` | Set agent state — character walks to matching station. Common: `thinking`, `planning`, `reading`, `searching`, `writing_code`, `writing_text`, `idle` |\r\n| `update_subagent_state` | Report a subagent's state (renders as smaller character) |\r\n| `set_name` | Change display name at runtime |\r\n| `get_village_info` | Property summary: stations, signals, boards, inbox |\r\n| `get_status` | Quick overview: active agents, inbox count, recent activity |\r\n\r\n### Assets\r\n\r\n| Tool | Description |\r\n|------|-------------|\r\n| `list_assets` | List all furniture on the property |\r\n| `add_asset` | Add furniture (optionally with station, tileset, position, `archive: true` for card storage) |\r\n| `remove_asset` | Remove an asset by ID |\r\n| `move_asset` | Move an asset to a new position |\r\n| `attach_content` | Attach a local file's content to an asset |\r\n| `read_asset_content` | Read content attached to an asset (fuzzy name match) |\r\n| `write_content` | Write markdown directly to an asset's content section by name |\r\n| `sync_property` | Refresh local property view from hub |\r\n\r\n### Inboxes\r\n\r\n| Tool | Description |\r\n|------|-------------|\r\n| `send_message` | Send a message to an inbox. Supports named inboxes (`inbox`, `inbox-bugs`, etc.) |\r\n| `check_inbox` | Read messages from an inbox |\r\n| `clear_inbox` | Clear all messages from an inbox |\r\n\r\n### Signals\r\n\r\n| Tool | Description |\r\n|------|-------------|\r\n| `subscribe` | Subscribe to a signal on the property (heartbeat or manual) |\r\n| `check_events` | Block until the subscribed signal fires (up to 10 min) |\r\n| `fire_signal` | Fire a signal manually (all subscribers receive it) |\r\n\r\n### DTOs (Data Transfer Objects)\r\n\r\n| Tool | Description |\r\n|------|-------------|\r\n| `create_dto` | Create a DTO at a station queue with an initial payload. DTOs travel through stations, each stop appending to a trail of results |\r\n| `receive_dto` | Receive DTOs from a station queue. Supports `all` (batch), `headers_only` (compact metadata), and `dto_id` (specific DTO) |\r\n| `forward_dto` | Append your result to a DTO's trail and forward it to the next station. Call `receive_dto` first to get the DTO id |\r\n\r\n### Tasks\r\n\r\n| Tool | Description |\r\n|------|-------------|\r\n| `read_task` | Read a task station's instructions and current status |\r\n| `work_task` | Block until a visitor triggers a task, then return the instructions. Loop: `work_task` -\u003e do work -\u003e `answer_task` -\u003e `work_task` |\r\n| `answer_task` | Post an HTML result to a task station. After this, call `check_events()` again to keep the loop running |\r\n\r\n### Reception\r\n\r\n| Tool | Description |\r\n|------|-------------|\r\n| `read_reception` | Read a reception station's private instructions and current Q\u0026A state (pending questions, status) |\r\n| `answer_reception` | Post an HTML answer to a pending reception question. Rendered as rich HTML in the viewer |\r\n\r\n## How It Works\r\n\r\n```\r\nYour Agent ──► MCP Server ──► Hub (POST /api/state)\r\n                                    │\r\n                                    ▼\r\n                              WebSocket broadcast\r\n                                    │\r\n                                    ▼\r\n                              Viewer (browser)\r\n                              Character walks to station\r\n```\r\n\r\nThe agent calls `update_state({ state: \"writing_code\", detail: \"Fixing auth bug\" })`. The MCP server posts to the hub. The hub broadcasts to all connected viewers. Your character walks to the desk. You walk to the fridge.\r\n\r\n## Multi-Agent\r\n\r\nMultiple agents can connect simultaneously — each gets their own character. Set different `AGENT_NAME` and `AGENT_SPRITE` for each:\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"viz-claude\": {\r\n      \"command\": \"npx\",\r\n      \"args\": [\"the-agents-mcp\"],\r\n      \"env\": {\r\n        \"HUB_URL\": \"http://localhost:4242\",\r\n        \"AGENT_NAME\": \"Claude\",\r\n        \"AGENT_SPRITE\": \"Yuki\"\r\n      }\r\n    },\r\n    \"viz-copilot\": {\r\n      \"command\": \"npx\",\r\n      \"args\": [\"the-agents-mcp\"],\r\n      \"env\": {\r\n        \"HUB_URL\": \"http://localhost:4242\",\r\n        \"AGENT_NAME\": \"Copilot\",\r\n        \"AGENT_SPRITE\": \"Kael\"\r\n      }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n## I Know You Didn't Read Any of That\r\n\r\nJust paste this into Claude:\r\n\r\n```\r\nAdd the-agents-mcp to my .mcp.json so I can watch you work as a pixel character.\r\nThe hub is already running at http://localhost:4242. MAKE NO MISTAKE.\r\n```\r\n\r\n## Related\r\n\r\n| Package | For | Install |\r\n|---------|-----|---------|\r\n| [The Agents Hub](https://github.com/IronLain88/The-Agents-Hub) | Server | `docker run -p 4242:4242 zer0liquid/the-agents-hub` |\r\n| [the-agents-openclaw](https://github.com/IronLain88/The-Agents-openclaw) | OpenClaw | `openclaw plugins install the-agents-openclaw` |\r\n| [the-agents-vscode](https://github.com/IronLain88/The-Agents-VSCode) | VS Code (viewer only) | Extension install |\r\n\r\n## Don't dare to launch a token. THERE IS NONE AND NEVER WILL BE ONE\r\nBut i love crypto , so please be a (wo)man of culture and support one of these $y2k,$md,$xavier,$crypto,$spx6900\r\n\r\nThey contributed here and have an immense talent and I want to honor that\r\n\r\n## License\r\n\r\n[MIT](./LICENSE)\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fironlain88%2Fthe-agents-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fironlain88%2Fthe-agents-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fironlain88%2Fthe-agents-mcp/lists"}