@roadmapperai/mcp 0.1.0

package/README.md

@@ -0,0 +1,111 @@
+# @roadmapperai/mcp
+
+The MCP (Model Context Protocol) server for [Roadmapper AI](https://roadmapperai.com).
+
+Lets your coding agent (Claude Code, Claude Desktop, Cursor, etc.) read your
+roadmap and — once write auth is enabled — propose themes, capabilities, and
+tasks against your live rubric.
+
+## Install
+
+You need a Roadmapper AI workspace. Sign up free at
+[dashboard.roadmapperai.com](https://dashboard.roadmapperai.com).
+
+Then add the server to your MCP client. The dashboard's Settings →
+**Connect to your agent** page generates a copy-pasteable config block with
+your workspace ID pre-filled — that's the fastest path.
+
+### Manual config
+
+If you'd rather wire it up by hand:
+
+#### Claude Code / Claude Desktop
+
+Add to your `~/.config/claude-code/config.json` (or the equivalent
+`claude_desktop_config.json` for the desktop app):
+
+```json
+{
+  "mcpServers": {
+    "roadmapper": {
+      "command": "npx",
+      "args": ["-y", "@roadmapperai/mcp"],
+      "env": {
+        "SUPABASE_URL": "https://tqfhcpoblluegsbkcaqq.supabase.co",
+        "SUPABASE_PUBLISHABLE_KEY": "sb_publishable_oT9...",
+        "SUPABASE_WORKSPACE_ID": "<your workspace id>"
+      }
+    }
+  }
+}
+```
+
+Get your workspace ID from the dashboard's URL bar
+(`dashboard.roadmapperai.com/settings` → workspace section) or from the
+generated config block in Settings → Connect.
+
+#### Cursor
+
+Cursor's MCP settings live under **Settings → Features → MCP**. The same
+JSON config works, dropped into Cursor's `mcp` field.
+
+## What this server exposes
+
+Read tools (always available):
+
+- `list_themes` — top-level strategic themes
+- `list_capabilities` — capabilities (optionally filtered by theme)
+- `list_tasks` — tasks (optionally filtered by capability or status)
+- `get_task` — full task detail including acceptance criteria + deps
+- `get_agents_md` — the planning rubric (the contract for proposals)
+- `get_roadmap_snapshot` — current state of the whole roadmap
+- `suggest_capability_for` — find existing capability that matches a description
+- `suggest_theme_for` — find existing theme that matches a description
+- `list_stale_outcomes` — capabilities whose outcome metric hasn't been
+  re-read recently
+
+Write tools (require workspace-scoped write auth — coming in v0.2):
+
+- `propose_theme`, `propose_capability`, `propose_task` — file new work
+- `update_theme`, `update_capability`, `update_task` — patch existing rows
+- `archive_*` / `unarchive_*` — soft delete
+- `move_task`, `move_capability` — reparent
+- `link_pr` — attach a merged PR to a task
+- `record_outcome_reading` — log an outcome metric measurement
+- `submit_acceptance_grades` — self-grade after delivery
+
+## How agents are meant to use this
+
+The intended loop:
+
+1. Agent calls `get_agents_md` to load the rubric.
+2. Agent reads the current roadmap state via `list_themes` /
+   `list_capabilities` / `list_tasks`.
+3. Before proposing anything new, agent calls `suggest_capability_for`
+   (or `suggest_theme_for`) to check if a matching parent already exists.
+4. Agent proposes new rows through the `propose_*` tools, including all
+   the rubric-required fields (RICE, acceptance criteria, etc.).
+5. Once a PR is merged, the agent calls `link_pr` to attach it; the
+   roadmap delivery stats update automatically.
+6. After delivery, the agent self-grades against the acceptance criteria
+   with `submit_acceptance_grades`.
+
+The server enforces the rubric: proposals filed without first fetching
+`get_agents_md` are rejected with a remediation hint pointing the agent
+back to the rubric.
+
+## Versioning
+
+This package follows semver. Breaking changes to tool shapes get a
+major-version bump and a deprecation window. Add `--package=@roadmapperai/mcp@0.x.y`
+to your `npx` invocation if you want to pin.
+
+## Support
+
+- Bugs / feature requests: contact@roadmapperai.com
+- Dashboard: https://dashboard.roadmapperai.com
+- Docs: https://roadmapperai.com
+
+## License
+
+MIT.

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@roadmapperai/mcp",
+  "version": "0.1.0",
+  "description": "Roadmapper AI MCP server — exposes a planning surface (themes, capabilities, tasks, sprints, PRs) to coding agents via stdio JSON-RPC. Pairs with the Roadmapper AI workspace at dashboard.roadmapperai.com.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "roadmap",
+    "planning",
+    "agents",
+    "claude",
+    "cursor",
+    "ai"
+  ],
+  "homepage": "https://roadmapperai.com",
+  "bugs": "mailto:contact@roadmapperai.com",
+  "license": "MIT",
+  "author": "Roadmapper AI",
+  "type": "module",
+  "main": "server.mjs",
+  "bin": {
+    "roadmapper-mcp": "server.mjs"
+  },
+  "files": [
+    "server.mjs",
+    "AGENTS.md",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "scripts": {
+    "prepack": "cp ../AGENTS.md ./AGENTS.md"
+  }
+}