Metadata-Version: 2.4
Name: openplan-mcp
Version: 0.8.2
Summary: Waze for AI agents planning — MCP server that improves cost estimates by learning from every project
Author: OpenPlan Contributors
License: MIT
Project-URL: Homepage, https://github.com/anomalyco/opencode
Project-URL: Documentation, https://opencode.ai/docs/openplan
Project-URL: Source, https://github.com/anomalyco/opencode/tree/main/docs/workflow/openplan
Project-URL: Changelog, https://github.com/anomalyco/opencode/blob/main/docs/workflow/openplan/CHANGELOG.md
Keywords: mcp,planning,ai-agent,state-space,project-management,model-context-protocol
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp<2.0.0,>=1.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: httpx>=0.28.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: ruff>=0.5.0; extra == "dev"
Provides-Extra: embed
Requires-Dist: fastembed>=0.5.0; extra == "embed"
Provides-Extra: ann
Requires-Dist: sqlite-vec>=0.1.9; extra == "ann"
Provides-Extra: all
Requires-Dist: openplan[ann,dev,embed]; extra == "all"
Dynamic: license-file

# OpenPlan

**AI-native state space planner. MCP server. Python. 4 tools.**

OpenPlan is an MCP server that gives AI agents a structured planning and memory system. Instead of tasks and milestones, everything is a **state** in a directed graph with probabilistic edges, auto-calibrating costs, and A* pathfinding that tells the agent where to go next.

## Tools (4)

`init` — Create a new project context (idempotent). Accepts `project_type` for cost baselines and `goal` for tracked achievement markers.

`act` — The only mutation tool. Traverses edges, creates branches (auto-sequenced by default, `parallel=True` for fan-out), sets status, attaches evidence (with filesystem verification), prunes subtrees, reverts, and verifies goal satisfaction.

`recommend` — Returns the best next target with an A* path, confidence intervals, effective costs, project health, goal progress, cross-project estimation by type, and self-tuning bandit state.

`export` — Export the full graph as JSON, GraphML, or adjacency matrix.

## Quick Start

```bash
pip install -e ".[dev]"

# Start the MCP server
openplan-server
```

Configure MCP in your opencode.json / claude_desktop_config.json:

```json
{
  "mcp": {
    "openplan": {
      "type": "local",
      "command": ["/path/to/.venv/bin/python", "-m", "openplan.server"],
      "cwd": "/path/to/openplan"
    }
  }
}
```

## Architecture

```
  MCP transport (stdio)
       │
  server.py (dispatch)
  ┌──────┴──────┐
  core/         db/
  ├─ state.py   ├─ connection.py
  ├─ graph.py   ├─ schema.py
  ├─ planner.py ├─ ...
  ├─ activation.py
  ├─ embedding.py
  ├─ export.py
  ├─ recommend.py
  ├─ telemetry.py
  └─ maintenance.py
```

**Shell imports core. Core never imports shell.**
SQLite with WAL mode, foreign keys, savepoints. RW lock for concurrency.

## Data Model

```
nodes:    id, label, activation, frontier, project, props, parent_id, status, project_type
edges:    source_id, target_id, action, cost_tokens, cost_risk, prob, weight_history
events:   id, project, node_id, event_type, payload, version, idempotency_key, session_id
goal_markers: project, criterion, achieved, achieved_by
evidence: id, project, state_id, evidence_type, uri, status, metadata (size, mtime)
```

## Testing

```bash
pip install -e ".[dev]"
pytest tests/ -v
```

## License

MIT
