DevPulse PM Agent — MCP Server

An MCP server that gives Asha four tools for grounded PM decision-making, backed by the real DevPulse datasets.

Quick Start

cd devpulse-pm-agent
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python server.py

Related MCP server: PM-Skills MCP

Connect to Claude Code

claude mcp add pm-agent python /absolute/path/to/server.py

Data Path Contract

The server reads from PM_AGENT_DATA env var, falling back to ./data:

DATA_DIR = Path(os.environ.get("PM_AGENT_DATA", Path(__file__).parent / "data"))

Tools

Approach Summary (Technical Decision Log)

1. Schema Rationale

prioritize_backlog takes a method enum to let Asha switch scoring approaches without rewording her question — RICE for data-driven prioritization, FIFO when chronological ordering matters, weighted for a simpler BV/confidence ratio. Flags are discrete booleans on each item rather than a separate list, so Claude can directly say "BP-126 is flagged unestimated and no_customer_signal." The deprioritize_blocked toggle separates "surfacing blocked items" from "penalizing them" — Asha might want to see blocked items at the top precisely so she can unblock them.

I considered a top_n parameter but rejected it — Claude can filter; a parameter cap just hides information.

analyze_feedback returns structured theme objects (not raw text) so Claude synthesizes, not recites. The group_by="customer" switch addresses the common query "what does CUST-01 keep asking for?" — a different grouping axis than theme. Bias warnings are always-on and surfaced as a first-class field, not buried in metadata.

I considered keyword embedding (sentence-transformers) for theme detection but rejected it — it adds a large dependency, fails in sandboxed grading environments, and the fixed keyword approach is fully auditable and sufficient for 9 known themes.

assess_capacity exposes every intermediate calculation (effective, after_pto, available) so Claude can explain the number, not just report it. planned_items is an optional list so Asha can ask "given these items, do we have the right skills?" in one call.

map_dependencies returns both direct and transitive deps in a tree structure per item, plus a separate critical_path field. The tree structure lets Claude reason about depth; the critical path field lets it directly answer "what's the riskiest chain?"

2. Investigation & Trap Handling

Capacity oracle investigation strategy:

The oracle exposes capacity_oracle(engineer_id) returning inputs + available_points. I designed a systematic probe:

• Baseline: queried an engineer with 100% allocation, 0 PTO, 0 carry-over → expected 21 points → confirmed total_capacity_points = 21.

• Isolation — allocation: queried 50% allocation, 0 PTO, 0 carry-over → expected 10.5 → confirmed effective = 21 * (allocation/100).

• Isolation — PTO: 100% allocation, 2 PTO days, 0 carry-over → expected 21 * (1 - 2/10) = 16.8 → confirmed PTO is pro-rated over the 10-day sprint, not a flat deduction.

• Isolation — carry-over: 100% allocation, 0 PTO, 5 carry-over → expected 21 - 5 = 16 → confirmed carry-over is subtracted after PTO.

• Zero allocation edge: queried 0% engineer → expected 0, confirmed contributes nothing to squad totals. This is important: a shared engineer doesn't "gift" capacity they can't actually give.

• Floor check: carry-over larger than capacity → expected 0 (not negative) → confirmed max(0, ...) floor.

The formula is:

effective = 21 * (allocation / 100)
after_pto = effective * (1 - pto_days / 10)
available = max(0, after_pto - carry_over_points)

Dependency oracle investigation:

• Queried known item IDs from the backlog and followed returned target_ids to trace the graph.

• Found that type distinguishes hard blockers (blocks) from optional ordering (soft) from cross-team dependencies (external).

• External deps with external_eta = "TBD" or null are a key risk signal — no committed delivery date means unknown blocking time.

• Soft dependencies get the same graph traversal as hard ones (critical path logic is the same) but are excluded from "blocks" warnings.

Data anomalies found in the given files:

• BP-126: effort_points = 0 — unestimated item, cannot compute reliable RICE score. Flagged as unestimated.

• BP-131 Executive dashboard: business_value_score = 2 but priority = P1 and has executive-priority tag — classic stakeholder override. Tool flags it and applies a 20% boost rather than ignoring it, since ignoring it would cause Claude to give Asha advice that conflicts with executive expectations she has to manage.

• BP-112 GraphQL migration depends on BP-118, which itself depends on BP-125, which depends on BP-112 — a potential cycle. The map_dependencies tool detects and reports this cycle.

• NovaBuild (CUST-07) has 10 feedback entries — 11% of the corpus — but is churned. Volume bias detection fires, and churned signal is flagged separately.

• Two BP-127 / BP-119 items both titled "Notification digest system" from different requesters with different effort estimates — a near-duplicate backlog item anomaly. The prioritize tool doesn't deduplicate these (that would require PM judgment) but the analyze_feedback near-duplicate check helps surface it.

3. Tool Description Craft

Tool descriptions are written to answer two questions Claude is implicitly asking: "Should I call this?" and "What should I pass?". Each description leads with example Asha questions ("What are customers actually asking for?") because Claude pattern-matches user intent to descriptions.

Example where the description shaped behavior: map_dependencies says "at least one ID is required" and lists the format BP-NNN. Without this, Claude would call the tool with fuzzy item names like "API redesign" instead of BP-112, causing a miss. Adding "Use backlog IDs (BP-NNN) as they appear in the dependency map" caused Claude to first call prioritize_backlog to find the ID, then map_dependencies with the correct format.

The assess_capacity description includes the formula verbatim — not to teach Claude math, but so Claude can explain the number to Asha without hallucinating an alternate explanation.

4. Failure Modes

• Bad input IDs in map_dependencies: If an item_id has no edges in the graph, the tool returns direct_deps: [] and chain_depth: 0 — informative, not a crash.

• Empty item_ids: Returns {"error": "item_ids must contain at least one item ID."} with a clear message.

• Cycle in dependency graph: Detected via DFS with path tracking. Returns the full cycle path (BP-112 -> BP-118 -> BP-125 -> BP-112) so Asha can see exactly what's circular. The tool does not crash — it flags and continues tracing the rest of the graph.

• Broken chain (target references unknown item): _trace_chain simply returns no transitive deps for an unknown target — doesn't crash, doesn't recurse into nothing. The _detect_cycle function uses a visited set to prevent infinite loops.

• Missing data files: load_json raises FileNotFoundError with a clear message about PM_AGENT_DATA. The roster and dependency map loaders try the canonical filename first, then fall back to the sample file — allows local dev without the grading harness.

• Unestimated items in RICE: Effort = 0 causes division by zero. The code uses max(effort, 1) and also flags the item as unestimated so Asha knows the score is unreliable.

5. Custom Insight: Designing Tools for AI vs. Human UI

The key insight: AI tools need to surface judgment inputs, not conclusions. A human dashboard shows a score; an AI tool should expose the components of that score (reach, impact, confidence, effort) so the AI can reason about tradeoffs, not just read a number.

The second insight: tool descriptions are API contracts with the AI. Every example question in the description is a routing hint. When Claude sees "What's blocking the API redesign?" it needs to know that's a map_dependencies call, not a prioritize_backlog call. The description does that work.

The third: flags matter more than scores. A dependency_conflict flag changes Asha's action (unblock first) even if the item scored first. Scores rank; flags route.

6. Production Scaling

Data layer: Replace file-based JSON with a read API that accepts a team_id. Each tool call would pass team_id as context so the same server can serve 6 product teams. Add a caching layer (Redis, 5-min TTL) — feedback and backlog data doesn't change mid-conversation.

Schema changes: Add team_id to all tool inputs. Add as_of_date parameter to assess_capacity so Asha can query future sprints. Add a confidence_interval output to assess_capacity based on historical velocity variance from sprint_history.

Error handling: Switch from raise FileNotFoundError to structured error responses ({"error": "...", "error_code": "data_unavailable"}) so the AI can explain the failure gracefully rather than receiving a crash.

New tools I'd add:

• sprint_fit_check(item_ids) — combines capacity + dependencies to answer "can we fit these specific items?" in one call

• churn_risk_signal(customer_id) — cross-reference feedback sentiment trend with ARR to give Asha early churn warnings

• velocity_forecast(sprint_count) — projects future capacity from historical sprint data

What I'd explicitly NOT automate: Sprint commitment decisions (which items go in), capacity reallocation between engineers, and executive priority overrides. These require human negotiation, context beyond the data, and accountability. The tools should inform these decisions, not make them. An AI that auto-commits the sprint or auto-reassigns engineers creates false precision and removes the PM's ability to surface organizational context the data doesn't capture.