Coordination MCP

Coordination MCP is a lightweight shared work-state service for multiple AI participants. It provides persistent Tickets, immutable Updates, and text-based Artifacts through MCP, allowing ChatGPT, local AI, and coding agents to share, incrementally synchronize, and restore work context within the same Scope.

What V0.1 can do

• Ticket: stores the current state of a piece of work; title, status, artifact_ids, and meta can be updated.

• Update: stores facts, findings, decisions, or results that have already occurred, assigned monotonically increasing seq per Scope.

• Artifact: stores immutable shared text content, such as Markdown, logs, or long documents.

• All objects are assigned globally unique IDs by the server.

• References to Ticket and Artifact must belong to the same Scope.

V0.1 does not include authentication, a workflow engine, queue acknowledgement, a relationship graph, wake-up notification, or binary artifact support.

Recommended usage patterns

• Ticket represents the current mutable state of an ongoing work item; it is not an event log.

• Update represents immutable events that have already occurred in the work timeline, such as requests, findings, decisions, or results.

• Artifact represents immutable long-form text content; long reviews, specifications, or logs should go into Artifact, not be stuffed into Update, and should be linked via artifact_ids.

• created_by should use a participant label that is stable across runs and across agents, such as chatgpt or pi-local-agent; do not use random or changing names each time, so that timeline attribution stays clear. This field is for provenance, not authentication.

A typical review loop is: a local AI requests review via Update → ChatGPT saves the full review as an Artifact and returns a summary and artifact_ids via an Update → the local AI fixes the code and appends a result Update → ChatGPT reviews again.

Quick start

Requirements: Node.js 24+.

cd /path/to/coordination-mcp
npm install
npm run build
node dist/main.js

The service listens on the following by default:

http://127.0.0.1:3000/mcp

You can also run the development version directly:

npm run dev

The service only binds to 127.0.0.1. If you need remote ChatGPT to access it, expose the MCP endpoint through a secure tunnel; do not expose the Node.js service directly to the public internet. V0.1 has no authentication yet.

Configuration

Configuration precedence, from lowest to highest, is:

代码默认值 < config/default.yml < ~/.coordination-mcp/config.yml < --profile < 环境变量

User configuration

Create a user configuration:

mkdir -p ~/.coordination-mcp
$EDITOR ~/.coordination-mcp/config.yml

Example:

port: 43721
allowedHosts:
  - 127.0.0.1
  - localhost
# dataDirectory: /absolute/path/to/coordination-data

~/.coordination-mcp/config.yml is optional and is not generated automatically by the service. When dataDirectory is not set, the default is:

~/.coordination-mcp/data

It is recommended to write a custom dataDirectory as an absolute path. Relative paths are resolved against the current working directory at process startup.

Profile

Profile paths are resolved relative to the current working directory; once specified, the file must exist:

node dist/main.js --profile config/local.yml
node dist/main.js --profile=/absolute/path/to/local.yml

A profile only overrides the fields it declares; undeclared fields continue to inherit from the preceding configuration.

Environment variables

PORT=43721 \
COORDINATION_DATA_DIR=/absolute/path/to/data \
COORDINATION_ALLOWED_HOSTS=127.0.0.1,localhost \
node dist/main.js

Supported environment variables:

The configuration file is read only at service startup; after modifying it, restart main.js.

MCP Tools

The service exposes the following 8 tools via POST /mcp:

MCP initialization example

curl -N \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Content-Type: application/json' \
  -H 'mcp-protocol-version: 2025-03-26' \
  -X POST http://127.0.0.1:3000/mcp \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {
        "name": "manual-client",
        "version": "0.1.0"
      }
    }
  }'

Create Ticket example

Example tools/call arguments:

{
  "name": "create_ticket",
  "arguments": {
    "scope": "coordination-mcp",
    "title": "Review the MCP integration",
    "created_by": "local-ai",
    "status": "open",
    "meta": {
      "priority": "high"
    }
  }
}

Data storage

The default data directory is created on demand; starting the service or performing read operations alone will not create the data directory. The first time a Ticket, Update, or Artifact is written, a structure similar to the following is created:

~/.coordination-mcp/
├── config.yml                 # 可选用户配置
└── data/
    └── scopes/
        └── <base64url-scope>/
            ├── tickets/
            │   └── T-*.json
            ├── updates.jsonl
            └── artifacts/
                └── A-*.json

• Tickets and Artifacts use separate, pretty-printed JSON files.

• Updates for a Scope use an append-only JSONL file; at read time, a corrupt trailing record that is not newline-terminated and cannot be parsed is ignored, but JSON corruption in fully newline-terminated records is not hidden.

• New directories use 0700, and new data files use 0600.

• V0.1 uses an in-process Scope mutex; cross-process locking or distributed deployment is not supported.

Development and validation

npm test
npm run check
npm run build

Project documentation

• Domain context

• Accepted ADRs

• Archived V0.1 protocol

• Archived implementation architecture