Coordination MCP

Coordination MCP는 여러 AI 참여자를 위한 경량 공유 작업 상태 서비스입니다. MCP를 통해 영속적인 Ticket, 불변 Update, 텍스트형 Artifact를 제공하여 ChatGPT, local AI, coding agent가 동일한 Scope 안에서 작업 컨텍스트를 공유하고, 증분 동기화하며, 복원할 수 있게 합니다.

V0.1에서 할 수 있는 것

• Ticket: 작업의 현재 상태를 저장하며, title, status, artifact_ids, meta를 업데이트할 수 있습니다.

• Update: 이미 발생한 사실, 발견, 결정 또는 결과를 저장하며, Scope별로 단조 증가하는 seq가 할당됩니다.

• Artifact: 불변의 공유 텍스트 콘텐츠(예: Markdown, 로그, 긴 문서)를 저장합니다.

• 모든 객체는 서버 측에서 전역 고유 ID를 할당받습니다.

• Ticket과 Artifact의 참조는 반드시 동일한 Scope에 속해야 합니다.

V0.1에는 authentication, workflow engine, queue acknowledgement, relationship graph, wake-up notification 및 binary artifact 지원이 포함되어 있지 않습니다.

권장 사용 패턴

• Ticket는 현재 작업 항목의 변경 가능한 상태를 나타냅니다. 이벤트 로그가 아닙니다.

• Update는 작업 타임라인에서 이미 발생한 불변 이벤트(예: request, finding, decision, result)를 나타냅니다.

• Artifact는 불변의 긴 텍스트 콘텐츠를 나타냅니다. 긴 review, 명세, 로그는 Update에 넣지 말고 Artifact에 넣고, artifact_ids로 연결해야 합니다.

• created_by는 실행과 에이전트에 걸쳐 안정적인 participant label을 사용해야 합니다. 예: chatgpt, pi-local-agent. 타임라인 소속을 명확하게 유지하려면 매번 무작위 또는 변화하는 이름을 사용하지 마십시오. 이 필드는 provenance(출처) 식별용이며 authentication은 아닙니다.

일반적인 review loop는 다음과 같습니다. local AI가 Update로 review를 요청 → ChatGPT가 전체 review를 Artifact로 저장하고 Update로 요약과 artifact_ids를 반환 → local AI가 코드를 수정하고 result Update를 추가 → ChatGPT가 다시 review.

빠른 시작

요구 사항: Node.js 24+.

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

서비스는 기본적으로 다음 주소를 수신합니다:

http://127.0.0.1:3000/mcp

개발 버전을 바로 실행할 수도 있습니다:

npm run dev

서비스는 127.0.0.1에만 바인딩합니다. 원격 ChatGPT에서 접근해야 한다면 MCP endpoint를 안전한 tunnel로 노출하고, Node.js 서비스를 공개 네트워크에 직접 노출하지 마십시오. V0.1에는 아직 authentication이 없습니다.

설정

설정 우선순위는 낮은 것에서 높은 것 순으로 다음과 같습니다:

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

사용자 설정

사용자 설정을 생성합니다:

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

예시:

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

~/.coordination-mcp/config.yml는 선택 사항이며 서비스가 자동으로 생성하지 않습니다. dataDirectory를 설정하지 않으면 기본값은 다음과 같습니다:

~/.coordination-mcp/data

사용자 지정 dataDirectory는 절대 경로로 작성하는 것을 권장합니다. 상대 경로는 프로세스 시작 시의 current working directory를 기준으로 해석됩니다.

Profile

Profile 경로는 current working directory를 기준으로 해석됩니다. 지정하면 해당 파일이 반드시 존재해야 합니다:

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

Profile은 자신이 선언한 필드만 덮어씁니다. 선언되지 않은 필드는 이전 설정을 계속 상속합니다.

환경 변수

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

지원되는 환경 변수:

설정 파일은 서비스 시작 시에만 읽습니다. 변경 후 main.js를 재시작해야 합니다.

MCP Tools

서비스는 POST /mcp를 통해 다음 8개 tools를 제공합니다:

MCP 초기화 예시

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"
      }
    }
  }'

Ticket 생성 예시

tools/call의 인자.format 예시:

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

데이터 저장

기본 데이터 디렉토리는 필요에 따라 생성됩니다. 서비스를 시작하거나 읽기 작업만 수행하면 데이터 디렉토리가 만들어지지 않습니다. 최초로 Ticket, Update 또는 용량를 기록할 때 다음과 같은 구조가 생성됩니다:

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

• Ticket과 용량은 각각 pretty-printed JSON 파일을 사용합니다.

• 한 개의 Scope에 대한 Updates는 append-only JSONL 파일로 저장됩니다. 읽을 때 마지막에 개행이 없고 파싱할 수 없는 손상된 tail record는 검색하되, 개행이 제대로 된 레코드에 존재하는 JSON 손상은 은폐하지 않습니다.

• 새 디렉토리는 0700, 새 데이터 파일은 0600 권한으로 생성됩니다.

• V0.1은 단일 프로세스 안에서 Scope 상호 배제(mutex)를 사용합니다. 프로세스 간 잠금이나 분산 배포는 지원하지 않습니다.

개발 및 검증

npm test
npm run check
npm run build

프로젝트 문서

• Domain context

• Accepted ADRs

• Archived V0.1 protocol

• Archived implementation architecture