<div align="center">

<a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/ProPlan-MCP-6366f1?style=for-the-badge" alt="ProPlan MCP" /></a>

ProPlan

Your project roadmap lives inside Claude.

It tracks progress, knows your codebase, and resumes exactly where you left off — every single session.

Quick Start · How It Works · Dashboard · Tools · Manual Setup

</div>

---

The Problem

Every time you open Claude Code, it's a blank slate. You re-explain the project. You re-describe what's done. You remind it what's next.

ProPlan fixes this with one word:

You: continue

Claude: I see we were working on the auth middleware. Last session you finished
        JWT validation but left the refresh token logic incomplete. 3 tasks are
        in progress across Phase 2. Want to pick up from there?

One word. Full context. Every session.

---

What Makes ProPlan Different

There are memory tools for Claude. There are project management tools like Linear and Jira. ProPlan is the only one that does both — inside Claude's tool context.

	Linear / Jira / Notion	Claude's built-in memory	ProPlan
Visual dashboard	✅	❌	✅
Lives inside Claude	❌	✅	✅
Structured roadmap	✅	❌	✅
Reads your codebase	❌	❌	✅
Claude updates it	❌	❌	✅
Syncs across machines	✅	❌	✅

---

Quick Start

npx @proplandev/mcp@latest init

That's it. The setup wizard will:

1. Ask local (SQLite, zero config) or cloud (syncs to the web dashboard)
2. Write your .mcp.json automatically
3. Create a CLAUDE.md so Claude knows to call get_project_status on every session start
4. Update .gitignore so your data isn't accidentally committed
5. Optionally update your Claude settings to skip approval prompts for read-only tools

Then restart Claude Code and type start.

---

How It Works

The Flow

flowchart TD
    A["Your Repo"] -->|npx init| B["Config files written<br/>.mcp.json · CLAUDE.md · .gitignore"]
    B -->|Claude Code starts| C(ProPlan MCP Server)
    C -->|new project| D["scan_repo<br/>→ roadmap generated"]
    C -->|existing project| E["get_project_status<br/>→ full context instantly"]
    C -->|resuming work| F["get_project_status<br/>→ 'last session you were...'"]

    classDef server fill:#6366f1,stroke:#4f46e5,color:#ffffff
    classDef outcome fill:#f0fdf4,stroke:#86efac,color:#166534
    class C server
    class D,E,F outcome

Session Lifecycle

Session Start — get_project_status(include_handoff: true)

• projectGoal — your north-star goal for the project
• lastSession — summary of what was done last time
• recentTasks — tasks worked on recently
• tech_metadata — codebase structure and stack

During Work — after each task

• update_task_status — mark progress with a short note (required)
• add_note_to_task — log observations without changing status

Session End — add_session_summary

• What was worked on
• Decisions made
• What comes next

Roadmap Structure

Project
└── Phase 1: Foundation
    ├── Milestone 1.1: Auth System
    │   ├── Task: Set up JWT ✓ completed
    │   ├── Task: Refresh tokens ◷ in_progress
    │   └── Task: Rate limiting ○ pending
    └── Milestone 1.2: Database
        └── ...
└── Phase 2: Features
    └── ...

---

Dashboard

ProPlan includes a web dashboard at project-planner-7zw4.onrender.com where you can:

• See all your projects and their completion percentage
• Track phases and tasks visually outside of Claude
• Generate your MCP token for cloud sync
• Share progress with teammates or stakeholders

Local → Dashboard

1. Run npx @proplandev/mcp@latest init → choose local
2. Use Claude to build your project — create_project, update tasks as you go
3. Run export_to_cloud with your MCP token from the dashboard Settings
4. View your projects at project-planner-7zw4.onrender.com

Dashboard → Local

1. Sign up at project-planner-7zw4.onrender.com
2. Go to Settings → Claude Code Integration → generate an MCP token
3. Run npx @proplandev/mcp@latest init → choose cloud → paste your token
4. Open Claude Code — your projects sync automatically on every session start

---

Tools

Read Tools (auto-approvable)

Tool	What it does
get_project_status	Status for one or all projects. Pass include_handoff: true for full session resume context in one call.
get_project_roadmap	Full roadmap. summary_only: true for a lightweight view.
get_next_tasks	Next pending or in-progress tasks ordered by phase → milestone.
get_tasks	Filter by status, phase, or keyword. Up to 500 results.
scan_repo	Directory tree + structural code analysis. Persists tech metadata when project_id provided. Hash-cached.

Write Tools (approval required)

Tool	What it does
create_project	Create a project with full phase/milestone/task structure.
update_task_status	Update status with a required note (max 150 chars).
add_note_to_task	Append a note without changing status.
add_task / add_milestone / add_phase	Add items to the roadmap. All support dry_run.
edit_task / edit_milestone / edit_phase	Rename or update. All support dry_run.
delete_task / delete_milestone / delete_phase / delete_project	Delete items. All support dry_run.
rename_project	Rename a project.
set_project_goal	Set the permanent north-star goal shown on every session start.
add_session_summary	Save what was done this session. Capped at 10 — oldest dropped automatically.
export_to_cloud	Sync local SQLite projects to the web dashboard.

---

Skip Approval Prompts

The init wizard offers to do this automatically. If you skipped it, add this to ~/.claude/settings.json:

{
  "allowedTools": [
    "mcp__project-planner__get_project_status",
    "mcp__project-planner__get_next_tasks",
    "mcp__project-planner__get_project_roadmap",
    "mcp__project-planner__get_tasks",
    "mcp__project-planner__add_session_summary",
    "mcp__project-planner__update_task_status",
    "mcp__project-planner__add_note_to_task"
  ]
}

---

Manual Setup

Prefer to edit .mcp.json yourself?

Local mode (SQLite — recommended to start)

{
  "mcpServers": {
    "project-planner": {
      "command": "npx",
      "args": ["-y", "@proplandev/mcp"]
    }
  }
}

Data lives in .project-planner/db.sqlite in your project. Nothing leaves your machine.

Cloud mode (syncs to the web dashboard)

{
  "mcpServers": {
    "project-planner": {
      "command": "npx",
      "args": ["-y", "@proplandev/mcp"],
      "env": {
        "MCP_TOKEN": "your-mcp-token"
      }
    }
  }
}

Get your MCP_TOKEN from the dashboard Settings page.

---

Project Structure

mcp-server/
├── cli.js                  # Entry point — routes init vs MCP server
├── index.js                # MCP server — all tool registrations
├── bin/
│   └── init.js             # Interactive setup wizard
├── adapters/
│   ├── SqliteAdapter.js    # Local SQLite storage
│   └── BackendApiAdapter.js# Cloud API storage
├── tools/                  # One file per MCP tool (24 tools)
├── lib/
│   └── fileAnalyzer.js     # Structural code analyzer (JS/TS/Python/Go/Rust)
└── tests/                  # Jest test suite — 199 tests

---

Requirements

• Node.js 18+
• Claude Code (or any MCP-compatible client)
• For cloud mode: a free account at project-planner-7zw4.onrender.com

---

License

Elastic License 2.0 (ELv2) · Built by Solomon Agyire