ccontext-mcp 0.1.0

MCP server for AI agents to manage project execution context

ccontext-mcp

MCP server that helps AI agents maintain project execution context across sessions.

The Problem

AI agents lose context between sessions. They forget:

• What was the current goal?
• What tasks were in progress?
• What lessons were learned?
• What decisions were made and why?

The Solution

ccontext-mcp provides a simple MCP interface for agents to read and write execution context stored in local YAML files. The context persists across sessions and includes automatic lifecycle management - old information naturally fades away while important items persist.

Installation

Claude Code

# Using uvx (recommended, faster)
claude mcp add ccontext -- uvx ccontext-mcp

# Or using pipx (more universal)
claude mcp add ccontext -- pipx run ccontext-mcp

That's it. The MCP server will auto-detect project root from your current working directory.

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "ccontext": {
      "command": "uvx",
      "args": ["ccontext-mcp"],
      "env": {
        "CCONTEXT_ROOT": "/path/to/your/project"
      }
    }
  }
}

Manual / Other MCP Clients

pip install ccontext-mcp
CCONTEXT_ROOT=/path/to/project python -m ccontext_mcp

Tools

Tool	Purpose
get_context()	Get full execution status. Start here at session begin.
update_context()	Update goal, why, or your agent status
create_task()	Create a new task with steps
update_task()	Update task/step status
delete_task()	Remove a task
list_tasks()	List tasks with optional status filter
add_entry()	Add a note or reference
update_entry()	Update entry content or score
remove_entry()	Remove an entry when no longer relevant

Score-Based Lifecycle

Every note and reference has a score (default: 10, range: 1-100).

• Each get_context() call decrements all scores by 1
• Items with score <= 0 show expiring: true warning
• Items with score <= -5 are auto-archived

Why? Old information naturally fades. Important items should be given high scores (50-100) so they persist longer. This prevents context from growing unbounded.

# Important lesson - will persist ~50 get_context() calls
add_entry(type="note", content="Never use force push on main", score=50)

# Temporary reference - will fade after ~10 calls  
add_entry(type="reference", content="API docs", uri="https://...", score=10)

Directory Structure

your-project/
└── context/
    ├── context.yaml      # Goal, why, agents, notes, references
    ├── tasks/
    │   ├── T001.yaml     # Task definitions
    │   └── T002.yaml
    └── archive/          # Auto-archived items

context.yaml Schema

version: "1"
goal: "Current execution goal - what are we trying to achieve?"
why: "Decision background - why this approach?"
agents:
  AgentA: "Last known status of AgentA"
  AgentB: "Last known status of AgentB"
notes:
  - id: N001
    content: "Important lesson learned"
    score: 45
    created: "2024-01-15T10:30:00Z"
references:
  - id: R001
    content: "Useful documentation"
    uri: "https://docs.example.com"
    score: 8
    expiring: true  # Shows when score <= 0

Task Schema

id: T001
name: "Implement feature X"
goal: "User-visible outcome"
status: active  # planned | active | complete
steps:
  - id: S1
    name: "Design API"
    done: "API spec reviewed"
    status: complete
  - id: S2
    name: "Implement"
    done: "Tests passing"
    status: in_progress

Use Cases

Single Agent

One agent maintains its own context, picking up where it left off each session.

Multi-Agent Collaboration

Multiple agents share the same context/ directory:

• Each updates their status in agents field
• Shared notes and references
• Coordinated task management

Integration with Orchestrators

Works well with agent orchestrators (like CCCC) that can:

• Detect context/ directory existence
• Generate appropriate prompts based on context
• Process progress markers as fallback

Without MCP

If your agent doesn't support MCP, it can directly read/write the YAML files following the schema above. The only difference: no automatic score decay (you'll need to manually clean up old entries).

License

MIT