change-ping-mcp

A local MCP server: a small in-memory event bus for independent AI agents working in the same repository.

Several agents can edit one repo from different clients (any MCP host). They do not share a chat and should not block each other. When a contract changes — not private internals — the author sends a short ping. The other agent reads the summary and keeps working against the current API.

Why

Agents are good at their own slice of the code and slow to notice that a neighbor just renamed a response field or added a Prisma column. PR comments and a shared chat arrive too late and too long.

change-ping-mcp is a shared local channel:

• Contracts only — APIs, database schemas, shared types, Zod/OpenAPI. Refactors, typos, and local edits stay off the bus.

• Summaries only — one to three concrete sentences, no diffs, no fluff.

• No locks — nobody waits for anybody. A ping is a signal, not a barrier.

A good ping looks like this:

[API_UPDATED] POST /api/v1/auth: field token renamed to authToken

Related MCP server: mcp-agent-bridge

How it works

One Node.js process holds an EventBus (history array + EventEmitter) and exposes two MCP tools:

The two URLs are not two buses and not tied to a specific IDE. Same process, same history, same tools. Only the MCP transport changes:

Try /mcp first. If the client cannot connect, use /sse on the same server.

History lives in process memory (up to 200 pings) and is cleared on restart.

While the process is running, the same bus is visible in the browser: http://127.0.0.1:3333. The feed updates in real time, including pings from agents. The page form can send a test ping.

Run

Node.js 18+ is required.

npm install
npm run dev

The server listens on http://127.0.0.1:3333 — open that URL in a browser. Health check:

curl http://127.0.0.1:3333/health

Build without tsx:

npm run build
npm start

Override bind address with PORT=3333 HOST=127.0.0.1 npm run dev.

Connect any agent

Point any MCP client at the bus as a remote/HTTP MCP server. Config shape differs by host; the URL does not.

{
  "url": "http://127.0.0.1:3333/mcp"
}

If the host only supports legacy SSE:

{
  "url": "http://127.0.0.1:3333/sse"
}

Where to put that URL is up to the client (mcp.json, opencode.json, claude_desktop_config.json, and so on). The server name can be anything; the tools are emit_change_ping and get_latest_pings.

When to ping belongs in the working project's agent rules (AGENTS.md, system prompt), not in this repository. The server runs without that; agents just will not know to call the tools.

Typical loop

1. Agent A calls get_latest_pings before touching a shared contract.

2. Does its work.

3. If it moved an API, schema, or shared type — emit_change_ping immediately.

4. Agent B repeats step 1 and picks up the change.

Agents do not sync sessions and do not send full diffs. The bus only stores short facts the neighbor depends on.

License

MIT