@project-tracker/mcp 1.0.0

package/README.md

@@ -0,0 +1,63 @@
+# @project-tracker/mcp
+
+MCP server for [Project Tracker](https://app.project-tracker.ai). Lets [Claude Code](https://claude.com/claude-code) and other MCP-aware AI clients read and update your tracker via tool calls — `list_projects`, `create_item`, `move_item`, `update_item`, etc.
+
+If your AI client doesn't support MCP, use the [curl-prompt path](https://app.project-tracker.ai/docs/curl-prompt.md) instead — same data, different shape.
+
+## Install
+
+Add to your Claude Code MCP config (`~/.claude/mcp.json` or the equivalent UI):
+
+```json
+{
+  "mcpServers": {
+    "project-tracker": {
+      "command": "npx",
+      "args": ["-y", "@project-tracker/mcp"],
+      "env": {
+        "API_BASE": "https://app.project-tracker.ai",
+        "API_KEY": "pt_your_token_here"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Code. The `project-tracker` server will appear in your MCP panel with its tool catalogue.
+
+### Where the API key comes from
+
+Log in to https://app.project-tracker.ai → **Integrations** (top right) → **Generate key** → name it (e.g. `Claude Code on my laptop`) → copy the `pt_...` token. Keys are shown once; store it in a password manager.
+
+The key inherits your user's permissions — owner / team-member / collaborator access to each project. If a tool call returns `Permission denied: requires X on project Y`, it's not a bug, it's your project role.
+
+## Configuration
+
+| Env var | Required | Default | Meaning |
+|---|---|---|---|
+| `API_KEY` | yes (in practice) | — | Your `pt_...` API key. Calls go through unauthenticated if unset, which means most operations 401. |
+| `API_BASE` | no | `http://127.0.0.1:3001` | Origin of the Project Tracker API. Use `https://app.project-tracker.ai` for the hosted service, or your own host for a self-hosted PT. Note: this is the origin only — the server appends `/api/...` internally. |
+
+## Tools
+
+- **Projects**: `list_projects`, `create_project`, `update_project`
+- **Items**: `list_items`, `get_item`, `get_item_context`, `create_item`, `update_item`, `delete_item`, `restore_item`, `move_item`, `bulk_update_items`
+- **Views**: `get_board`, `get_matrix`
+
+Full schema for each tool surfaces in your MCP client. Argument shapes mirror the underlying REST API — full reference at https://app.project-tracker.ai/api/docs.
+
+## AI behaviour prompt
+
+Drop the contents of https://app.project-tracker.ai/docs/mcp-prompt.md into your project's `CLAUDE.md` (or equivalent system prompt) so the AI knows how to use the tools — work-claiming conventions, multi-AI safety, etc. The MCP server checks the prompt version on session start and flags via `_meta.promptUpdateAvailable` if your bundled copy is stale.
+
+## Requirements
+
+Node.js ≥ 18. The package ships pre-built JavaScript; `npx -y @project-tracker/mcp` installs and runs without a separate build step.
+
+## Source
+
+This package lives in the [`mcp-server/`](https://github.com/DQ-ProjectTracker/project-tracker/tree/main/mcp-server) subdirectory of the Project Tracker repo. Issues + PRs welcome at https://github.com/DQ-ProjectTracker/project-tracker.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,284 @@
+#!/usr/bin/env node
+// PT-89: shebang is preserved by tsc into dist/index.js so the `bin` entry
+// in package.json runs the file directly under node when invoked via npx.
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+const API_BASE = process.env.API_BASE || "http://127.0.0.1:3001";
+const API_KEY = process.env.API_KEY;
+// Bundled prompt version. Bump this together with the front-matter version
+// in project-planning-prompt-mcp.md whenever AI behaviour changes.
+const BUNDLED_PROMPT_VERSION = "1.4.0";
+let promptUpdate = null;
+let versionCheckPromise = null;
+function compareVersions(a, b) {
+    const pa = a.split(".").map((n) => parseInt(n, 10) || 0);
+    const pb = b.split(".").map((n) => parseInt(n, 10) || 0);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const d = (pa[i] || 0) - (pb[i] || 0);
+        if (d !== 0)
+            return d;
+    }
+    return 0;
+}
+async function checkPromptVersion() {
+    try {
+        const res = await fetch(`${API_BASE}/api/prompts/version`);
+        if (!res.ok)
+            return;
+        const data = (await res.json());
+        if (compareVersions(data.mcp, BUNDLED_PROMPT_VERSION) > 0) {
+            promptUpdate = {
+                current: BUNDLED_PROMPT_VERSION,
+                latest: data.mcp,
+                changelogUrl: data.changelog,
+            };
+            console.error(`⚠ Project Tracker prompt v${data.mcp} available (you have v${BUNDLED_PROMPT_VERSION}). Changelog: ${data.changelog}`);
+        }
+    }
+    catch {
+        // Network failure during version check is non-fatal — tool calls still work.
+    }
+}
+function ensureVersionChecked() {
+    if (!versionCheckPromise)
+        versionCheckPromise = checkPromptVersion();
+    return versionCheckPromise;
+}
+// Coercion helpers — MCP clients may pass numbers/arrays as strings
+const coerceNumber = z.coerce.number();
+const coerceLabels = z.preprocess((v) => (typeof v === "string" ? JSON.parse(v) : v), z.array(z.string()));
+async function apiRequest(path, options) {
+    // Trigger version check on first API call (fire-and-forget after first call).
+    ensureVersionChecked();
+    const headers = {
+        "Content-Type": "application/json",
+        ...options?.headers,
+    };
+    if (API_KEY)
+        headers["Authorization"] = `Bearer ${API_KEY}`;
+    const res = await fetch(`${API_BASE}${path}`, {
+        ...options,
+        headers,
+    });
+    if (!res.ok) {
+        const body = await res.json().catch(() => ({}));
+        throw new Error(body.error || `API error: ${res.status}`);
+    }
+    return res.json();
+}
+function textResult(data) {
+    const result = {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+    };
+    if (promptUpdate) {
+        result._meta = { promptUpdateAvailable: promptUpdate };
+    }
+    return result;
+}
+const server = new McpServer({
+    name: "project-tracker",
+    version: "1.0.0",
+});
+// --- Projects ---
+server.tool("list_projects", "List all projects", {}, async () => {
+    const projects = await apiRequest("/api/projects");
+    return textResult(projects);
+});
+server.tool("create_project", "Create a new project", {
+    key: z.string().describe("Short slug, e.g. WEB, API"),
+    name: z.string().describe("Display name"),
+    color: z.string().optional().describe("Hex color, e.g. #3B82F6"),
+    repoPath: z.string().optional().describe("Default working directory for this project"),
+    claudeMdPath: z.string().optional().describe("Path to the project's claude.md"),
+    branch: z.string().optional().describe("Default branch name"),
+    notes: z.string().optional().describe("Context notes for Claude"),
+}, async (params) => {
+    const project = await apiRequest("/api/projects", {
+        method: "POST",
+        body: JSON.stringify(params),
+    });
+    return textResult(project);
+});
+server.tool("update_project", "Update an existing project's fields", {
+    key: z.string().describe("Project key"),
+    name: z.string().optional(),
+    color: z.string().optional(),
+    status: z.enum(["active", "archived"]).optional().describe("Set to 'archived' to hide project from default views"),
+    repoPath: z.string().optional(),
+    claudeMdPath: z.string().optional(),
+    branch: z.string().optional(),
+    notes: z.string().optional(),
+}, async (params) => {
+    const { key, ...updates } = params;
+    const project = await apiRequest(`/api/projects/${key}`, {
+        method: "PATCH",
+        body: JSON.stringify(updates),
+    });
+    return textResult(project);
+});
+// --- Items ---
+server.tool("list_items", "List project items with optional filters. Set deleted=true to list soft-deleted (trashed) items instead.", {
+    status: z.enum(["backlog", "todo", "blocked", "in_progress", "review", "done"]).optional(),
+    type: z.enum(["story", "task"]).optional(),
+    label: z.string().optional(),
+    search: z.string().optional(),
+    project: z.string().optional().describe("Filter by project key"),
+    deleted: z.boolean().optional().describe("If true, returns soft-deleted items only (the trash list)."),
+}, async (params) => {
+    const qs = new URLSearchParams();
+    if (params.status)
+        qs.set("status", params.status);
+    if (params.type)
+        qs.set("type", params.type);
+    if (params.label)
+        qs.set("label", params.label);
+    if (params.search)
+        qs.set("search", params.search);
+    if (params.project)
+        qs.set("project", params.project);
+    if (params.deleted)
+        qs.set("deleted", "true");
+    const qstr = qs.toString();
+    const items = await apiRequest(`/api/items${qstr ? "?" + qstr : ""}`);
+    return textResult(items);
+});
+server.tool("get_item", "Get a single item by its key (e.g. PT-1)", {
+    key: z.string().describe("Item key like PT-1"),
+}, async (params) => {
+    const item = await apiRequest(`/api/items/${params.key}`);
+    return textResult(item);
+});
+server.tool("get_item_context", "Get resolved context for an item (merged project defaults + item overrides). Call this before starting work on any item to know the repo path, claude.md location, branch, and notes.", {
+    key: z.string().describe("Item key like PT-1"),
+}, async (params) => {
+    const context = await apiRequest(`/api/items/${params.key}/context`);
+    return textResult(context);
+});
+server.tool("create_item", "Create a new story or task", {
+    type: z.enum(["story", "task"]),
+    title: z.string(),
+    description: z.string().optional(),
+    status: z.enum(["backlog", "todo", "blocked", "in_progress", "review", "done"]).optional(),
+    priority: z.enum(["low", "medium", "high", "critical"]).optional(),
+    labels: coerceLabels.optional(),
+    assignee: z.string().optional(),
+    parentKey: z.string().optional(),
+    project: z.string().optional().describe("Project key (defaults to PT)"),
+    value: coerceNumber.min(1).max(5).optional().describe("Business value 1-5 (XS-XL)"),
+    effort: coerceNumber.min(1).max(5).optional().describe("Effort estimate 1-5 (XS-XL)"),
+    desirability: coerceNumber.min(1).max(5).optional().describe("Need/desirability 1-5 (XS-XL)"),
+    dueDate: z.string().optional().describe("Due date in ISO format (YYYY-MM-DD)"),
+    blockedBy: coerceLabels.optional().describe("Array of item keys that block this item"),
+    blockedReason: z.string().optional().describe("Free-text reason for the block — useful when blocked by external things not in the tracker"),
+    milestone: z.string().optional().describe("Milestone or sprint name (e.g. v2, Sprint 3)"),
+    repoPath: z.string().optional().describe("Override project repo path"),
+    claudeMdPath: z.string().optional().describe("Override project claude.md path"),
+    branch: z.string().optional().describe("Override project branch"),
+    notes: z.string().optional().describe("Working notes for this item"),
+}, async (params) => {
+    const item = await apiRequest("/api/items", {
+        method: "POST",
+        body: JSON.stringify(params),
+    });
+    return textResult(item);
+});
+server.tool("update_item", "Update an existing item's fields", {
+    key: z.string().describe("Item key like PT-1"),
+    title: z.string().optional(),
+    description: z.string().optional(),
+    status: z.enum(["backlog", "todo", "blocked", "in_progress", "review", "done"]).optional(),
+    priority: z.enum(["low", "medium", "high", "critical"]).optional(),
+    type: z.enum(["story", "task"]).optional(),
+    labels: coerceLabels.optional(),
+    assignee: z.string().optional(),
+    parentKey: z.string().optional(),
+    value: coerceNumber.min(1).max(5).optional(),
+    effort: coerceNumber.min(1).max(5).optional(),
+    desirability: coerceNumber.min(1).max(5).optional(),
+    dueDate: z.string().optional().describe("Due date in ISO format (YYYY-MM-DD)"),
+    blockedBy: coerceLabels.optional().describe("Array of item keys that block this item"),
+    blockedReason: z.string().optional().describe("Free-text reason for the block — useful when blocked by external things not in the tracker"),
+    milestone: z.string().optional().describe("Milestone or sprint name"),
+    changeLog: z.string().optional().describe("What changed — appended to the item's change log"),
+    repoPath: z.string().optional(),
+    claudeMdPath: z.string().optional(),
+    branch: z.string().optional(),
+    notes: z.string().optional(),
+    expectedVersion: coerceNumber.optional().describe("Optional optimistic concurrency token. Pass the item's __v from your last get_item; on mismatch the server returns 409 and the call fails with the latest version. Omit for last-write-wins."),
+}, async (params) => {
+    const { key, ...updates } = params;
+    const item = await apiRequest(`/api/items/${key}`, {
+        method: "PATCH",
+        body: JSON.stringify(updates),
+    });
+    return textResult(item);
+});
+server.tool("delete_item", "Soft-delete an item by key. The item is marked deletedAt and disappears from board/list/matrix/timeline, but the row stays in the DB and any active personal schedule claims are released. Restore via restore_item. Idempotent.", {
+    key: z.string().describe("Item key like PT-1"),
+}, async (params) => {
+    const result = await apiRequest(`/api/items/${params.key}`, { method: "DELETE" });
+    return textResult(result);
+});
+server.tool("restore_item", "Restore a soft-deleted item by key — clears deletedAt and brings it back into normal views. Does not re-add to anyone's schedule (the user re-plans manually).", {
+    key: z.string().describe("Item key like PT-1"),
+}, async (params) => {
+    const result = await apiRequest(`/api/items/${params.key}/restore`, { method: "POST" });
+    return textResult(result);
+});
+server.tool("move_item", "Move an item to a different status column and/or reorder it. When moving to in_progress, pass claimedBy with your worker identifier (e.g. 'claude-opus-codex') so the server can detect conflicts. If another worker already holds it you'll get a 409 — pass force=true to take over deliberately.", {
+    key: z.string().describe("Item key like PT-1"),
+    status: z.enum(["backlog", "todo", "blocked", "in_progress", "review", "done"]),
+    order: coerceNumber.optional(),
+    claimedBy: z.string().optional().describe("Your worker identifier; recorded as assignee when claiming in_progress."),
+    force: z.boolean().optional().describe("Override an existing in_progress claim by another worker."),
+}, async (params) => {
+    const item = await apiRequest(`/api/items/${params.key}/move`, {
+        method: "PATCH",
+        body: JSON.stringify({
+            status: params.status,
+            order: params.order ?? 0,
+            claimedBy: params.claimedBy,
+            force: params.force,
+        }),
+    });
+    return textResult(item);
+});
+server.tool("get_board", "Get the full Kanban board with items grouped by status", {
+    project: z.string().optional().describe("Filter by project key"),
+}, async (params) => {
+    const qs = params.project ? `?project=${params.project}` : "";
+    const board = await apiRequest(`/api/items/board${qs}`);
+    return textResult(board);
+});
+server.tool("get_matrix", "Get the value/effort matrix (plan view) with items grouped into a 5x5 grid", {
+    project: z.string().optional().describe("Filter by project key"),
+}, async (params) => {
+    const qs = params.project ? `?project=${params.project}` : "";
+    const matrix = await apiRequest(`/api/items/board/matrix${qs}`);
+    return textResult(matrix);
+});
+server.tool("bulk_update_items", "Update multiple items at once. Pass an array of updates, each with a key and fields to update.", {
+    updates: z.preprocess((v) => (typeof v === "string" ? JSON.parse(v) : v), z.array(z.object({
+        key: z.string(),
+        status: z.enum(["backlog", "todo", "blocked", "in_progress", "review", "done"]).optional(),
+        priority: z.enum(["low", "medium", "high", "critical"]).optional(),
+        labels: z.array(z.string()).optional(),
+        value: z.number().min(1).max(5).optional(),
+        effort: z.number().min(1).max(5).optional(),
+        desirability: z.number().min(1).max(5).optional(),
+        changeLog: z.string().optional(),
+    }))).describe("Array of { key, ...fields } objects"),
+}, async (params) => {
+    const result = await apiRequest("/api/items/bulk", {
+        method: "PATCH",
+        body: JSON.stringify({ updates: params.updates }),
+    });
+    return textResult(result);
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Project Tracker MCP server running");
+}
+main().catch(console.error);

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@project-tracker/mcp",
+  "version": "1.0.0",
+  "description": "MCP server for Project Tracker (app.project-tracker.ai) — lets Claude Code and other MCP-aware AI clients read and update your tracker via tool calls.",
+  "type": "module",
+  "bin": {
+    "project-tracker-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "project-tracker",
+    "claude",
+    "kanban",
+    "ai-tools"
+  ],
+  "author": "Jason Gould",
+  "license": "MIT",
+  "homepage": "https://app.project-tracker.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DQ-ProjectTracker/project-tracker.git",
+    "directory": "mcp-server"
+  },
+  "bugs": {
+    "url": "https://github.com/DQ-ProjectTracker/project-tracker/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.9.0",
+    "typescript": "^5.6.0"
+  }
+}