pm-server 0.4.0

Project management MCP Server for Claude Code — track tasks, visualize progress, manage decisions

pm-server

日本語版 README はこちら

Project management MCP Server for Claude Code.

Track tasks, visualize progress, record decisions — all through natural language in your Claude Code session.

> 進捗は？
✓ Phase 1 "Backend API": 60% complete (12/20 tasks)
  - 3 tasks in progress, 1 blocked
  - Velocity: 8 tasks/week (↑ trending up)

> 次にやること
1. [P0] MYAPP-014: Add user authentication endpoint
2. [P1] MYAPP-015: Implement rate limiting
3. [P1] MYAPP-018: Write integration tests

> MYAPP-014 に着手
✓ MYAPP-014 → in_progress

---

Features

• 30 MCP tools — task CRUD, child issues, status, blockers, velocity, dashboard, ADR, session memory, workflows, knowledge records, and more
• Workflow engine — template-based development workflows with loops, user gates, and chaining (Discovery → Development)
• Knowledge records — structured findings between casual memory and formal ADR (research, tradeoff, spec, etc.)
• Super Research skill — 3 parallel agents (Domain Expert, Critical Analyst, Lateral Thinker) + Depth Check (6 dimensions) + Fact Check + Cross-Check
• Session memory — SQLite + FTS5 full-text search. Memories persist across sessions and link to tasks/decisions
• Cross-project search — search memories across all projects via a global index
• Natural language — say "進捗は？" or "what's next?" instead of memorizing commands
• Zero configuration — pip install + pm-server install, then just say "PM初期化して"
• Multi-project — manage all your projects from a global registry with cross-project dashboards
• Git-friendly — plain YAML files in .pm/ directory, trackable with git diff
• Non-invasive — adds only a .pm/ directory to your project. rm -rf .pm/ to remove completely

---

Quick Start

Install (once)

pip install pm-server
pm-server install       # Registers MCP server in Claude Code
# Restart Claude Code

Update

pip install --upgrade pm-server
# Restart Claude Code

Note: pip install pm-server without --upgrade will NOT update an existing installation. Always use --upgrade (or -U) to get the latest version.

After upgrading, the CLAUDE.md auto-action rules in each project are automatically updated:

1. On the next session start, pm_status detects the template version mismatch
2. Claude Code runs pm_update_claudemd to update the rules section
3. New features (e.g., child issue workflow) become active immediately

You can also update manually:

> CLAUDE.md を更新して    # or: pm_update_claudemd

Initialize a project

# In Claude Code, cd to your project directory
> PM初期化して
✓ .pm/ created
✓ Registered in global registry
✓ Detected: name=my-app, version=1.2.0 (from package.json)

pm-server automatically detects project info from package.json, pyproject.toml, Cargo.toml, .git/config, and README.md.

Use it

You say	What happens
進捗は？ / status	Show project progress summary
次にやること / what's next	Recommend next tasks by priority & dependencies
タスク追加：○○を実装	Add a new task (auto-numbered)
MYAPP-003 完了	Mark task as done
MYAPP-003 に課題がある	Add child issue to task (auto-inherits phase)
ブロッカーある？	List blocked tasks
ダッシュボード見せて	Generate HTML dashboard (Chart.js, dark theme)
この設計にした理由を記録	Record an Architecture Decision Record (ADR)
全プロジェクトの状態	Cross-project portfolio view

---

MCP Tools (30 tools)

Project Management

Tool	Description
pm_init	Create .pm/, register in global registry, auto-detect project info
pm_status	Phase progress, task summary, blockers, velocity, active tasks, hook auto-setup
pm_tasks	List tasks with filters (status / phase / priority / tag)
pm_add_task	Add task with auto-numbered ID (e.g., MYAPP-001)
pm_update_task	Update status, priority, notes, blocked_by
pm_next	Recommend next tasks (excludes blocked / unmet dependencies)
pm_blockers	List blocked tasks across projects
pm_add_issue	Add child issue to a task (phase auto-inherited, parent auto-reverted to review)

Records

Tool	Description
pm_log	Daily log entry with auto task linking (progress / decision / blocker / note / milestone)
pm_add_decision	Add ADR with context, decision, and consequences

Analysis

Tool	Description
pm_velocity	Weekly velocity + trend (up / down / flat)
pm_risks	Auto-detect risks: overdue, stale, long-blocked tasks

Visualization

Tool	Description
pm_dashboard	HTML dashboard with workflow progress + knowledge map (single project or portfolio)

Discovery

Tool	Description
pm_discover	Scan directories for .pm/ projects and auto-register
pm_cleanup	Remove invalid paths from registry
pm_list	List all registered projects

Memory (Session Continuity)

Tool	Description
pm_remember	Save a memory with auto task linking (observation / insight / lesson)
pm_recall	Recall memories — FTS5 search, by task, or cross-project
pm_session_summary	Save / get / list session summaries for continuity
pm_memory_search	Advanced search with type, tag, and task filters
pm_memory_stats	Memory DB statistics (total, by type, DB size)
pm_memory_cleanup	Clean up old memories (dry-run supported)

Knowledge Records

Tool	Description
pm_record	Record structured knowledge (research / market / spike / tradeoff / spec / api_design)
pm_knowledge	Query, filter, update, and summarize knowledge records

Workflow Engine

Tool	Description
pm_workflow_start	Start a workflow from a template (development / discovery / super-research)
pm_workflow_status	View current step, progress, and guidance for active workflow
pm_workflow_advance	Advance to next step with artifacts and notes; supports loops and skip
pm_workflow_list	List all workflow instances with status filter
pm_workflow_templates	List available workflow templates (built-in + custom)

Maintenance

Tool	Description
pm_update_claudemd	Update PM Server rules section in CLAUDE.md to latest version

---

Data Structure

pm-server stores task data as plain YAML and memories in SQLite:

your-project/
└── .pm/
    ├── project.yaml        # Project metadata
    ├── tasks.yaml          # Tasks with status, priority, dependencies
    ├── decisions.yaml      # Architecture Decision Records (ADR)
    ├── knowledge.yaml      # Structured knowledge records
    ├── workflows.yaml      # Workflow instances and state
    ├── milestones.yaml     # Milestone definitions
    ├── risks.yaml          # Risks and blockers
    ├── memory.db           # Session memories (SQLite + FTS5)
    ├── workflow_templates/  # Custom workflow templates (optional)
    └── daily/
        └── 2026-04-08.yaml # Auto-generated daily log

~/.pm/
├── registry.yaml           # Global project index
└── memory.db               # Cross-project memory index

YAML files are human-readable and hand-editable. Memory DB is the source of truth for session data; the global index at ~/.pm/memory.db enables cross-project search.

---

CLAUDE.md Integration

Add this to your project's CLAUDE.md for automatic PM behavior (or run pm-server update-claudemd):

## PM Server 自動行動ルール（必ず従うこと）

### セッション開始時（最初の応答の前に必ず実行）
1. pm_status を MCP ツールとして実行し、現在の進捗を表示する
2. pm_next で次に着手すべきタスクを3件表示する
3. pm_recall で前回セッションの文脈を取得する
4. ブロッカーや期限超過があれば警告する
5. pm_status の claudemd.other_rule_sections に他のルールセクションが報告された場合、この CLAUDE.md 内の該当セクションのルールも全て実行する

### タスクに着手する前
1. 該当タスクを pm_update_task で in_progress に変更する

### 作業中に重要な発見・判断があった時
1. pm_remember で記憶を保存する（関連タスクIDがあれば task_id で紐付け）

### コンテキスト保全（Compaction / Clear 対策）
Claude Code はセッションが長くなるとコンテキストを自動圧縮（compaction）する。
圧縮のタイミングは予測できないため、重要な情報は随時保存すること。
1. 重要な発見・技術的判断は発生時点で即座に pm_remember で保存する（セッション終了を待たない）
2. 複雑な議論や設計検討の後は、結論を pm_remember でまとめて保存する
3. 3往復以上のやり取りで未記録の知見があれば、チェックポイントとして pm_remember で保存する
4. ユーザーが /clear する前は必ず pm_session_summary を実行する
5. Compaction 後にコンテキストが失われていると感じたら pm_recall で復元する

### タスク完了時（コードが動作確認できたら）
1. pm_update_task で done に変更する
2. all_issues_resolved フラグが返された場合、親タスクの完了もユーザーに提案する
3. pm_log に完了内容を記録する
4. 次の推薦タスクを pm_next で表示する
5. アトミックコミットを作成する

### タスク完了確認中にイシュー（課題）が見つかった時
1. pm_add_issue で親タスクに紐づくイシュー（子タスク）を作成する
   - phase は親タスクから自動継承される
   - 親タスクが done だった場合、自動で review に戻される
2. イシューを解消したら pm_update_task で done に変更する
3. 全イシューが解消されると all_issues_resolved フラグが返される
4. 親タスクの完了をユーザーに提案する

### 設計上の意思決定が発生した時
1. ユーザーに「ADRとして記録しますか？」と確認する
2. 承認されたら pm_add_decision で保存する

### コーディングセッション終了時
1. 進行中のタスクの状態を確認し、必要に応じて更新する
2. pm_log にセッションの成果を記録する
3. pm_session_summary で要約を保存する
4. 未コミットの変更があればコミットする

---

Tips: Getting the Most out of pm-server

Recommended Workflow

1. Install & register      →  pip install pm-server && pm-server install
2. Start Claude Code       →  (restart after install)
3. Initialize project      →  "PM初期化して" or "Initialize PM"
4. Add tasks               →  "Add task: implement user auth"
5. Work on tasks            →  "Start MYAPP-001"
6. Complete tasks           →  "MYAPP-001 done"
7. Issues found in review   →  "MYAPP-001 has an issue: ..." (creates child issue)
8. End session              →  "Session wrap-up" (triggers summary + log)

Protecting Context from Compaction

Claude Code automatically compresses (compacts) conversation context when sessions get long. This means detailed information from earlier exchanges can be lost. pm-server's memory tools protect against this:

Situation	What to do
Made an important discovery	pm_remember immediately — don't wait for session end
Finished a design discussion	Summarize the conclusion with pm_remember
About to run /clear	Run pm_session_summary first
Resuming after compaction	pm_recall restores previous context
Starting a new session	pm_recall + pm_status (auto if CLAUDE.md rules are set)

Key principle: Save early, save often. Compaction timing is unpredictable — if a finding is worth keeping, record it now.

Session Continuity

pm-server's memory layer ensures nothing is lost between sessions:

Session 1                          Session 2
  │                                  │
  ├─ pm_remember (findings)          ├─ pm_recall ← restores context
  ├─ pm_remember (decisions)         ├─ pm_status ← current state
  ├─ pm_session_summary              │
  └─ (session ends)                  └─ (continues seamlessly)

Automatic Hooks (Lifecycle Enforcement)

pm-server automatically installs Claude Code hooks at first session start (pm_status). After a git commit, a PostToolUse hook injects a reminder into the conversation, prompting Claude to call pm_log, pm_update_task, and pm_next.

• Hooks are installed globally in ~/.claude/settings.json
• Existing user hooks are preserved (pm-server hooks are appended, not replaced)
• No manual setup needed — hooks are auto-installed on upgrade
• To manage manually: pm-server install-hooks / pm-server uninstall-hooks

Multi-Project Management

> "Discover projects under ~/projects"    # Auto-scan & register
> "Show all projects"                     # Portfolio overview
> "Search memories for 'auth' globally"   # Cross-project search
> "Show dashboard for all projects"       # Portfolio HTML dashboard

---

CLI Commands

pm-server install          # Register MCP server in Claude Code
pm-server uninstall        # Unregister MCP server
pm-server serve            # Start MCP server (called by Claude Code automatically)
pm-server discover .       # Scan for projects with .pm/ directories
pm-server status           # Show project status from terminal
pm-server context-inject   # Print session context to stdout (for hook integration)
pm-server migrate          # Migrate from pm-agent (rename transition)
pm-server update-claudemd  # Update PM Server rules in CLAUDE.md
pm-server install-hooks    # Manually install Claude Code hooks (auto-installed via pm_status)
pm-server uninstall-hooks  # Remove PM Server hooks from Claude Code settings

---

Architecture

Claude Code Session
  │
  ├── CLAUDE.md auto-action rules
  ├── PostToolUse hooks (auto-installed)
  ├── Skills (super-research, etc.)
  │
  └── MCP Server (stdio)
        └── pm-server serve
              │
              ├── server.py    → 30 MCP tools (FastMCP)
              ├── models.py    → Pydantic v2 data models (17 models, 15 enums)
              ├── storage.py   → YAML read/write
              ├── workflow.py  → Workflow engine (state machine)
              ├── memory.py    → SQLite memory store + FTS5 search
              ├── recall.py    → Session context builder (token-budgeted)
              ├── hooks.py     → Claude Code hook handler + installer
              ├── context.py   → CLI context injection
              ├── velocity.py  → Velocity calculation & risk detection
              ├── dashboard.py → HTML/text dashboard (Jinja2) + workflow progress + knowledge map
              ├── discovery.py → Auto-detect project info
              └── installer.py → claude mcp add wrapper
                    │
                    ├── project-A/.pm/ (YAML + workflows + knowledge + memory.db)
                    ├── project-B/.pm/ (YAML + workflows + knowledge + memory.db)
                    └── ~/.pm/registry.yaml + memory.db

---

Migrating from pm-agent

If you were using the earlier pm-agent package:

pip uninstall pm-agent
pip install pm-server
pm-server migrate       # Switches MCP registration from pm-agent to pm-server
# Restart Claude Code

The migrate command will:

• Remove the old pm-agent MCP registration
• Register pm-server as the new MCP server
• Verify ~/.pm/registry.yaml integrity
• Warn about any CLAUDE.md files that reference pm-agent

Your .pm/ data directories are unchanged — no data migration needed.

---

Requirements

• Python 3.11+
• Claude Code (with MCP support)

Dependencies

• FastMCP — MCP server framework
• Pydantic v2 — data validation
• PyYAML — data persistence
• Click — CLI framework
• Jinja2 — dashboard templates

---

Development

git clone https://github.com/flc-design/pm-server.git
cd pm-server
pip install -e ".[dev]"
pytest                  # 400+ tests
ruff check src/         # Lint
ruff format src/        # Format

---

Design Principles

1. Zero Configuration — pip install + one command, done
2. Auto-everything — detection, registration, and inference are fully automatic
3. Git-friendly — plain text YAML, trackable with git diff
4. Human-readable — safe to hand-edit, won't break
5. AI-native — formats that Claude Code can naturally read and write
6. Non-invasive — only adds .pm/, never modifies your project

---

License

MIT — Shinichi Nakazato / FLC design co., ltd.