Metadata-Version: 2.4
Name: ccontext-mcp
Version: 0.1.0
Summary: MCP server for AI agents to manage project execution context
Author: CCCC Team
License-Expression: MIT
Keywords: agent,ai,context,mcp,project-management
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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

```bash
# 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`:

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

### Manual / Other MCP Clients

```bash
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.

```python
# 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

```yaml
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

```yaml
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
