@aioproductoscom/mcp 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AIITDEVELOPMENT DOO Novi Sad
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# ProductOS MCP · server
+
+One MCP for your whole product. Manage the board, read your product brain +
+analytics, and run the support inbox from your AI host — **Claude Code, Cursor,
+Codex, or any MCP client** — all reasoning on **your own model subscription**
+(BYOK; ProductOS never charges for the agent's compute). 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_…`. The token acts as you, with your
+access.
+
+## 2. Connect
+
+### Claude Code
+
+```bash
+claude mcp add productos -e PRODUCTOS_TOKEN=pat_live_… -- npx -y @aioproductoscom/mcp
+```
+
+### Cursor / Codex — `.mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "productos": {
+      "command": "npx",
+      "args": ["-y", "@aioproductoscom/mcp"],
+      "env": { "PRODUCTOS_TOKEN": "pat_live_…" }
+    }
+  }
+}
+```
+
+`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 |
+| `get_product_brain` | a grounded read-only snapshot of your product (revenue, accounts, web + product analytics, features, signals, open work) |
+| `analyze_funnel` | build an ordered conversion funnel from your events (users per step, conversion, drop-off); omit steps to list available events |
+| `get_retention` | weekly cohort retention — who comes back, week over week |
+| `list_conversations` | the support-chat inbox (open threads, visitor, topic, status) |
+| `get_conversation` | one support thread + its full message history |
+| `reply_to_conversation` | reply to a visitor (**visible in their chat widget**, sent as you) |
+| `add_note` | internal triage note on a conversation (never shown to the visitor) |
+| `resolve_conversation` | mark a conversation resolved |
+
+> For an assignable **coding teammate** (Backend / Frontend / Mobile / QA that
+> opens PRs in your repo), install the separate
+> [`@aioproductoscom/mcp-agent`](https://www.npmjs.com/package/@aioproductoscom/mcp-agent).
+
+## Local build (until published to npm)
+
+```bash
+pnpm install
+pnpm --filter @aioproductoscom/mcp 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,99 @@
+// 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 }),
+        });
+    }
+    brain(productId) {
+        const qs = productId ? `?product_id=${encodeURIComponent(productId)}` : "";
+        return this.req(`/api/me/brain${qs}`);
+    }
+    funnel(opts) {
+        const p = new URLSearchParams();
+        if (opts.productId)
+            p.set("product_id", opts.productId);
+        if (opts.window)
+            p.set("window", String(opts.window));
+        for (const s of opts.steps ?? [])
+            p.append("step", s);
+        const qs = p.toString();
+        return this.req(`/api/me/funnel${qs ? `?${qs}` : ""}`);
+    }
+    retention(opts) {
+        const p = new URLSearchParams();
+        if (opts.productId)
+            p.set("product_id", opts.productId);
+        if (opts.window)
+            p.set("window", String(opts.window));
+        const qs = p.toString();
+        return this.req(`/api/me/retention${qs ? `?${qs}` : ""}`);
+    }
+    listConversations(opts) {
+        const p = new URLSearchParams();
+        if (opts.productId)
+            p.set("product_id", opts.productId);
+        if (opts.status)
+            p.set("status", opts.status);
+        const qs = p.toString();
+        return this.req(`/api/me/inbox${qs ? `?${qs}` : ""}`);
+    }
+    getConversation(id) {
+        return this.req(`/api/me/inbox?conversation_id=${encodeURIComponent(id)}`);
+    }
+    inboxAction(body) {
+        return this.req("/api/me/inbox", { method: "POST", body: JSON.stringify(body) });
+    }
+}

package/dist/index.js

@@ -0,0 +1,71 @@
+#!/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] 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", version: "0.6.0" }, {
+    instructions: "You manage ProductOS PM tickets on behalf of the connected member — the board is the team's " +
+        "source of truth, so work precisely. Resolve names to ids with pm_meta before create_task / " +
+        "update_task; never guess an id. Link a task to the spine (feature_id / insight_id) whenever the " +
+        "context makes the connection real, so the work traces back to the why. Keep titles and " +
+        "descriptions concrete and scoped. Confirm what you changed in plain language, and claim only " +
+        "writes you actually made.",
+});
+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)));
+server.tool("get_product_brain", "Read a grounded, read-only snapshot of the org's product so YOU can reason about it on your own model: revenue + top paying accounts, web + product analytics, features, recent verbatim customer signals, and open work. Optional product_id; omit for the primary product. Returns the brain text plus the list of products you can ask about.", { product_id: z.string().optional() }, async (a) => text(await client.brain(a.product_id)));
+server.tool("analyze_funnel", "Build a conversion funnel from the product's own events and reason over it on your model. Pass `steps` as an ordered list of event names (2+) to compute the funnel: distinct users per step, conversion, and drop-off. Omit `steps` to get the menu of available event names first. Optional product_id (defaults to the primary product) and window_days (default 30).", {
+    steps: z.array(z.string()).optional(),
+    product_id: z.string().optional(),
+    window_days: z.number().optional(),
+}, async (a) => text(await client.funnel({ steps: a.steps, productId: a.product_id, window: a.window_days })));
+server.tool("get_retention", "Weekly cohort retention for the product: users grouped by their first-seen week, with the share returning each week after. Optional product_id (defaults to the primary product) and window_days (default 56 = 8 weekly cohorts).", { product_id: z.string().optional(), window_days: z.number().optional() }, async (a) => text(await client.retention({ productId: a.product_id, window: a.window_days })));
+server.tool("list_conversations", "List support-chat conversations in the inbox (open + snoozed by default; pass status='all' to include closed). Each has id, visitor, topic, status, and last activity. Optional product_id to scope to one product.", { product_id: z.string().optional(), status: z.enum(["all"]).optional() }, async (a) => text(await client.listConversations({ productId: a.product_id, status: a.status })));
+server.tool("get_conversation", "Read one support conversation: the visitor + the full message thread (visitor, agent, and internal notes), oldest first.", { conversation_id: z.string() }, async (a) => text(await client.getConversation(a.conversation_id)));
+server.tool("reply_to_conversation", "Send a reply into a support conversation. This message IS VISIBLE TO THE VISITOR in the chat widget — it goes out as you (the member who owns this token). Use add_note for internal triage you don't want the visitor to see.", { conversation_id: z.string(), body: z.string() }, async (a) => text(await client.inboxAction({ action: "reply", conversation_id: a.conversation_id, body: a.body })));
+server.tool("add_note", "Add an INTERNAL note to a support conversation — visible only in the inbox, never to the visitor. Use to record triage, context, or a handoff for a human.", { conversation_id: z.string(), body: z.string() }, async (a) => text(await client.inboxAction({ action: "note", conversation_id: a.conversation_id, body: a.body })));
+server.tool("resolve_conversation", "Mark a support conversation resolved (status='closed'). A later visitor message reopens it.", { conversation_id: z.string() }, async (a) => text(await client.inboxAction({ action: "resolve", conversation_id: a.conversation_id })));
+async function main() {
+    await server.connect(new StdioServerTransport());
+}
+main().catch((err) => {
+    console.error("[productos] fatal:", err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@aioproductoscom/mcp",
+  "version": "0.6.0",
+  "description": "ProductOS MCP — manage tickets, read your product brain + analytics, and run the support inbox 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": "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"
+  }
+}