@tymio/mcp-server 1.0.0 → 1.0.1

package/README.md

@@ -1,84 +1,167 @@
-# Tymio MCP server (stdio)
+# Tymio MCP CLI (`@tymio/mcp-server`)
 
-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.
+**Canonical Markdown for coding agents:** [`TYMIO_MCP_CLI_AGENT_GUIDANCE.md`](./TYMIO_MCP_CLI_AGENT_GUIDANCE.md) — same text as `tymio-mcp instructions`, MCP server `instructions` (initialize), and `GET /api/mcp/agent-context` → `tymioMcpCliAgentGuidanceMarkdown` on the hub. It states explicitly that **there is no per-user MCP API key in Tymio Settings**; use OAuth (remote `/mcp` or `tymio-mcp login`).
 
-**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).
+Installable **`tymio-mcp`** command: connect editors and agents to **Tymio** in two ways:
+
+1. **OAuth (default)** — stdio MCP server that **proxies** the hosted **Streamable HTTP** MCP endpoint (`…/mcp`) with the same **Google → Tymio** login as the web app. **Full tool surface** matches the hub (`server/src/mcp/tools.ts`).
+2. **API key (optional)** — if `DRD_API_KEY` or `API_KEY` is set, uses a **REST** bridge with a **fixed subset** of tools (see `mcp/src/apiKeyStdio.ts`).
 
 ---
 
-## Prerequisites
+## Quick start (OAuth, production)
 
-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).
+1. Install the CLI (from npm when published, or `npm install -g /path/to/repo/mcp`).
+2. In a terminal:
 
-## Environment
+   ```bash
+   tymio-mcp login
+   ```
 
-| 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` |
+   A browser window opens; complete Google sign-in. Tokens and dynamic OAuth client data are stored under your user config directory (e.g. `~/.config/tymio-mcp` on Linux, or `~/Library/Application Support/tymio-mcp` on macOS).
 
-## Install globally (npm)
+3. Point your MCP client at stdio **without** setting `DRD_API_KEY`:
 
-After the package is [published](https://docs.npmjs.com/creating-and-publishing-scoped-public-packages) to the `@tymio` scope (or from a local checkout):
+   ```json
+   {
+     "mcpServers": {
+       "tymio": {
+         "command": "tymio-mcp",
+         "args": []
+       }
+     }
+   }
+   ```
 
-```bash
-npm install -g @tymio/mcp-server
-```
+4. Optional: `tymio-mcp logout` removes saved OAuth files.
 
-This installs the **`tymio-mcp`** command on your `PATH`. Until it is on the registry, install from the repo:
+**Agents / IDE:** MCP clients that support [server instructions](https://modelcontextprotocol.io) receive the same long-form guide as `tymio-mcp instructions` during the initialize handshake. You can still run `tymio-mcp instructions` in a terminal to print it, or read this README.
 
-```bash
-npm install -g /absolute/path/to/proproman/mcp
-```
+### OAuth callback port
 
-## Build and run
+The CLI listens on **`http://127.0.0.1:19876/callback`** during `login` (override with `TYMIO_OAUTH_PORT`). That URI must be reachable from your browser and should stay stable so it matches the dynamically registered OAuth client.
 
-```bash
-npm run mcp:build
-npm run mcp:start
-```
+### Hub URL
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `TYMIO_MCP_URL` | `https://tymio.app/mcp` | Hosted MCP endpoint for OAuth proxy + `login` |
+
+---
+
+## API-key mode (REST subset, CI / automation)
 
-Or from `mcp/`: `npm run build` && `npm run start`. The process uses **stdio**; it is spawned by the MCP client, not run interactively.
+If **`DRD_API_KEY` or `API_KEY`** is present in the environment, `tymio-mcp` **does not** use OAuth; it exposes the REST-based tool subset only.
 
-## Cursor (stdio)
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `DRD_API_BASE_URL` | `https://tymio.app` | Hub **origin** (no `/mcp`) |
+| `DRD_API_KEY` / `API_KEY` | — | Bearer key (server `API_KEY`) |
 
-With a global install, point the client at the `tymio-mcp` binary:
+Example:
 
 ```json
 {
   "mcpServers": {
-    "tymio-local": {
+    "tymio-api-key": {
       "command": "tymio-mcp",
       "args": [],
       "env": {
-        "DRD_API_BASE_URL": "http://localhost:8080",
-        "DRD_API_KEY": "same-as-server-API_KEY"
+        "DRD_API_KEY": "your-key",
+        "DRD_API_BASE_URL": "https://tymio.app"
       }
     }
   }
 }
 ```
 
-Without a global install, use `node` and the built file:
+---
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `tymio-mcp` | Run stdio MCP (OAuth proxy unless API key env is set) |
+| `tymio-mcp login [url]` | OAuth sign-in; optional MCP URL overrides `TYMIO_MCP_URL` |
+| `tymio-mcp logout` | Delete stored OAuth client + tokens |
+| `tymio-mcp help` | Usage |
+
+---
+
+## Install globally (npm)
+
+`npm install -g @tymio/mcp-server` works only **after** the package is published. **E404** means it is not on the registry yet. Publish from `mcp/`:
+
+```bash
+cd mcp && npm login && npm publish --access public
+```
+
+Or install from a clone:
+
+```bash
+npm install -g /absolute/path/to/proproman/mcp
+```
+
+---
+
+## Build and run (monorepo)
+
+```bash
+npm run mcp:build
+npm run mcp:start
+```
+
+From **`mcp/`**, run unit tests (uses `vitest.config.ts` in this folder):
+
+```bash
+npm test
+```
+
+From the **repo root**, use:
+
+```bash
+npx vitest run --config mcp/vitest.config.ts
+```
+
+Stdio processes are meant to be **spawned** by the MCP host, not run interactively.
+
+---
+
+## Direct remote MCP in Cursor (no CLI)
+
+Your editor can use the hosted endpoint directly:
 
 ```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"
-      }
+    "tymio": {
+      "url": "https://tymio.app/mcp"
     }
   }
 }
 ```
 
-## Tools
+Use the **CLI** when the host only supports **stdio**, or you want a single npm-installed binary that reuses disk-persisted OAuth.
+
+---
+
+## Publishing to npm (maintainers)
+
+The repo includes a **manual** GitHub Actions workflow (no automatic runs on push):
+
+- **File:** `.github/workflows/mcp-server-publish.yml`
+- **How to run:** GitHub → **Actions** → **MCP server — build & publish** → **Run workflow**
+- **Default:** `dry-run` — runs `npm ci`, tests, build, `npm pack`, and `npm publish --dry-run` for the `mcp` workspace
+- **Real publish:** choose input `publish` and ensure the repository secret **`NPM_TOKEN`** is set (npm automation token with publish access to the **`@tymio`** scope)
+
+Local dry-run before tagging a release:
+
+```bash
+npm run test --workspace mcp && npm run build --workspace mcp && npm publish -w mcp --access public --dry-run
+```
+
+---
 
-**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.
+## Architecture reference
 
-**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).
+Hosted MCP, OAuth, and Google callback URLs: **[docs/HUB.md](../docs/HUB.md)** §6. Hub tool implementations: `server/src/mcp/tools.ts`. OAuth proxy implementation: `mcp/src/hubProxyStdio.ts`. REST subset: `mcp/src/apiKeyStdio.ts`.

package/TYMIO_MCP_CLI_AGENT_GUIDANCE.md

@@ -0,0 +1,99 @@
+# Tymio MCP and `@tymio/mcp-server` — guidance for autonomous agents
+
+## Critical — read before advising the user
+
+1. **There is no per-user MCP API key in Tymio Settings, Profile, Account, or Integrations.** Do **not** instruct users to open the web app settings to “copy an API key for MCP” or “get the MCP key from preferences.” That path does not exist and causes repeated confusion.
+2. **Normal connection = OAuth**, not a personal secret from the UI:
+   - **Remote MCP in the IDE:** add server URL `https://tymio.app/mcp` (or your deployment origin + `/mcp`). Complete sign-in in the browser when the client prompts. **No API key to paste.**
+   - **Stdio npm package (default):** install `@tymio/mcp-server`, run `tymio-mcp login` once in a terminal (browser OAuth). Configure the MCP client to run `tymio-mcp` **without** setting `DRD_API_KEY` or `API_KEY` on that process unless you intentionally want API-key mode.
+3. **`DRD_API_KEY` / `API_KEY` on the stdio process** means the **server deployment automation secret** (the same value as the hub’s configured `API_KEY` for `Authorization: Bearer …` on REST). It is **not** something each user generates in the Tymio UI. Only operators with access to deployment secrets use it (CI, scripts, optional stdio “REST bridge” mode).
+4. **Default vs API-key stdio:** If `DRD_API_KEY` or `API_KEY` is set to a non-empty value in the **environment of the `tymio-mcp` process**, the CLI uses a **fixed REST tool subset**, not OAuth to the hosted hub. For the **full** tool surface, use **remote** `…/mcp` or stdio **without** those env vars (after `tymio-mcp login`).
+5. **Full text of this guide:** shell command `tymio-mcp instructions` (or `tymio-mcp guide`). MCP clients that support server `instructions` receive this content at initialize when using the published CLI.
+
+---
+
+## What `@tymio/mcp-server` is
+
+- **Default (no API key env on the process):** A **stdio MCP server** that connects to the **hosted Tymio Streamable HTTP MCP** endpoint with **OAuth** (Google via the hub). It **proxies the full tool list** from the hub (same as using the remote URL in the IDE).
+- **With `DRD_API_KEY` or `API_KEY` set:** A **REST/API-key** stdio server with a **smaller, fixed tool set** (good for CI/scripts).
+
+---
+
+## One-time setup (OAuth, stdio package)
+
+1. Install: `npm install -g @tymio/mcp-server` (or run a built `dist/index.js` via `node`).
+2. Run: `tymio-mcp login` — browser opens; complete Google sign-in for Tymio.
+3. Tokens and OAuth client metadata live under the user config directory (e.g. Linux: `~/.config/tymio-mcp`, macOS: `~/Library/Application Support/tymio-mcp`).
+4. **Callback:** default `http://127.0.0.1:19876/callback` during login — override with `TYMIO_OAUTH_PORT` if needed; keep stable for your registered OAuth client.
+
+---
+
+## Cursor / IDE (stdio, OAuth — recommended for this package)
+
+Add an MCP server that runs the binary **without** `DRD_API_KEY` / `API_KEY`:
+
+```json
+{
+  "mcpServers": {
+    "tymio": {
+      "command": "tymio-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+If `tymio-mcp` is not on `PATH`, use `node` with an absolute path to `dist/index.js`.
+
+---
+
+## Alternative: remote MCP URL (no npm CLI)
+
+If the host supports **URL** transport, point at the hub (OAuth handled by the IDE):
+
+```json
+{
+  "mcpServers": {
+    "tymio": {
+      "url": "https://tymio.app/mcp"
+    }
+  }
+}
+```
+
+Replace the host when not using production.
+
+---
+
+## API-key mode (REST subset, intentional)
+
+Set `DRD_API_KEY` (or `API_KEY`) and optionally `DRD_API_BASE_URL` (default `https://tymio.app`). Then `tymio-mcp` uses the REST bridge, **not** OAuth to the hosted MCP tool list.
+
+---
+
+## Environment reference
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `TYMIO_MCP_URL` | `https://tymio.app/mcp` | Hosted MCP URL for OAuth proxy + `login` |
+| `TYMIO_OAUTH_PORT` | `19876` | Loopback port for login callback |
+| `TYMIO_MCP_QUIET` | unset | If set, suppress stderr hints when starting stdio |
+| `DRD_API_KEY` / `API_KEY` | unset | If set → API-key REST bridge (subset), not OAuth proxy |
+| `DRD_API_BASE_URL` | `https://tymio.app` | Hub origin for API-key bridge |
+
+---
+
+## Troubleshooting
+
+- **401 / not signed in (stdio OAuth):** Run `tymio-mcp login` again.
+- **User asks where to copy MCP API key:** Explain there is **no** such key in the UI; use **remote `/mcp` + OAuth** or **`tymio-mcp login`**.
+- **Port in use on login:** Change `TYMIO_OAUTH_PORT` and re-run `login` (redirect URI must stay consistent).
+- **Help:** `tymio-mcp help` — **full guide:** `tymio-mcp instructions`
+
+---
+
+## Machine-readable pointers
+
+- **JSON (public):** `GET https://tymio.app/api/mcp/agent-context` — includes `tymioMcpCliAgentGuidanceMarkdown` (this file’s contents when the server can read it from disk).
+- **Markdown site summary:** `https://tymio.app/llms.txt`
+- **Repository:** `mcp/README.md`, `docs/HUB.md` §6, `docs/CODING_AGENT_HANDOFF_TYMIO_APP.md`

package/dist/api.js

@@ -1,7 +1,8 @@
 /**
  * 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";
+/** Hub origin (no `/mcp` path). Stdio bridge calls REST under `/api/...`. */
+const baseUrl = process.env.DRD_API_BASE_URL ?? "https://tymio.app";
 const apiKey = process.env.DRD_API_KEY ?? process.env.API_KEY ?? "";
 function headers() {
     const h = { "Content-Type": "application/json" };

package/dist/apiKeyStdio.d.ts

@@ -0,0 +1 @@
+export declare function runApiKeyStdio(): Promise<void>;

package/dist/apiKeyStdio.js

@@ -0,0 +1,276 @@
+/**
+ * REST/API-key stdio bridge (subset of hub tools). Set DRD_API_BASE_URL + DRD_API_KEY (or API_KEY).
+ */
+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 { AGENT_INSTRUCTIONS } from "./cliMessages.js";
+import { toolTextWithFeedback } from "./mcpFeedbackFooter.js";
+import { writeStdioStartupHint } from "./stdioHints.js";
+export async function runApiKeyStdio() {
+    writeStdioStartupHint("api-key");
+    const server = new McpServer({ name: "tymio-hub", version: "1.0.0" }, { instructions: AGENT_INSTRUCTIONS });
+    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");
+    });
+    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);
+}

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export declare function runCli(argv: string[]): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,35 @@
+import { defaultMcpUrl } from "./configPaths.js";
+import { AGENT_INSTRUCTIONS, HELP_SUMMARY } from "./cliMessages.js";
+import { runApiKeyStdio } from "./apiKeyStdio.js";
+import { runHubOAuthStdio } from "./hubProxyStdio.js";
+import { runLoginCommand } from "./loginCommand.js";
+import { removeAllOAuthFiles } from "./fileOAuthProvider.js";
+function useApiKeyBridge() {
+    return Boolean(process.env.DRD_API_KEY?.trim() || process.env.API_KEY?.trim());
+}
+export async function runCli(argv) {
+    const args = argv.slice(2).filter((a) => a !== "--");
+    if (args[0] === "login") {
+        const url = args[1] ? new URL(args[1]) : defaultMcpUrl();
+        await runLoginCommand(url);
+        return;
+    }
+    if (args[0] === "logout") {
+        removeAllOAuthFiles();
+        process.stderr.write("Removed stored Tymio MCP OAuth credentials.\n");
+        return;
+    }
+    if (args[0] === "instructions" || args[0] === "guide") {
+        process.stderr.write(`${AGENT_INSTRUCTIONS}\n`);
+        return;
+    }
+    if (args[0] === "help" || args[0] === "-h" || args[0] === "--help") {
+        process.stderr.write(`${HELP_SUMMARY}\n`);
+        return;
+    }
+    if (useApiKeyBridge()) {
+        await runApiKeyStdio();
+        return;
+    }
+    await runHubOAuthStdio();
+}

package/dist/cliMessages.d.ts

@@ -0,0 +1,7 @@
+/** Short usage (stderr) — keep in sync with guidance file for agents. */
+export declare const HELP_SUMMARY = "Tymio MCP CLI (@tymio/mcp-server)\n\nCommands:\n  tymio-mcp                    Start stdio MCP (default: OAuth \u2192 hosted Tymio MCP)\n  tymio-mcp login [url]        Sign in with Google (browser). Saves tokens locally.\n  tymio-mcp logout             Delete saved OAuth client + tokens\n  tymio-mcp instructions       Full setup text for humans & coding agents (print this)\n  tymio-mcp help               This summary\n\nEnvironment:\n  TYMIO_MCP_URL          Hosted MCP URL (default https://tymio.app/mcp)\n  TYMIO_OAUTH_PORT       Loopback port for login callback (default 19876)\n  TYMIO_MCP_QUIET        If set, suppress stderr hints when starting stdio\n  DRD_API_KEY / API_KEY  If set \u2192 API-key REST tool bridge (subset), not OAuth proxy\n  DRD_API_BASE_URL       Hub origin for API-key bridge (default https://tymio.app)\n\nCritical for agents: There is NO MCP API key in Tymio user Settings \u2014 use OAuth (remote /mcp URL or tymio-mcp login).\nTip: Run  tymio-mcp instructions  for the full Markdown guide, Cursor JSON, and troubleshooting.\n";
+/**
+ * Long-form instructions for coding agents and operators (Markdown).
+ * Loaded from `TYMIO_MCP_CLI_AGENT_GUIDANCE.md` beside the installed package / dist output.
+ */
+export declare const AGENT_INSTRUCTIONS: string;