@tymio/mcp-server 1.0.0

package/README.md

@@ -0,0 +1,84 @@
+# Tymio MCP server (stdio)
+
+Local **stdio** MCP server for the Tymio hub: exposes REST APIs as [MCP](https://modelcontextprotocol.io/) tools using a **Bearer API key**. Use for scripts, CI, or when you do not want remote OAuth.
+
+**Remote MCP** (recommended for daily Cursor use) runs inside the main Express app at `POST /mcp` with OAuth 2.1 and Google. See **[docs/HUB.md](../docs/HUB.md)** §6 for architecture, Google callback URL, and Cursor config (local + remote).
+
+---
+
+## Prerequisites
+
+1. Server env: `API_KEY` set; optional `API_KEY_USER_ID` (otherwise first `SUPER_ADMIN` is used).
+2. Tymio API running (e.g. `npm run dev` from repo root).
+
+## Environment
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `DRD_API_BASE_URL` | No (default `http://localhost:8080`) | Hub API base URL |
+| `DRD_API_KEY` | Yes for authenticated tools | Same value as server `API_KEY` |
+
+## Install globally (npm)
+
+After the package is [published](https://docs.npmjs.com/creating-and-publishing-scoped-public-packages) to the `@tymio` scope (or from a local checkout):
+
+```bash
+npm install -g @tymio/mcp-server
+```
+
+This installs the **`tymio-mcp`** command on your `PATH`. Until it is on the registry, install from the repo:
+
+```bash
+npm install -g /absolute/path/to/proproman/mcp
+```
+
+## Build and run
+
+```bash
+npm run mcp:build
+npm run mcp:start
+```
+
+Or from `mcp/`: `npm run build` && `npm run start`. The process uses **stdio**; it is spawned by the MCP client, not run interactively.
+
+## Cursor (stdio)
+
+With a global install, point the client at the `tymio-mcp` binary:
+
+```json
+{
+  "mcpServers": {
+    "tymio-local": {
+      "command": "tymio-mcp",
+      "args": [],
+      "env": {
+        "DRD_API_BASE_URL": "http://localhost:8080",
+        "DRD_API_KEY": "same-as-server-API_KEY"
+      }
+    }
+  }
+}
+```
+
+Without a global install, use `node` and the built file:
+
+```json
+{
+  "mcpServers": {
+    "tymio-local": {
+      "command": "node",
+      "args": ["/ABSOLUTE/PATH/TO/repo/mcp/dist/index.js"],
+      "env": {
+        "DRD_API_BASE_URL": "http://localhost:8080",
+        "DRD_API_KEY": "same-as-server-API_KEY"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+**Ontology / playbook (Tymio):** `tymio_get_coding_agent_guide` (full [CODING_AGENT_TYMIO.md](../docs/CODING_AGENT_TYMIO.md) from server), `tymio_get_agent_brief`, `tymio_list_capabilities`, `tymio_get_capability` — see [docs/HUB.md](../docs/HUB.md) §6.1.
+
+**Backlog / data (historical `drd_*` prefix):** health, meta, initiatives, features, requirements, domains, products, accounts, partners, demands, campaigns, timeline, assignments, stakeholders, etc. Full list: `server/src/mcp/tools.ts` and `mcp/src/index.ts` (stdio subset).

package/dist/api.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Minimal Tymio hub API client for the stdio MCP server. Uses DRD_API_BASE_URL and DRD_API_KEY from env.
+ */
+/** JSON-friendly body; plain objects are stringified. */
+export type DrdFetchInit = Omit<RequestInit, "body"> & {
+    body?: string | Record<string, unknown>;
+};
+export declare function drdFetch<T>(path: string, init?: DrdFetchInit): Promise<T>;
+/** Plain text body (e.g. Markdown agent brief). */
+export declare function drdFetchText(path: string, init?: RequestInit): Promise<string>;
+export declare function getBaseUrl(): string;
+export declare function hasApiKey(): boolean;

package/dist/api.js

@@ -0,0 +1,45 @@
+/**
+ * Minimal Tymio hub API client for the stdio MCP server. Uses DRD_API_BASE_URL and DRD_API_KEY from env.
+ */
+const baseUrl = process.env.DRD_API_BASE_URL ?? "http://localhost:8080";
+const apiKey = process.env.DRD_API_KEY ?? process.env.API_KEY ?? "";
+function headers() {
+    const h = { "Content-Type": "application/json" };
+    if (apiKey)
+        h["Authorization"] = `Bearer ${apiKey}`;
+    return h;
+}
+export async function drdFetch(path, init) {
+    const { body, ...rest } = init ?? {};
+    const bodyInit = body === undefined ? undefined : typeof body === "string" ? body : JSON.stringify(body);
+    const res = await fetch(`${baseUrl}${path}`, {
+        ...rest,
+        body: bodyInit,
+        headers: { ...headers(), ...(rest.headers ?? {}) }
+    });
+    if (!res.ok) {
+        const body = await res.text();
+        throw new Error(`Tymio API ${res.status}: ${body || res.statusText}`);
+    }
+    if (res.status === 204)
+        return undefined;
+    return (await res.json());
+}
+/** Plain text body (e.g. Markdown agent brief). */
+export async function drdFetchText(path, init) {
+    const res = await fetch(`${baseUrl}${path}`, {
+        ...init,
+        headers: { ...headers(), ...(init?.headers ?? {}) }
+    });
+    if (!res.ok) {
+        const errBody = await res.text();
+        throw new Error(`Tymio API ${res.status}: ${errBody || res.statusText}`);
+    }
+    return res.text();
+}
+export function getBaseUrl() {
+    return baseUrl;
+}
+export function hasApiKey() {
+    return Boolean(apiKey);
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,283 @@
+#!/usr/bin/env node
+/**
+ * Tymio MCP server (stdio) — exposes hub REST APIs as MCP tools for agents.
+ * Set DRD_API_BASE_URL and DRD_API_KEY in the environment.
+ */
+import { z } from "zod";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { drdFetch, drdFetchText, getBaseUrl, hasApiKey } from "./api.js";
+import { toolTextWithFeedback } from "./mcpFeedbackFooter.js";
+const server = new McpServer({
+    name: "tymio-hub",
+    version: "1.0.0"
+});
+async function textContent(text) {
+    return toolTextWithFeedback(getBaseUrl(), text);
+}
+// --- Health & meta (no auth required for health)
+server.registerTool("drd_health", {
+    title: "Tymio API health check",
+    description: "Check if the Tymio hub API is reachable.",
+    inputSchema: z.object({})
+}, async () => {
+    const data = await drdFetch("/api/health");
+    return textContent(JSON.stringify(data));
+});
+server.registerTool("drd_meta", {
+    title: "Get Tymio meta",
+    description: "Get meta data: domains, products, accounts, partners, personas, revenue streams, users.",
+    inputSchema: z.object({})
+}, async () => {
+    const data = await drdFetch("/api/meta");
+    return textContent(JSON.stringify(data, null, 2));
+});
+// --- Initiatives
+const listInitiativesSchema = z.object({
+    domainId: z.string().optional(),
+    ownerId: z.string().optional(),
+    horizon: z.enum(["NOW", "NEXT", "LATER"]).optional(),
+    priority: z.enum(["P0", "P1", "P2", "P3"]).optional(),
+    isGap: z.boolean().optional()
+});
+server.registerTool("drd_list_initiatives", {
+    title: "List initiatives",
+    description: "List initiatives with optional filters: domainId, ownerId, horizon, priority, isGap.",
+    inputSchema: listInitiativesSchema
+}, async (args) => {
+    const params = new URLSearchParams();
+    if (args.domainId)
+        params.set("domainId", args.domainId);
+    if (args.ownerId)
+        params.set("ownerId", args.ownerId);
+    if (args.horizon)
+        params.set("horizon", args.horizon);
+    if (args.priority)
+        params.set("priority", args.priority);
+    if (args.isGap !== undefined)
+        params.set("isGap", String(args.isGap));
+    const data = await drdFetch(`/api/initiatives?${params.toString()}`);
+    return textContent(JSON.stringify(data.initiatives, null, 2));
+});
+server.registerTool("drd_get_initiative", {
+    title: "Get initiative by ID",
+    description: "Get a single initiative by its ID.",
+    inputSchema: z.object({ id: z.string().describe("Initiative ID") })
+}, async ({ id }) => {
+    const data = await drdFetch(`/api/initiatives/${id}`);
+    return textContent(JSON.stringify(data.initiative, null, 2));
+});
+server.registerTool("drd_create_initiative", {
+    title: "Create initiative",
+    description: "Create a new initiative. Requires admin/editor role.",
+    inputSchema: z.object({
+        title: z.string(),
+        domainId: z.string(),
+        description: z.string().optional(),
+        ownerId: z.string().optional(),
+        priority: z.enum(["P0", "P1", "P2", "P3"]).optional(),
+        horizon: z.enum(["NOW", "NEXT", "LATER"]).optional(),
+        status: z.enum(["IDEA", "PLANNED", "IN_PROGRESS", "DONE", "BLOCKED"]).optional(),
+        commercialType: z.string().optional(),
+        isGap: z.boolean().optional()
+    })
+}, async (body) => {
+    const data = await drdFetch("/api/initiatives", {
+        method: "POST",
+        body: JSON.stringify(body)
+    });
+    return textContent(JSON.stringify(data.initiative, null, 2));
+});
+server.registerTool("drd_update_initiative", {
+    title: "Update initiative",
+    description: "Update an existing initiative by ID.",
+    inputSchema: z.object({
+        id: z.string(),
+        title: z.string().optional(),
+        domainId: z.string().optional(),
+        description: z.string().optional(),
+        ownerId: z.string().optional(),
+        priority: z.enum(["P0", "P1", "P2", "P3"]).optional(),
+        horizon: z.enum(["NOW", "NEXT", "LATER"]).optional(),
+        status: z.enum(["IDEA", "PLANNED", "IN_PROGRESS", "DONE", "BLOCKED"]).optional(),
+        commercialType: z.string().optional(),
+        isGap: z.boolean().optional()
+    })
+}, async ({ id, ...body }) => {
+    const data = await drdFetch(`/api/initiatives/${id}`, {
+        method: "PUT",
+        body: JSON.stringify(body)
+    });
+    return textContent(JSON.stringify(data.initiative, null, 2));
+});
+server.registerTool("drd_delete_initiative", {
+    title: "Delete initiative",
+    description: "Delete an initiative by ID.",
+    inputSchema: z.object({ id: z.string() })
+}, async ({ id }) => {
+    await drdFetch(`/api/initiatives/${id}`, { method: "DELETE" });
+    return textContent(JSON.stringify({ ok: true }));
+});
+// --- Domains, products, personas
+server.registerTool("drd_list_domains", {
+    title: "List domains",
+    description: "List all domains.",
+    inputSchema: z.object({})
+}, async () => {
+    const data = await drdFetch("/api/domains");
+    return textContent(JSON.stringify(data.domains, null, 2));
+});
+server.registerTool("drd_create_domain", {
+    title: "Create domain",
+    description: "Create a new domain (pillar). Requires workspace OWNER or ADMIN.",
+    inputSchema: z.object({
+        name: z.string().min(1),
+        color: z.string().min(1),
+        sortOrder: z.number().int().optional()
+    })
+}, async (body) => {
+    const data = await drdFetch("/api/domains", {
+        method: "POST",
+        body: JSON.stringify({
+            name: body.name,
+            color: body.color,
+            sortOrder: body.sortOrder ?? 0
+        })
+    });
+    return textContent(JSON.stringify(data.domain, null, 2));
+});
+server.registerTool("drd_list_products", {
+    title: "List products",
+    description: "List all products (with hierarchy).",
+    inputSchema: z.object({})
+}, async () => {
+    const data = await drdFetch("/api/products");
+    return textContent(JSON.stringify(data.products, null, 2));
+});
+server.registerTool("drd_list_personas", {
+    title: "List personas",
+    description: "List all personas.",
+    inputSchema: z.object({})
+}, async () => {
+    const data = await drdFetch("/api/personas");
+    return textContent(JSON.stringify(data.personas, null, 2));
+});
+server.registerTool("drd_list_accounts", {
+    title: "List accounts",
+    description: "List all accounts.",
+    inputSchema: z.object({})
+}, async () => {
+    const data = await drdFetch("/api/accounts");
+    return textContent(JSON.stringify(data.accounts, null, 2));
+});
+server.registerTool("drd_list_partners", {
+    title: "List partners",
+    description: "List all partners.",
+    inputSchema: z.object({})
+}, async () => {
+    const data = await drdFetch("/api/partners");
+    return textContent(JSON.stringify(data.partners, null, 2));
+});
+// --- KPIs, milestones, stakeholders
+server.registerTool("drd_list_kpis", {
+    title: "List KPIs",
+    description: "List all initiative KPIs with their initiative context (title, domain, owner).",
+    inputSchema: z.object({})
+}, async () => {
+    const data = await drdFetch("/api/kpis");
+    return textContent(JSON.stringify(data.kpis, null, 2));
+});
+server.registerTool("drd_list_milestones", {
+    title: "List milestones",
+    description: "List all initiative milestones with their initiative context.",
+    inputSchema: z.object({})
+}, async () => {
+    const data = await drdFetch("/api/milestones");
+    return textContent(JSON.stringify(data.milestones, null, 2));
+});
+server.registerTool("drd_list_demands", {
+    title: "List demands",
+    description: "List all demands (from accounts, partners, internal, compliance).",
+    inputSchema: z.object({})
+}, async () => {
+    const data = await drdFetch("/api/demands");
+    return textContent(JSON.stringify(data.demands, null, 2));
+});
+server.registerTool("drd_list_revenue_streams", {
+    title: "List revenue streams",
+    description: "List all revenue streams.",
+    inputSchema: z.object({})
+}, async () => {
+    const data = await drdFetch("/api/revenue-streams");
+    return textContent(JSON.stringify(data.revenueStreams, null, 2));
+});
+server.registerTool("tymio_get_coding_agent_guide", {
+    title: "Get Tymio coding agent playbook (Markdown)",
+    description: "Full docs/CODING_AGENT_TYMIO.md: MCP usage, as-is to Tymio, feature lifecycle. Call at session start when automating this hub.",
+    inputSchema: z.object({})
+}, async () => {
+    const md = await drdFetchText("/api/agent/coding-guide");
+    return textContent(md);
+});
+server.registerTool("tymio_get_agent_brief", {
+    title: "Get compiled agent capability brief",
+    description: "Returns the hub capability ontology as Markdown or JSON. mode=compact|full, format=md|json.",
+    inputSchema: z.object({
+        mode: z.enum(["compact", "full"]).default("compact"),
+        format: z.enum(["md", "json"]).default("md")
+    })
+}, async (args) => {
+    const params = new URLSearchParams({ mode: args.mode, format: args.format });
+    const q = params.toString();
+    if (args.format === "md") {
+        const text = await drdFetchText(`/api/ontology/brief?${q}`);
+        return textContent(text);
+    }
+    const raw = await drdFetchText(`/api/ontology/brief?${q}`);
+    try {
+        const parsed = JSON.parse(raw);
+        return textContent(JSON.stringify(parsed, null, 2));
+    }
+    catch {
+        return textContent(raw);
+    }
+});
+server.registerTool("tymio_list_capabilities", {
+    title: "List hub capabilities (ontology)",
+    description: "Optional status: ACTIVE, DRAFT, DEPRECATED.",
+    inputSchema: z.object({ status: z.enum(["ACTIVE", "DRAFT", "DEPRECATED"]).optional() })
+}, async (args) => {
+    const params = new URLSearchParams();
+    if (args.status)
+        params.set("status", args.status);
+    const q = params.toString();
+    const data = await drdFetch(`/api/ontology/capabilities${q ? `?${q}` : ""}`);
+    return textContent(JSON.stringify(data, null, 2));
+});
+server.registerTool("tymio_get_capability", {
+    title: "Get one capability by id or slug",
+    description: "Provide id or slug.",
+    inputSchema: z.object({ id: z.string().optional(), slug: z.string().optional() })
+}, async (args) => {
+    if (args.id) {
+        const data = await drdFetch(`/api/ontology/capabilities/${args.id}`);
+        return textContent(JSON.stringify(data, null, 2));
+    }
+    if (args.slug) {
+        const data = await drdFetch(`/api/ontology/capabilities/by-slug/${encodeURIComponent(args.slug)}`);
+        return textContent(JSON.stringify(data, null, 2));
+    }
+    throw new Error("Provide id or slug");
+});
+// --- Run
+async function main() {
+    if (!hasApiKey()) {
+        process.stderr.write("Warning: DRD_API_KEY is not set. Authenticated API calls will fail. Set DRD_API_KEY and API_KEY on the server.\n");
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/mcpFeedbackFooter.d.ts

@@ -0,0 +1,7 @@
+/** Async: resolves to MCP content block with optional feedback footer. */
+export declare function toolTextWithFeedback(baseUrl: string, body: string): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/dist/mcpFeedbackFooter.js

@@ -0,0 +1,33 @@
+/**
+ * Fetches /api/mcp/agent-context (no auth) once and appends feedback instructions to every tool result.
+ */
+let cachedFooter = "";
+let loadPromise = null;
+async function loadFromHub(baseUrl) {
+    try {
+        const url = `${baseUrl.replace(/\/$/, "")}/api/mcp/agent-context`;
+        const res = await fetch(url);
+        if (!res.ok)
+            return;
+        const data = (await res.json());
+        if (typeof data.feedbackReporting === "string" && data.feedbackReporting.trim()) {
+            cachedFooter = data.feedbackReporting.trim();
+        }
+    }
+    catch {
+        /* hub may be offline during local dev */
+    }
+}
+function ensureLoaded(baseUrl) {
+    if (cachedFooter)
+        return Promise.resolve();
+    if (!loadPromise)
+        loadPromise = loadFromHub(baseUrl);
+    return loadPromise;
+}
+/** Async: resolves to MCP content block with optional feedback footer. */
+export async function toolTextWithFeedback(baseUrl, body) {
+    await ensureLoaded(baseUrl);
+    const text = cachedFooter ? `${body}\n\n---\n${cachedFooter}` : body;
+    return { content: [{ type: "text", text }] };
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@tymio/mcp-server",
+  "version": "1.0.0",
+  "description": "Tymio hub MCP server (stdio) — exposes REST APIs as MCP tools via API key",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "tymio-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.0",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.14",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}