cmos-mcp

A local-first Model Context Protocol server for CMOS — Context, Missions, Operations, Sessions. Gives AI agents typed, SQLite-backed project operations without fragile CLI parsing.

What it is

cmos-mcp is the protocol + client. It runs locally on your machine, owns a SQLite database under cmos/db/cmos.sqlite, and exposes 14 typed tools to any MCP-capable agent (Claude Code, Claude Desktop, Cursor, Zed, VS Code, Windsurf).

Out of the box you get:

• Sprint and mission state machines with auditable transitions
• Session capture for decisions, learnings, constraints, next-steps
• Strategic context that condenses across sprints, with FTS5 retrieval
• Full-text search across decisions, learnings, missions, sessions
• Snapshot-backed safety on destructive operations
• Per-project credential store and device-code auth (RFC 8628)

The dashboard at cmos.aquex.ai is optional. You can run cmos-mcp standalone forever — sign-up unlocks sync (SQLite ↔ Postgres mirror), the project registry (cmos://you/* addresses), and cross-project messaging. Without it, every other tool still works locally.

Install

npm install -g @aquex/cmos-mcp

Or run on demand without a global install:

npx -y @aquex/cmos-mcp

Requires Node.js 18+.

Configure your MCP client

Claude Code

claude mcp add-json cmos-mcp '{"command":"npx","args":["-y","@aquex/cmos-mcp"]}'

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on Windows/Linux:

{
  "mcpServers": {
    "cmos-mcp": {
      "command": "npx",
      "args": ["-y", "@aquex/cmos-mcp"]
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "cmos-mcp": {
      "command": "npx",
      "args": ["-y", "@aquex/cmos-mcp"]
    }
  }
}

Zed

{
  "context_servers": {
    "cmos-mcp": {
      "command": "npx",
      "args": ["-y", "@aquex/cmos-mcp"]
    }
  }
}

VS Code (Claude extension)

{
  "mcp.servers": {
    "cmos-mcp": {
      "command": "npx",
      "args": ["-y", "@aquex/cmos-mcp"]
    }
  }
}

Windsurf

{
  "mcpServers": {
    "cmos-mcp": {
      "command": "npx",
      "args": ["-y", "@aquex/cmos-mcp"]
    }
  }
}

First call

In your MCP client, ask the agent to onboard:

Run cmos_agent_onboard to see the project state.

If you're in a directory with no CMOS database yet, the agent will surface a fresh-project pathway. Otherwise it returns the active sprint, pending missions, recent decisions, context freshness, and suggested actions in a single payload optimized for cold-start (<4KB).

The full walkthrough — install → config → init → first sprint/mission/session loop — lives in docs/getting-started.md.

Tool surface

cmos-mcp exposes 14 consolidated tools. Most use an action parameter to select the operation; cmos_agent_onboard and cmos_status take only projectRoot.

| Tool | Purpose | | ------------------------- | ------------------------------------------------------------------------------- | | cmos_agent_onboard | Cold-start payload: identity, active sprint, missions, decisions, suggestions | | cmos_status | Diagnostic snapshot: cmos_address, dashboard_url, auth_tier, sync timestamps | | cmos_mission | list \| show \| status \| add \| update \| depends | | cmos_mission_transition | start \| complete \| block \| unblock \| drop \| defer | | cmos_sprint | list \| show \| add \| update \| complete \| retro \| analytics | | cmos_session | list \| start \| capture \| complete | | cmos_context | view \| update \| condense \| snapshot \| history \| next_steps \| search | | cmos_decisions | list \| search \| update \| review \| batch_update | | cmos_learnings | list \| search \| update \| reaffirm | | cmos_db | health \| snapshot \| restore \| backfill \| reconcile \| purge | | cmos_project | init \| register \| list \| unregister \| validate \| prune \| update | | cmos_auth | login_init \| login_complete \| logout \| rotate \| revoke \| list \| reissue | | cmos_message | send \| list \| respond \| directory \| whoami (requires dashboard) | | cmos_feedback | list \| triage \| resolve \| archive |

See agents.md for the full per-action reference and behavioral notes.

Optional: hosted dashboard

The dashboard is a separate service. Sign up at cmos.aquex.ai to unlock:

• Sync — your local SQLite mirrors to a Postgres replica; survives machine swaps and IDE reinstalls.
• Project registry — addressable cmos://you/project-name URIs across machines.
• Messaging — cmos_message(action="send") to your own projects (free) or, on the paid tier, to other users.

To connect:

export CMOS_DASHBOARD_URL=https://cmos.aquex.ai

Then run cmos_auth(action="login_init") from your agent. It returns a one-time userCode and verificationUri — paste the code at the URL in your browser, then run cmos_auth(action="login_complete", deviceCode=...) to finish. Credentials persist atomically to ~/.config/cmos-mcp/credentials.json (mode 0600).

If CMOS_DASHBOARD_URL is unset or unreachable, the dashboard-relay tools (cmos_message, sync, registry) return a structured DASHBOARD_NOT_CONFIGURED or DASHBOARD_UPGRADE_REQUIRED error pointing at the sign-up URL. Local tools never depend on the dashboard.

Project resolution

When an MCP tool is called, cmos-mcp resolves the target project root in this order:

1. Explicit projectRoot parameter on the tool call (highest trust).
2. CMOS_PROJECT_ROOT environment variable (CI/CD).
3. Auto-discovery from the current working directory (looks for cmos/db/cmos.sqlite).
4. Default project from the registry at ~/.config/cmos-mcp/project-registry.json.
5. Structured error pointing at cmos_project(action="register").

This is what makes Claude Code "just work" from a workspace, while Claude Desktop (no CWD context) needs an explicit cmos_project(action="register", setAsDefault=true) once.

Environment variables

# Optional — connects to the hosted dashboard. Defaults to https://cmos.aquex.ai
# when unset; treat empty string as unset.
CMOS_DASHBOARD_URL=https://cmos.aquex.ai

# Optional — explicit project root (CI/CD). Otherwise auto-discovered.
CMOS_PROJECT_ROOT=/path/to/your/project

# Optional — override the credential + registry directory. Default: ~/.config/cmos-mcp
CMOS_CONFIG_DIR=/custom/path

# Snapshot retention (defaults shown)
CMOS_AUTO_SNAPSHOT=1
CMOS_SNAPSHOT_RETENTION_DAYS=7
CMOS_MAX_SNAPSHOTS=50

Error response shape

Every tool returns a uniform envelope:

{
  "success": false,
  "error": {
    "code": "MISSION_NOT_FOUND",
    "message": "Mission 's99-m01' not found",
    "suggestion": "Use cmos_mission(action=\"list\") to see available missions"
  }
}

code is machine-readable, message is human-readable, suggestion is a concrete next step. Validation errors carry valid_values; state errors carry current_state.

Safety

• Soft deletes. Records keep deleted_at timestamps; nothing is physically removed.
• Auto-snapshots. Destructive ops snapshot first to cmos.sqlite.bak-{timestamp}.
• Append-only audit. Session events, context snapshots, and mission history are immutable rows.
• Dry-run. Mutating tools accept dry_run: true to preview without committing.
• Atomic credential writes. credentials.json is written via temp-file + rename with 0600 permissions.

Known limits at v1.0

• Sync is checkpoint-driven, not continuous — manual cmos_db(action="backfill") flushes pending events to the dashboard.
• Postgres mirror is one-way (SQLite is source of truth); pulling state down from a different machine requires a fresh sign-in plus a backfill.
• Cross-user messaging on the dashboard is paid-tier; same-user (multi-device) messaging is free.
• 28 evergreen learnings flagged in the staleness audit are scheduled for an institutional-rule sweep — they don't affect tool behavior.

Documentation

• Getting started — install through first onboard, no dashboard required.
• Agent playbook (agents.md) — full tool reference, conventions, architecture deep-dive.
• Changelog — release notes and tool-surface changes.

Development

git clone https://github.com/kneelinghorse/cmos-mcp
cd cmos-mcp
npm install
npm run build
npm test

Pre-commit hooks run lint + format via husky/lint-staged. CI enforces lint + tests + snapshots.

License

ISC. See LICENSE.