@contorium/mcp

MCP Runtime Adapter for Contorium Project Intelligence

A Model Context Protocol (MCP) runtime that connects AI coding agents to Contorium’s Project Intelligence Layer (PIL).

It enables AI tools like:

• Claude Code
• OpenAI Codex
• Cursor
• Gemini CLI
• VS Code MCP
• Any MCP-compatible runtime

to access structured project intelligence.

Core Purpose

Contorium MCP is not an agent.

It is a bridge between AI tools and project intelligence.

It provides:

• Inspect → read project intelligence
• Capture → write structured memory
• Transfer → move intelligence across sessions

Architecture Overview

AI Host (Claude / Codex / Cursor)
        ↓
   MCP Runtime (@contorium/mcp)
        ↓
   @contora/state-core (CIL + PIL Engine)
        ↓
   .contora/ (Local Project Intelligence Store)

Design Principle

MCP does NOT execute tasks
MCP does NOT make decisions

It only:

• exposes project intelligence
• synchronizes state
• enables continuity

Project Intelligence Model (PIL v3)

Contorium MCP operates on a structured intelligence model:

Core Layer

• STATE → current project state
• INTENT → project goals
• DECISION → architecture decisions
• WHY → reasoning behind decisions

Extended Layer

• TIMELINE → evolution over time
• IMPACT → dependency relationships
• CONFIDENCE → reliability scoring
• PROVENANCE → origin tracking
• EVOLUTION → structural changes

Core Capabilities

1. Inspect (Read-only Intelligence)

Used by AI agents to understand project context.

inspect_state
inspect_intent
inspect_decision
inspect_why
inspect_timeline
inspect_impact
inspect_health
inspect_graph
inspect_provenance

2. Capture (Write Intelligence)

Used to persist structured project memory.

capture_focus
capture_note
capture_decision

3. Transfer (AI Continuity Export)

Used to move project intelligence across sessions.

| Tool | Purpose | Size | | --- | --- | --- | | transfer_context | lightweight continuation | ~300–800 tokens | | transfer_handoff | runtime continuation | ~100–300 tokens | | transfer_intelligence | full project export | ~8000 tokens |

Typical AI Agent Flow

1. inspect_state
2. inspect_intent
3. inspect_decision
4. perform work (external AI tool)
5. capture_note / capture_decision
6. transfer_context (session handoff)

MCP Runtime Contract

Read Layer

inspect_*

Provides deterministic access to:

• state
• intent
• decisions
• timeline
• graph
• health

Write Layer

capture_*

Persists:

• focus updates
• notes
• decision logs

Transfer Layer

transfer_*

Exports structured intelligence for AI continuity.

CIL Integration (Recommended)

MCP does NOT handle natural language directly.

All reasoning flows through CIL:

ask_project
get_next_actions
get_project_history
get_decision_graph
get_cognitive_health
get_knowledge_health
get_review_queue
set_decision_lifecycle_meta
get_project_essence
get_snapshot
get_entity_knowledge

Decision validity (Knowledge Lifecycle v2)

Same lifecycle engine as CLI and IDE — not a separate store.

| Tool | Purpose | | --- | --- | | get_knowledge_health | Project knowledge health + per-decision trust | | get_review_queue | Stale, expired, conflict, and invalidation triggers | | set_decision_lifecycle_meta | Set owner, verification, expiry (tracks owner changes) | | ask_project | Decision questions include validity, why, and suggested action |

CLI equivalents: contorium lifecycle · contorium review · contorium lifecycle owner|verify

MCP = access layer
CIL = cognition layer

AI Layer (Optional)

Contorium supports optional LLM enhancement for:

• Why explanation
• Story generation
• Essence compression
• Project DNA summarization

Important

• LLM is NOT required
• All core intelligence remains deterministic
• LLM is only for interpretation

Configuration

Workspace

CONTORIUM_WORKSPACE=/your/project/root

LLM Config (Optional)

Stored in:

.contora/config/llm.json

Used for:

• explanation generation
• narrative synthesis

No secrets stored in repo (API keys are gitignored).

Installation

npm (recommended)

npm install -g @contorium/mcp

From source

git clone https://github.com/ContoriumLabs/contorium.git
cd contorium
npm install
npm run compile

MCP Host Setup

Claude Code

claude mcp add --scope project contorium -- npx @contorium/mcp

OpenAI Codex

codex mcp add contorium -- npx @contorium/mcp

Cursor / VS Code / Gemini CLI

Supports standard MCP registration:

{
  "mcpServers": {
    "contorium": {
      "command": "npx",
      "args": ["@contorium/mcp"]
    }
  }
}

Local-First Design

All intelligence stays local:

.contora/
├── state.json
├── handoff.json
├── intent/
├── timeline/
├── graph/
├── events/
├── intelligence/
├── governance/
├── config/
│   ├── llm.json
│   └── .llm-keys.json (gitignored)
├── cache/llm/

No cloud dependency.

No vendor lock-in.

CLI Equivalents

| MCP Tool | CLI Command | | --- | --- | | inspect_* | contorium inspect | | capture_* | contorium capture | | transfer_* | contorium transfer |

Legacy Compatibility

Deprecated but supported:

• get_project_*
• get_cognitive_snapshot
• transfer_runtime
• get_full_intelligence

Supported MCP Hosts

• Claude Code
• OpenAI Codex
• Cursor
• Gemini CLI
• VS Code MCP
• Any MCP-compatible runtime

Key Insight

MCP is not intelligence.
It is the transport layer of intelligence.

Links

• Project: https://github.com/ContoriumLabs/contorium
• Overview: https://github.com/ContoriumLabs/contorium/blob/main/docs/OVERVIEW.md
• PIL Guide: https://github.com/ContoriumLabs/contorium/blob/main/docs/PIL_RUNTIME.md
• AI Layer: https://github.com/ContoriumLabs/contorium/blob/main/docs/AI_LAYER.md
• MCP Docs: https://github.com/ContoriumLabs/contorium/blob/main/docs/MCP.md
• Knowledge Lifecycle: https://github.com/ContoriumLabs/contorium/blob/main/docs/LIFECYCLE_V1.md
• Install Guide: https://github.com/ContoriumLabs/contorium/blob/main/docs/INSTALL.md

License

MIT