@aioproductoscom/mcp-agent 0.1.0

package/README.md

@@ -0,0 +1,81 @@
+# @aioproductoscom/mcp-agent
+
+Turn **Claude Code, Cursor, or Codex** into an assignable **Backend / Frontend / Mobile / QA**
+teammate inside [ProductOS](https://platform.aioproductos.com). Your team assigns it tasks like any
+teammate; it pulls the work, does it **in your repo on your model**, opens a PR (or writes tests),
+and reports status back. ProductOS owns the work lifecycle; your host owns the runtime — we never
+hold your repo credentials.
+
+## 1. Get a token
+
+A team admin opens **ProductOS → Settings → AI Team**, hires a teammate (name it, pick a role), and
+copies the token shown once. One agent = one role; the token decides which tools appear.
+
+## 2. Connect it (in the repo the agent should work in)
+
+The only thing you paste is the token. Launch your host from the project directory.
+
+### Claude Code
+
+```bash
+claude mcp add productos-agent \
+  -e PRODUCTOS_TOKEN=agent_live_xxx \
+  -- npx -y @aioproductoscom/mcp-agent
+```
+
+### Cursor — `.cursor/mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "productos-agent": {
+      "command": "npx",
+      "args": ["-y", "@aioproductoscom/mcp-agent"],
+      "env": { "PRODUCTOS_TOKEN": "agent_live_xxx" }
+    }
+  }
+}
+```
+
+### Codex / any MCP host — `mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "productos-agent": {
+      "command": "npx",
+      "args": ["-y", "@aioproductoscom/mcp-agent"],
+      "env": { "PRODUCTOS_TOKEN": "agent_live_xxx" }
+    }
+  }
+}
+```
+
+Self-hosted ProductOS? Add `"PRODUCTOS_URL": "https://platform.your-domain.com"`.
+
+## 3. Run the loop
+
+Tell your host: **"You're a ProductOS agent — call `get_skill`, then work your assigned tasks."**
+
+| Tool | What it does |
+|---|---|
+| `whoami` | Org, your name, your role |
+| `get_skill` | Your role-specialized workflow + hard rules (read first) |
+| `get_assigned_tasks` | Tasks assigned to you, pullable, with run state |
+| `get_task_context(id)` | Acceptance criteria + linked feature/insight/product + thread |
+| `start_task(id)` | Atomic claim → In Progress (fails if another session holds it) |
+| `report_progress(id, note)` | Progress comment on the task |
+| `submit_work(id, …)` | **Dev** — attach PR + summary + files → In Review |
+| `submit_tests(id, …)` | **QA** — attach tests + coverage + results → In Review |
+| `block_task(id, reason)` | Stuck / underspecified → blocked + a clear question |
+| `ping` | Keep "online" in the team view |
+
+## Guarantees
+
+- **Human-in-the-loop.** `submit_work` lands the task **In Review** — it never merges. A human
+  approves the PR.
+- **Least privilege.** A QA token can't submit code; a Dev token can't reassign humans or touch
+  billing. Scopes are enforced server-side, per role.
+- **No secrets in the bundle.** The token is yours, pasted into your host. The agent acts locally;
+  only lifecycle data (status, PR URL, summary, test results) is posted back.
+- **One claim per task.** Two sessions of one token can't open duplicate PRs (atomic claim).

package/dist/client.js

@@ -0,0 +1,63 @@
+// Thin typed HTTP client over the platform's agent worker endpoints. The agent
+// token is the only credential; nothing is stored. Uses global fetch (Node 18+).
+export class AgentClient {
+    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 text = await res.text();
+        const json = text ? JSON.parse(text) : {};
+        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/agent/me");
+    }
+    ping() {
+        return this.req("/api/agent/ping", { method: "POST" });
+    }
+    assignedTasks() {
+        return this.req("/api/agent/tasks");
+    }
+    taskContext(id) {
+        return this.req(`/api/agent/tasks/${encodeURIComponent(id)}`);
+    }
+    action(id, body) {
+        return this.req(`/api/agent/tasks/${encodeURIComponent(id)}`, {
+            method: "POST",
+            body: JSON.stringify(body),
+        });
+    }
+    start(id) {
+        return this.action(id, { action: "start" });
+    }
+    progress(id, note) {
+        return this.action(id, { action: "progress", note });
+    }
+    submitWork(id, b) {
+        return this.action(id, { action: "submit", ...b });
+    }
+    submitTests(id, b) {
+        return this.action(id, { action: "tests", ...b });
+    }
+    block(id, reason) {
+        return this.action(id, { action: "block", reason });
+    }
+}

package/dist/index.js

@@ -0,0 +1,72 @@
+#!/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 { AgentClient } from "./client.js";
+import { ROLE_SKILLS, ROLE_LABEL, SKILL_VERSION } from "./skills.js";
+const token = process.env.PRODUCTOS_TOKEN;
+const baseUrl = (process.env.PRODUCTOS_URL ?? "https://platform.aioproductos.com").replace(/\/$/, "");
+if (!token) {
+    console.error("[productos-agent] PRODUCTOS_TOKEN is required — your team admin generates it in ProductOS → Settings → AI Team.");
+    process.exit(1);
+}
+const client = new AgentClient(baseUrl, token);
+function text(data) {
+    return {
+        content: [
+            { type: "text", text: typeof data === "string" ? data : JSON.stringify(data, null, 2) },
+        ],
+    };
+}
+async function main() {
+    // Identify ourselves up front — the token's role decides which tools we expose
+    // (the server enforces the same scopes, this is belt-and-braces + a clean UX).
+    let role;
+    let name;
+    try {
+        const me = await client.whoami();
+        role = me.role;
+        name = me.name;
+    }
+    catch (err) {
+        console.error(`[productos-agent] could not authenticate: ${err.message}`);
+        process.exit(1);
+    }
+    const who = `${name ?? "Agent"} · ${ROLE_LABEL[role]}`;
+    const isQA = role === "qa";
+    const server = new McpServer({ name: "productos-agent", version: "0.1.0" }, {
+        instructions: `You are "${who}", an AI teammate inside ProductOS. Work the assigned-task loop: get_assigned_tasks → get_task_context → start_task → (do the work in THIS repo) → report_progress → ${isQA ? "submit_tests" : "submit_work"}; block_task if stuck. Call get_skill first for your full workflow and hard rules (open a PR, never merge). Skill v${SKILL_VERSION}.`,
+    });
+    server.tool("whoami", "Show this agent's identity (org, name, role).", {}, async () => text(await client.whoami()));
+    server.tool("get_skill", "Your role-specialized workflow + hard rules. Read this before starting work.", {}, async () => text(`${ROLE_SKILLS[role]}\n\n— skill v${SKILL_VERSION}`));
+    server.tool("get_assigned_tasks", "List the tasks assigned to you (pullable), each with its current run state.", {}, async () => text(await client.assignedTasks()));
+    server.tool("get_task_context", "Full context for one assigned task: acceptance criteria, linked feature/insight/product, the comment thread, and your run state.", { id: z.string() }, async (a) => text(await client.taskContext(a.id)));
+    server.tool("start_task", "Claim an assigned task (atomic). You then own it and the board moves to In Progress. Fails if another session already holds it.", { id: z.string() }, async (a) => text(await client.start(a.id)));
+    server.tool("report_progress", "Post a progress note on the task so the human can follow along.", { id: z.string(), note: z.string() }, async (a) => text(await client.progress(a.id, a.note)));
+    server.tool("block_task", "Mark the task blocked with a precise reason (underspecified, missing dependency, untestable). Beats guessing.", { id: z.string(), reason: z.string() }, async (a) => text(await client.block(a.id, a.reason)));
+    if (isQA) {
+        server.tool("submit_tests", "Attach the tests you wrote + measured coverage + run results. The task lands In Review for a human.", {
+            id: z.string(),
+            framework: z.string().optional(),
+            files: z.array(z.string()).optional(),
+            coverage: z.number().optional(),
+            results: z.string().optional(),
+            idempotency_key: z.string().optional(),
+        }, async ({ id, ...b }) => text(await client.submitTests(id, b)));
+    }
+    else {
+        server.tool("submit_work", "Attach your PR URL + summary + files changed. The task lands In Review for a human — it is never merged automatically.", {
+            id: z.string(),
+            pr_url: z.string().optional(),
+            summary: z.string().optional(),
+            files_changed: z.array(z.string()).optional(),
+            idempotency_key: z.string().optional(),
+        }, async ({ id, ...b }) => text(await client.submitWork(id, b)));
+    }
+    server.tool("ping", "Heartbeat — keep this agent shown as online in the team view.", {}, async () => text(await client.ping()));
+    await server.connect(new StdioServerTransport());
+}
+main().catch((err) => {
+    console.error("[productos-agent] fatal:", err);
+    process.exit(1);
+});

package/dist/skills.js

@@ -0,0 +1,101 @@
+// Versioned, role-specialized agent skills (the prompt + workflow the customer's
+// host runs). Conservative by design — this is the one quality lever we own, and
+// the agent wears the customer's brand on a model + repo we don't control. The
+// server exposes the right one via get_skill() and frames it in `instructions`.
+//
+// Bump SKILL_VERSION on any behavioural change so a run is traceable to a skill.
+export const SKILL_VERSION = "0.1.0";
+const LOOP = `## The loop
+1. \`get_assigned_tasks\` — find work assigned to you. Pick the highest-priority unstarted one.
+2. \`get_task_context(id)\` — read the title, acceptance criteria (description), and any linked
+   feature/insight/product. If the goal is unclear, \`block_task\` with a precise question instead
+   of guessing.
+3. \`start_task(id)\` — claim it (you now own it; the board moves to In Progress). If the claim is
+   refused, another session already holds it — pick a different task.
+4. Do the work **in the repo the host was launched in**, following that repo's existing
+   conventions, language, and patterns. Small, reviewable changes.
+5. \`report_progress(id, note)\` at meaningful checkpoints so the human can follow along.
+
+## Hard rules (never break)
+- **Open a PR. Never push to a default/protected branch, never force-push, never merge.** A human
+  approves and merges. Your job ends at "ready for review".
+- Don't touch secrets, infra, billing, or unrelated files. Stay in the task's scope.
+- If you're stuck, blocked on a dependency, or the task is underspecified → \`block_task(id, reason)\`.
+  A clear block beats a wrong implementation.`;
+const BACKEND = `# ProductOS · Backend Dev
+
+You are a **Backend** AI teammate. You implement server-side work — APIs, data models,
+migrations, business logic, jobs — in the customer's repository.
+
+${LOOP}
+
+## Backend specifics
+- Match the project's framework, ORM/query layer, and error-handling style. Validate inputs at
+  boundaries; never trust external data.
+- Migrations: additive and reversible where possible; never destructive without an explicit ask.
+- Add/extend tests for the logic you change. Note any new env vars or migration steps in the PR.
+
+## Finishing
+\`submit_work(id, { pr_url, summary, files_changed })\` — attach the PR URL, a short summary of the
+approach, and the files you touched. The task lands **In Review** for a human.`;
+const FRONTEND = `# ProductOS · Frontend Dev
+
+You are a **Frontend** AI teammate. You implement UI work — components, pages, state, styling,
+accessibility — in the customer's repository.
+
+${LOOP}
+
+## Frontend specifics
+- Reuse the project's design system, components, and tokens. Don't introduce a new UI library or
+  one-off styles when an existing pattern fits.
+- Keep components accessible (semantic HTML, labels, keyboard, focus). Respect reduced-motion.
+- Verify the change renders at the key breakpoints; avoid layout shift. Add component/interaction
+  tests where the project has them.
+
+## Finishing
+\`submit_work(id, { pr_url, summary, files_changed })\` — attach the PR URL, a short summary, and the
+files you touched. The task lands **In Review** for a human.`;
+const MOBILE = `# ProductOS · Mobile Dev
+
+You are a **Mobile** AI teammate. You implement mobile app work — screens, navigation, native
+integration, platform behaviour — in the customer's repository.
+
+${LOOP}
+
+## Mobile specifics
+- Match the project's stack (React Native / Swift / Kotlin / Flutter) and its navigation + state
+  conventions. Handle both platforms when the project targets both.
+- Mind platform differences (safe areas, permissions, lifecycle, offline). Keep bundles lean.
+- Add tests where the project supports them; note any native/config steps in the PR.
+
+## Finishing
+\`submit_work(id, { pr_url, summary, files_changed })\` — attach the PR URL, a short summary, and the
+files you touched. The task lands **In Review** for a human.`;
+const QA = `# ProductOS · QA
+
+You are a **QA** AI teammate. You don't ship product code — you **write and run tests** for the
+assigned task in the customer's repository, then report coverage and results.
+
+${LOOP}
+
+## QA specifics
+- Write the test layer the project uses (unit / integration / e2e — Playwright, Vitest, Jest, etc.).
+  Cover the acceptance criteria, the happy path, and the edge/error cases.
+- Run the tests. Report real numbers — don't claim coverage you didn't measure.
+- If the feature is untestable as built (no hooks, no data-testids), \`block_task\` with what's needed.
+
+## Finishing
+\`submit_tests(id, { framework, files, coverage, results })\` — attach the framework, the test files,
+the measured coverage, and the run results. The task lands **In Review** for a human.`;
+export const ROLE_SKILLS = {
+    backend: BACKEND,
+    frontend: FRONTEND,
+    mobile: MOBILE,
+    qa: QA,
+};
+export const ROLE_LABEL = {
+    backend: "Backend",
+    frontend: "Frontend",
+    mobile: "Mobile",
+    qa: "QA",
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@aioproductoscom/mcp-agent",
+  "version": "0.1.0",
+  "description": "ProductOS Agent — an MCP server that turns Claude Code, Cursor, or Codex into an assignable Backend/Frontend/Mobile/QA teammate inside ProductOS.",
+  "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-agent"
+  },
+  "bugs": { "url": "https://github.com/businesstalksnetwork/productos/issues" },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "productos",
+    "claude",
+    "cursor",
+    "codex",
+    "ai-agent",
+    "coding-agent"
+  ],
+  "bin": { "productos-agent": "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"
+  }
+}