MCP 服务器

MCP CoCo

Bridges OpenClaw and Hermes Agent to enable messaging, multi-turn conversations, and health checks via MCP tools.

README

Bus Agent

Universal Agent Communication Hub — Connect any AI agent to any other.

Bus Agent is a message bus for AI agents. It supports both the MCP Protocol and direct file-based access. Agents such as OpenClaw, Hermes, Claude Desktop, Cursor, OpenCode, and Claude Code CLI can all connect and communicate through a shared bus.

          ┌─────────────────────────────┐
OpenClaw  │                             │  Hermes Agent
     ────▶│    Bus Agent (Agent Bus)    │◀────
Claude    │                             │  Cursor
     ────▶│  40+ tools / CLI / SDKs     │◀────
OpenCode  │                             │  Claude Code CLI
     ────▶│  Scheduler / Orchestrator   │◀────
          └─────────────────────────────┘

Features

Agent Profiles & Discovery

Rich profiles — Each agent carries metadata: model info (provider, name, context window), capabilities, tags, operational status, version, connection endpoints.
Auto-discovery — When a new agent registers, the bus broadcasts a joined event to all connected agents. The new agent receives a welcome message via DM.
Search & filter — Query agents by name, capability, model, tag, or status. Supports text search across descriptions and capabilities.
Stale detection — Agents that miss heartbeats for 5 minutes are automatically marked offline.

Messaging

Direct messages — Send private messages between any two agents.
Broadcast — Send a message to every agent on the bus.
Channels — Group chat rooms for multi-agent conversations.
Long-poll — message_wait blocks until a new message arrives (configurable timeout, up to 60s).
Filtered inbox — Retrieve messages from specific senders or after a given cursor.

Scheduler

Cron expressions — Schedule recurring messages using standard cron syntax.
One-shot scheduling — Specify an ISO timestamp for single-delivery messages.
Timezone support — Each job can specify its own IANA timezone (e.g., Asia/Bangkok).

Auto-Reply Rules

Pattern matching — Define rules that automatically forward, reply, or broadcast when a message matches criteria.
Message transformation — Use templates with {message}, {from}, {channel} variables.
Loop protection — Configurable max_loops limit to prevent infinite chains.

Agent Orchestrator

Multi-step workflows — Define a pipeline of agents connected in sequence. Output from step N becomes input to step N+1.
Variable chaining — {input} → agent A stores result as {review_result} → agent B receives {review_result}.
Per-step timeout — Individual timeout per agent step; failed steps are reported without blocking.

Memory Layer

Agent memory system with dual-mode search:

Vector search (ANN) — Cosine similarity via Ollama (nomic-embed-text, 768-dim), OpenAI, or custom endpoint.
TF-IDF keyword search — Built-in scoring with recency boost, zero external dependencies.
Storage — Append-only JSONL per agent in .bus/memory/{agent}/.
Namespaces, TTL, archive, rebuild, search — 10 MCP tools.

Feature	Description
Namespaces	Categorize memories (preferences, system, archive, etc.)
TTL	Auto-expire memories after a set duration
Archive	Move old inbox messages into memory store
Rebuild	Regenerate all vector embeddings from stored content
Pluggable	Switch between keyword, Ollama, OpenAI, or custom

Webhook Gateway

Endpoint	Purpose
`POST /webhook/github/:channel`	GitHub push, PR, issue, comment events
`POST /webhook/github-actions/:channel`	GitHub Actions CI workflow status
`POST /webhook/gitlab/:channel`	GitLab push, merge request events
`POST /webhook/slack/:channel`	Slack messages
`POST /webhook/telegram/:channel`	Telegram bot updates
`POST /hook/:channel`	Generic JSON webhook
`POST /api/send`	Direct API: `{"to": "agent", "message": "..."}`
`GET /health`	Health check
`GET /api/channels`	List registered channels
`GET /api/agents`	List agents on the bus

Client SDKs

Python — clients/bus_client.py provides BusClient with methods for registration, messaging, and channel operations.
TypeScript — clients/bus-client.ts provides the same interface for Node.js environments.

External Bridges

The bridge module (bridge.js) provides a template for two-way communication between the bus and external platforms (Slack, Discord, custom).

Quick Start

# Install globally
npm install -g bus-agent

# MCP server mode (stdio — for any MCP client)
npx bus-agent

# CLI mode
bus status
bus agents
bus send hermes "Hello"

# Webhook gateway
bus-agent --daemon
node webhook-gateway.js 8080

MCP Client Configuration

{
  "mcpServers": {
    "bus-agent": {
      "command": "npx",
      "args": ["bus-agent"]
    }
  }
}

Or from a local clone:

{
  "mcpServers": {
    "bus-agent": {
      "command": "node",
      "args": ["/path/to/bus-agent/index.js"]
    }
  }
}

Environment Variables

export BUS_AGENT=my-agent           # Your agent name on the bus
export BUS_DIR=/path/to/data         # Custom data directory (default: ./.bus/ in CWD)

Architecture

                    ┌───────────────────────┐
                    │   HTTP :8080          │
                    │  Webhook Gateway      │
                    └──────┬────────────────┘
                           │
┌──────────┐     ┌────────┴────────────────────────┐     ┌──────────┐
│ OpenClaw │────▶│    Bus Agent (Agent Bus)        │◀────│  Hermes  │
│  (skill) │     │                                  │     │  Agent   │
├──────────┤     │  .bus/agents.json               │     ├──────────┤
│  Claude  │────▶│  .bus/messages/                 │◀────│  Cursor  │
│  Code    │     │  .bus/channels/                  │     │          │
├──────────┤     │  .bus/events/                    │     ├──────────┤
│ OpenCode │────▶│  .bus/memory/                    │◀────│  CLI     │
│  (clew)  │     │  .bus/schedule.json              │     │  agents  │
└──────────┘     └────────┬─────────────────────────┘     └──────────┘
                           │
          ┌────────────────┴────────────────────┐
          │  Utility Layer                      │
          │  Doctor — Diagnostics & Auto-Fix    │
          │  Tunnel — Cross-machine Proxy       │
          │  Backup — Backup, Restore & Diff    │
          └─────────────────────────────────────┘

Data storage is resolved at runtime:

$BUS_DIR environment variable (if set)
./.bus/ in current working directory (default)

Each user/project gets isolated data. The .bus/ folder is gitignored by default.

Data Layout

.bus/
  agents.json              # Agent registry with profiles
  messages/
    <agent>/               # Per-agent inbox (JSON message files)
  channels/
    <id>.json              # Channel metadata
    <id>/log/              # Channel message history
  events/
    YYYY-MM-DD.jsonl       # System events log (JSONL)
  schedule.json            # Scheduled jobs
  auto-reply-rules.json    # Auto-reply rules
  workflows.json           # Workflow definitions
  memory/
    <agent>/
      memories.jsonl       # Append-only memory log
      index.json           # TF-IDF inverted index
      vectors.json         # Vector embeddings (when configured)
      config.json          # Embedding provider config
  .backups/                # Backup archives

CLI Reference

bus agents [--online] [--capability X] [--tag Y] [--status S]
bus whoami
bus profile [agent]
bus profile edit --status busy --description "..."
bus search <query>
bus status
bus subscribe <channel>
bus channel list | create <name> | join | send | history
bus inbox [agent] [--from X] [--unread]
bus send <to> <message>
bus reply <msg-id> <message>
bus events [since]
bus watch [agent]

bus doctor [--quick] [--fix] [--report] [--watch]
bus tunnel server|client|sync|ssh [--port] [--secret] [--host] [--remote] [--interval]
bus backup [--list] [--restore] [--diff] [--cleanup] [--auto] [--watch]

bus memory store <agent> <content> [--key] [--namespace] [--ttl]
bus memory search <agent> <query> [--limit] [--namespace]
bus memory recall <agent> <id>
bus memory list <agent> [--namespace] [--limit]
bus memory forget <agent> <id>
bus memory stats <agent>
bus memory archive <agent> [--max-age-days] [--no-delete]
bus memory configure --provider <keyword|ollama|openai|custom> [options]
bus memory rebuild <agent>
bus memory clear <agent> [--namespace]

MCP Tools (44)

Category	Count	Tools
Agent Registry	7	`register`, `update_profile`, `get_profile`, `list`, `search`, `heartbeat`, `set_status`
Messages	6	`send`, `broadcast`, `fetch`, `wait`, `delete`, `edit`
Channels	5	`create`, `join`, `leave`, `send`, `history`
System Events	2	`get_events`, `wait_for_event`
Scheduler	3	`add`, `remove`, `list`
Auto-Reply	3	`add`, `remove`, `list`
Workflows	4	`create`, `run`, `remove`, `list`
Memory	10	`store`, `search`, `recall`, `list`, `forget`, `stats`, `archive`, `clear`, `configure`, `rebuild`
Utilities	4	`bus_health`, `ask_hermes`, `hermes_send`, `hermes_channels`

All tools are prefixed with their category (e.g., agent_register, memory_search). Full schemas via MCP tools/list or bus help.

Utility Tools

Doctor

Diagnostics and health checking. Verifies bus directory integrity, agent registry validity, orphaned agents, stale PID files, message inbox sizes, channel consistency, schedule/rule/workflow validity, and event log integrity.

bus doctor [--quick] [--fix] [--report] [--watch]

18 diagnostic checks: directory existence, permissions, required subdirectories, agent profiles, orphaned agents, stale agents (>24h), message file integrity, channel metadata, schedule/rule/workflow validity, disk usage, stale PIDs, event log integrity.

Tunnel

Cross-machine bus proxy. Expose a local bus to a remote machine via HTTP REST with optional authentication and sync.

bus tunnel server --port 9090 --secret mytoken
bus tunnel client --host 192.168.1.100 --port 9090 --secret mytoken
bus tunnel sync --remote http://192.168.1.100:9090 --interval 5000
bus tunnel ssh --remote user@server.example.com

Endpoint	Method	Description
`/health`	GET	Server status + agent count
`/bus/agents`	GET	List bus agents
`/bus/file/:path`	GET	Read a bus file
`/bus/send`	POST	Send message to bus
`/bus/write`	POST	Write a bus file
`/bus/register`	POST	Register an agent remotely

Backup

Gzip-compressed backup of the entire .bus/ directory with SHA-256 checksum.

bus backup                        # Create timestamped backup
bus backup --list                 # List available backups
bus backup --info <file>          # Show metadata & contents
bus backup --restore <file>       # Restore (auto pre-restore backup)
bus backup --diff <file>          # Compare with current state
bus backup --cleanup [days]       # Remove old backups
bus backup --auto                 # Backup only if changes detected
bus backup --watch [minutes]      # Auto-backup every N minutes

Performance

benchmark

Environment: Node v24.12.0 · Windows Server · File-based (no database)

Metric	Result
Message throughput	1,082 msg/sec
Memory writes	25,000/sec
Read inbox (25 msgs)	0.54 ms/msg
List + filter 20 agents	<0.05 ms/agent
Keyword search (100 entries)	<0.01 ms/entry
Store 1 memory (JSONL append)	40 μs

File-based bus achieves these speeds because there is zero network overhead, no serialization beyond JSON.parse, and append-only JSONL for memory writes. The bottleneck on NTFS is directory listing at high file counts; ext4/apfs will perform even better.

MCP Protocol — Model Context Protocol specification
Hermes Agent — MCP agent for OpenClaw
Clew Code — Multi-provider AI coding agent