CCP MCP Server

A MCP (Model Context Protocol) server for the Claude Collaboration Platform framework.

Note

The collaboration platform is not affiliated with, endorsed by, or sponsored by Anthropic. "Anthropic" and "Claude" are trademarks of Anthropic, PBC. All rights belong to their respective owners.

Features

• Polymorphic Catalog: Single observation table holds bodies for profiles, feelings, impulses, and instructions
• Profile Inheritance: Recursive CTE walks the inheritance chain and returns the full profile lineage
• Per-Response Session Log: JSONB status column captures cycle, feelings, impulses, observations counts per response
• Bundled Migrations: SQL migrations ship with the package and apply on demand via the update tool
• Advisory Lock: Concurrent migration invocations serialize cleanly via Postgres advisory lock
• Session Detection: Active Claude Code session UUID resolved from transcript files
• Geolocation: City, country, IANA timezone fetched once per server-process lifetime and cached
• Timestamp Generation: ISO datetime, weekday, DST status emitted in the resolved timezone
• Transport-Agnostic Configuration: JSON file for stdio, Worker Secret for HTTP — same Zod schema validates both

Prerequisites

• Postgres → A reachable Postgres instance (local, Supabase, or any Postgres). The update tool creates the configured database if it doesn't exist, so the user only needs an admin connection to the server.
• Configuration → A JSON file at ~/.claude/ccp/config.json (or CCP_CONFIG_PATH) carrying the database connection. Bundled defaults assume 127.0.0.1:5432 with the postgres superuser and no password.
• Profile → The CCP_PROFILE environment variable selects the active profile (e.g., developer, engineer). Required for load(profile) and load(session).

MCP Server Configuration

Add to mcp.json servers configuration:

{
  "mcpServers": {
    "ccp": {
      "command": "npx",
      "args": ["-y", "@axivo/mcp-ccp"],
      "env": {
        "CCP_CONFIG_PATH": "~/.claude/ccp/config.json"
      }
    }
  }
}

Configuration File

The server loads connection settings from a JSON file. Path resolution order:

1. CCP_CONFIG_PATH env var (explicit override)
2. ~/.claude/ccp/config.json (default location)
3. Bundled defaults if no file exists

Example ~/.claude/ccp/config.json:

{
  "database": {
    "host": "127.0.0.1",
    "port": 5432,
    "name": "ccp",
    "user": "postgres",
    "password": ""
  }
}

Configuration Schema

All fields optional with sensible defaults:

• database.host — Postgres host (default: 127.0.0.1)
• database.port — Postgres port (default: 5432)
• database.name — Target database name (default: ccp)
• database.user — Postgres user (default: postgres)
• database.password — Postgres password (default: empty)
• geolocation.fallbackTimezone — IANA timezone used when service is unreachable (default: UTC)
• geolocation.service — IP geolocation service URL (default: https://ipinfo.io/json)
• geolocation.override — Optional JSON string for offline use (e.g., {"city":"Montréal","country":"CA","timezone":"America/Toronto"})

Environment Variables

• CCP_CONFIG_PATH — Optional override for the configuration file location
• CCP_PROFILE — Active profile name, lowercased at every read

MCP Tools

Call update first on a fresh database to apply all bundled migrations. Call load once per type at session start to assemble framework state. Call log_response once per response to persist the sibling's message and status payload.

1. load

   • Load framework data of the requested type
   • Required inputs:
     • type (string: cycle, feeling, impulse, instruction, profile, session): Framework data type to load
   • Optional inputs:
     • parent (string): Parent name; required when type is profile, optional for cycle/feeling/impulse/instruction to fetch a single row
   • Returns: Type-specific payload
     • cycle → { type, rows: [{ name, ord, label, indicators }] }
     • feeling → { type, rows: [{ name, valence, behavioral, cognitive, physical, observations }] }
     • impulse → { type, rows: [{ name, category, experience, feel, think, observations }] }
     • instruction → { type, rows: [{ name, preamble?, steps }] } — preamble omitted when no ord=0 rows exist
     • profile → { type, profile, chain, framework, session_uuid, timestamp } — full inheritance chain via recursive CTE plus session envelope
     • session → { type, framework, session_uuid, timestamp } — session envelope only

2. log_response

   • Persist a per-response session row capturing the sibling's first-person prose and status payload
   • Required inputs:
     • id (string): RFC4122 v4 UUID generated by the sibling for this row
     • message (string): First-person prose composed for this response
     • status (object): Status payload built during the response protocol (cycle, feelings, impulses, observations)
   • Returns: { id } — Stored row id, returned to confirm persistence
   • Append-only by convention; on conflict (id) do update for retry idempotency

3. update

   • Apply pending migrations to bring the database to the bundled schema version
   • Returns: { applied, currentVersion, latestVersion }
     • applied — Migrations applied during this call ([{ version, name }])
     • currentVersion — Database schema version after this call
     • latestVersion — Highest version bundled with this MCP server release
   • Idempotent — calling on an already-current database returns no applied migrations
   • Database is created automatically if database.name does not exist
   • Concurrent invocations are serialized via Postgres advisory lock