pm-server

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

22 MCP tools — task CRUD, status, blockers, velocity, dashboard, ADR, session memory, and more
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.

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
`ブロッカーある？`	List blocked tasks
`ダッシュボード見せて`	Generate HTML dashboard (Chart.js, dark theme)
`この設計にした理由を記録`	Record an Architecture Decision Record (ADR)
`全プロジェクトの状態`	Cross-project portfolio view

MCP Tools (22 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
`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

Records

Tool	Description
`pm_log`	Daily log entry (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 (single project or portfolio view)

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 tied to the current session (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)

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)
    ├── milestones.yaml     # Milestone definitions
    ├── risks.yaml          # Risks and blockers
    ├── memory.db           # Session memories (SQLite + FTS5)
    └── 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. ブロッカーや期限超過があれば警告する

### タスクに着手する前
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. pm_log に完了内容を記録する
3. 次の推薦タスクを pm_next で表示する
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. 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)

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

Architecture

Claude Code Session
  │
  ├── CLAUDE.md auto-action rules
  │
  └── MCP Server (stdio)
        └── pm-server serve
              │
              ├── server.py    → 22 MCP tools (FastMCP)
              ├── models.py    → Pydantic v2 data models
              ├── storage.py   → YAML read/write
              ├── memory.py    → SQLite memory store + FTS5 search
              ├── recall.py    → Session context builder (token-budgeted)
              ├── context.py   → CLI context injection
              ├── velocity.py  → Velocity calculation & risk detection
              ├── dashboard.py → HTML/text dashboard (Jinja2)
              ├── discovery.py → Auto-detect project info
              └── installer.py → claude mcp add wrapper
                    │
                    ├── project-A/.pm/ (YAML + memory.db)
                    ├── project-B/.pm/ (YAML + 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                  # 237 tests
ruff check src/         # Lint
ruff format src/        # Format

Design Principles

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

License

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

Name		Name	Last commit message	Last commit date
Latest commit History 25 Commits
docs		docs
skill		skill
src/pm_server		src/pm_server
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.ja.md		README.ja.md
README.md		README.md
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

pm-server

Features

Quick Start

Install (once)

Update

Initialize a project

Use it

MCP Tools (22 tools)

Project Management

Records

Analysis

Visualization

Discovery

Memory (Session Continuity)

Maintenance

Data Structure

CLAUDE.md Integration

Tips: Getting the Most out of pm-server

Recommended Workflow

Protecting Context from Compaction

Session Continuity

Multi-Project Management

CLI Commands

Architecture

Migrating from pm-agent

Requirements

Dependencies

Development

Design Principles

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages