@aioproductoscom/mcp-pm 0.1.0

package/README.md

@@ -0,0 +1,61 @@
+# ProductOS PM Helper · MCP server
+
+Manage **ProductOS** tickets from your AI host — Claude Code, Cursor, Codex, or any
+MCP client. List, create, update, and comment on tasks, grounded in the ProductOS
+spine (features, insights). Thin and secret-free: the only credential is your
+personal access token, which you paste into *your* host's config.
+
+## 1. Get a token
+
+In ProductOS → **Settings → Tokens & Agents** → **Generate token**. Copy it (shown
+once) — it looks like `pat_live_…`.
+
+## 2. Connect
+
+### Claude Code
+```bash
+claude mcp add productos-pm -e PRODUCTOS_TOKEN=pat_live_… -- npx -y @aioproductoscom/mcp-pm
+```
+or in `.mcp.json`:
+```json
+{
+  "mcpServers": {
+    "productos-pm": {
+      "command": "npx",
+      "args": ["-y", "@aioproductoscom/mcp-pm"],
+      "env": { "PRODUCTOS_TOKEN": "pat_live_…" }
+    }
+  }
+}
+```
+
+### Cursor / Codex
+Same shape in their `mcp.json`: `command: "npx"`, `args: ["-y", "@aioproductoscom/mcp-pm"]`,
+`env.PRODUCTOS_TOKEN`.
+
+`PRODUCTOS_URL` defaults to `https://platform.aioproductos.com`; set it to point at a
+self-hosted platform.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `whoami` | the connected org + member |
+| `pm_meta` | lists / statuses / members / features (resolve names → ids) |
+| `list_tasks` | list tasks (filter by `status_id`, `list_id`) |
+| `get_task` | one task + comments + assignees |
+| `create_task` | new task; `feature_id` / `insight_id` link it to the spine |
+| `update_task` | change status, priority, fields, assignees |
+| `comment_on_task` | add a comment |
+
+## Local build (until published to npm)
+
+```bash
+pnpm install
+pnpm --filter @aioproductoscom/mcp-pm build
+```
+Then point the host at the built binary instead of `npx`:
+```json
+{ "command": "node", "args": ["<repo>/packages/mcps/productos-pm/dist/index.js"],
+  "env": { "PRODUCTOS_TOKEN": "pat_live_…" } }
+```

package/dist/client.js

@@ -0,0 +1,60 @@
+// Thin typed HTTP client over the platform's token-authed PM endpoints.
+// Uses global fetch (Node 18+). The PAT is the only credential; nothing is stored.
+export class PlatformClient {
+    baseUrl;
+    token;
+    constructor(baseUrl, token) {
+        this.baseUrl = baseUrl;
+        this.token = token;
+    }
+    async req(path, init) {
+        const res = await fetch(`${this.baseUrl}${path}`, {
+            ...init,
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${this.token}`,
+                ...(init?.headers ?? {}),
+            },
+        });
+        const body = await res.text();
+        const json = body ? JSON.parse(body) : {};
+        if (!res.ok) {
+            const o = (json ?? {});
+            const msg = o.error ? `${o.error}${o.detail ? `: ${o.detail}` : ""}` : `HTTP ${res.status}`;
+            const e = new Error(msg);
+            e.status = res.status;
+            throw e;
+        }
+        return json;
+    }
+    whoami() {
+        return this.req("/api/me");
+    }
+    meta() {
+        return this.req("/api/pm/meta");
+    }
+    listTasks(q) {
+        const params = new URLSearchParams();
+        if (q.status_id)
+            params.set("status_id", q.status_id);
+        if (q.list_id)
+            params.set("list_id", q.list_id);
+        const qs = params.toString();
+        return this.req(`/api/pm/tasks${qs ? `?${qs}` : ""}`);
+    }
+    getTask(id) {
+        return this.req(`/api/pm/tasks/${encodeURIComponent(id)}`);
+    }
+    createTask(body) {
+        return this.req("/api/pm/tasks", { method: "POST", body: JSON.stringify(body) });
+    }
+    updateTask(id, body) {
+        return this.req(`/api/pm/tasks/${encodeURIComponent(id)}`, { method: "PATCH", body: JSON.stringify(body) });
+    }
+    comment(id, body) {
+        return this.req(`/api/pm/tasks/${encodeURIComponent(id)}/comments`, {
+            method: "POST",
+            body: JSON.stringify({ body }),
+        });
+    }
+}

package/dist/index.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { PlatformClient } from "./client.js";
+const token = process.env.PRODUCTOS_TOKEN;
+const baseUrl = (process.env.PRODUCTOS_URL ?? "https://platform.aioproductos.com").replace(/\/$/, "");
+if (!token) {
+    console.error("[productos-pm] PRODUCTOS_TOKEN is required — generate one in ProductOS → Settings → Tokens & Agents.");
+    process.exit(1);
+}
+const client = new PlatformClient(baseUrl, token);
+function text(data) {
+    return {
+        content: [
+            { type: "text", text: typeof data === "string" ? data : JSON.stringify(data, null, 2) },
+        ],
+    };
+}
+const server = new McpServer({ name: "productos-pm", version: "0.1.0" });
+server.tool("whoami", "Show the connected ProductOS identity (org, member).", {}, async () => text(await client.whoami()));
+server.tool("pm_meta", "List the org's PM lists, statuses, members, and features — use to resolve names to ids before create/update.", {}, async () => text(await client.meta()));
+server.tool("list_tasks", "List tasks in the org. Optional filters: status_id, list_id.", { status_id: z.string().optional(), list_id: z.string().optional() }, async (a) => text(await client.listTasks(a)));
+server.tool("get_task", "Get one task with its comments and assignees.", { id: z.string() }, async (a) => text(await client.getTask(a.id)));
+server.tool("create_task", "Create a task. Omitting list_id uses the org's first list. feature_id / insight_id link it to the ProductOS spine.", {
+    title: z.string(),
+    description: z.string().optional(),
+    priority: z.enum(["urgent", "high", "normal", "low"]).optional(),
+    list_id: z.string().optional(),
+    status_id: z.string().optional(),
+    feature_id: z.string().optional(),
+    insight_id: z.string().optional(),
+    assignee_member_ids: z.array(z.string()).optional(),
+}, async (a) => text(await client.createTask(a)));
+server.tool("update_task", "Update a task's fields (status, priority, title, description, feature, insight, assignees).", {
+    id: z.string(),
+    title: z.string().optional(),
+    description: z.string().nullable().optional(),
+    priority: z.enum(["urgent", "high", "normal", "low"]).nullable().optional(),
+    status_id: z.string().nullable().optional(),
+    feature_id: z.string().nullable().optional(),
+    insight_id: z.string().nullable().optional(),
+    assignee_member_ids: z.array(z.string()).optional(),
+}, async ({ id, ...body }) => text(await client.updateTask(id, body)));
+server.tool("comment_on_task", "Add a comment to a task.", { id: z.string(), body: z.string() }, async (a) => text(await client.comment(a.id, a.body)));
+async function main() {
+    await server.connect(new StdioServerTransport());
+}
+main().catch((err) => {
+    console.error("[productos-pm] fatal:", err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@aioproductoscom/mcp-pm",
+  "version": "0.1.0",
+  "description": "ProductOS PM Helper — an MCP server to manage ProductOS tickets from Claude Code, Cursor, Codex, and any MCP host.",
+  "type": "module",
+  "license": "MIT",
+  "author": "AIITDEVELOPMENT DOO Novi Sad",
+  "homepage": "https://platform.aioproductos.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/businesstalksnetwork/productos.git",
+    "directory": "packages/mcps/productos-pm"
+  },
+  "bugs": { "url": "https://github.com/businesstalksnetwork/productos/issues" },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "productos",
+    "claude",
+    "cursor",
+    "codex",
+    "project-management",
+    "product-management"
+  ],
+  "bin": { "productos-pm": "dist/index.js" },
+  "files": ["dist", "README.md"],
+  "engines": { "node": ">=18" },
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.0",
+    "typescript": "^5.6.0"
+  }
+}