https://github.com/vncsleal/openplan
Waze for AI agents planning — an MCP server that improves cost estimates by learning from every project.
https://github.com/vncsleal/openplan
ai-agent ai-planning cost-estimation cost-tracking developer-tools mcp model-context-protocol open-source opencode planning project-management sqlite typescript
Last synced: about 20 hours ago
JSON representation
Waze for AI agents planning — an MCP server that improves cost estimates by learning from every project.
- Host: GitHub
- URL: https://github.com/vncsleal/openplan
- Owner: vncsleal
- License: mit
- Created: 2026-06-16T14:14:57.000Z (9 days ago)
- Default Branch: main
- Last Pushed: 2026-06-18T19:02:32.000Z (7 days ago)
- Last Synced: 2026-06-18T19:18:36.209Z (7 days ago)
- Topics: ai-agent, ai-planning, cost-estimation, cost-tracking, developer-tools, mcp, model-context-protocol, open-source, opencode, planning, project-management, sqlite, typescript
- Language: Python
- Homepage: https://openplan.cc
- Size: 587 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# OpenPlan MCP Server
**Waze for AI agents** — plan, track, and learn from software projects.
An [MCP](https://modelcontextprotocol.io) server that helps AI agents decompose goals into costed execution plans, checkpoint progress with deviation tracking, and learn from past project data.
## Quick Start
```bash
npx @openplan/mcp
```
The server auto-creates its config and SQLite database on first run — no setup needed.
Add it to your MCP client:
**opencode.json:**
```json
{
"mcp": {
"openplan": {
"type": "local",
"command": ["npx", "-y", "@openplan/mcp"]
}
}
}
```
**claude_desktop_config.json:**
```json
{
"mcpServers": {
"openplan": {
"command": "npx",
"args": ["-y", "@openplan/mcp"]
}
}
}
```
Or run `openplan install` to auto-detect and configure both.
## Tools (3)
| Tool | Description |
|------|-------------|
| `plan(goal, context?, replan?, project?)` | Decompose a goal into costed phases with estimates |
| `checkpoint(phase?, actual_cost?, correct?, route_id?, project?)` | Record phase cost, correct data, or check status |
| `review(route_id?, project?)` | Session retrospective with deviations, accuracy, learning |
## Resources (3)
| URI | Description |
|-----|-------------|
| `openplan://{project}/route` | Current route state and phase progress |
| `openplan://profiles` | Personal bias and accuracy by action |
| `openplan://sync-status` | Mesh sync health and pending checkpoints |
## CLI
```bash
openplan # Start MCP server (stdio mode)
openplan install # Auto-detect and install in MCP clients
openplan auth # Authenticate with Mesh via GitHub OAuth
openplan subscribe # Subscribe to Pro (Stripe Checkout)
openplan portal # Manage subscription (Stripe Customer Portal)
openplan account # Show identity, API key, subscription
openplan config # View current configuration
openplan mesh [on|off] # Show or toggle Mesh sync
openplan status # List routes for a project
openplan log # Show checkpoint trail
openplan export # Export calibration data (Pro)
openplan completion # Generate shell completion script
openplan doctor # Check system health and diagnose issues
```
Use `--json` on `account`, `config`, `status`, `log`, `mesh` for structured output. Auth supports `--no-browser`, `--clipboard`, `--with-token `, and `--debug`.
## Architecture
```
core/ Domain types, pure logic, typed ports
handlers/ MCP tool handlers — validation, wiring
adapters/ Mesh sync, cost probes, config loaders
db/ Drizzle schema, SQLite, DataStore implementation
```
**One rule:** Core never imports adapters or handlers. The `DataStore` port insulates core from Drizzle.
## Development
```bash
npm install
npm run dev # tsx watch
npm test # vitest (config at vitest.config.ts)
npm run test:e2e # end-to-end against compiled dist/
npm run build # tsc
npm run lint # biome check
```
### CI/CD
GitHub Actions runs lint, test, build on every push/PR. Publish to npm happens automatically on version tags (`v*`).
## Stack
- **FastMCP** — MCP framework with Zod schemas for input validation
- **SQLite** via `better-sqlite3` / Drizzle ORM — 7 tables, local-first
- **Mesh API** (proprietary, at `github.com/vncsleal/openplan-api`) — cross-session cost learning
- **Structured logging** — `createLogger(module)` with `[openplan:module]` prefix
- **Coverage** — Vitest with 60% branch / 65% line thresholds
License: MIT