@tymio/mcp-server 1.0.0 → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+## 2.0.0
+
+### Breaking
+
+- **Pinned workspace for stdio** — `tymio-mcp` (OAuth proxy and API-key bridge) **requires** `TYMIO_WORKSPACE_SLUG` or `DRD_WORKSPACE_SLUG` (the hub workspace slug this process is bound to). Every tool call must include **`workspaceSlug`** matching that pin (case-insensitive). Prevents agents from targeting another workspace for the same user.
+- **Tests / local tooling only** — set `TYMIO_MCP_SKIP_WORKSPACE_PINNING=1` to skip the startup requirement (do not use in production agent configs).
+
+### Added / changed
+
+- **API-key stdio** — Resolves the pinned slug to a tenant via `GET /api/me/tenants` and sends **`X-Tenant-Id`** on all hub REST calls; tool payloads still carry `workspaceSlug` for consistency but must match the pin.
+- **OAuth stdio (hub proxy)** — Asserts tool arguments match the pinned slug before `callTool` to the hosted MCP.
+- **Hub (server) MCP** — Stricter `workspaceSlug` validation (length, `^[a-z0-9-]+$`) and **case-insensitive** match to the session workspace; API-key sessions can use tenant-list routes needed for resolution (`authViaApiKey` + `requireSession` behavior).
+
+### Requires
+
+- **Deploy hub** with the matching server changes **before or with** rolling out this CLI to users who rely on API-key stdio or the updated MCP slug rules.
+
+## 1.1.0
+
+- **Bundled agent personas** (`personas/*.md`): `workspace`, `pm`, `po`, `dev` — aligned with Tymio hub roles; shipped in the npm tarball.
+- **`tymio-mcp persona list`** and **`tymio-mcp persona <id>`** — print persona Markdown to stdout (or list ids).
+- **`TYMIO_MCP_PERSONA`** — optional env on the stdio process; appends the selected persona to MCP server **`instructions`** after the main agent guide (`hub` aliases `workspace`). Invalid values log a stderr warning and fall back to the base guide only.
+- **Startup stderr hint** — when a valid persona is set, reminds that instructions include it and how to print the prompt (`tymio-mcp persona <id>`).
+- **Agent guidance** — `TYMIO_MCP_CLI_AGENT_GUIDANCE.md` updated with persona usage; `README.md` and help text document commands and env.
+
+## 1.0.1
+
+Prior release (OAuth proxy, API-key REST subset, `tymio-mcp instructions`, login/logout).

package/README.md

@@ -1,84 +1,194 @@
-# 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
-```
+### Bundled agent personas (PM / PO / DEV)
 
-## Build and run
+The package ships Markdown prompts in **`personas/`** (aligned with Cursor Skills in the monorepo).
 
-```bash
-npm run mcp:build
-npm run mcp:start
+| Mechanism | What it does |
+|-----------|----------------|
+| **`tymio-mcp persona list`** | Lists persona ids and usage |
+| **`tymio-mcp persona pm`** (or `po`, `dev`, `workspace`) | Prints that prompt to **stdout** (pipe into docs or paste into a chat) |
+| **`TYMIO_MCP_PERSONA=pm`** on the `tymio-mcp` process | **Appends** the same Markdown to MCP server **`instructions`** after the main CLI guide — steers the model for clients that honor instructions (no Skills required). Use `hub` as an alias for `workspace`. |
+
+Example Cursor stdio config with a Product Owner bias:
+
+```json
+{
+  "mcpServers": {
+    "tymio-po": {
+      "command": "tymio-mcp",
+      "args": [],
+      "env": { "TYMIO_MCP_PERSONA": "po" }
+    }
+  }
+}
 ```
 
-Or from `mcp/`: `npm run build` && `npm run start`. The process uses **stdio**; it is spawned by the MCP client, not run interactively.
+### OAuth callback port
 
-## Cursor (stdio)
+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.
 
-With a global install, point the client at the `tymio-mcp` binary:
+### 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)
+
+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.
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `DRD_API_BASE_URL` | `https://tymio.app` | Hub **origin** (no `/mcp`) |
+| `DRD_API_KEY` / `API_KEY` | — | Bearer key (server `API_KEY`) |
+
+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 instructions` / `guide` | Print full agent Markdown (same as MCP `instructions` base) |
+| `tymio-mcp persona list` | Bundled persona ids (`pm`, `po`, `dev`, `workspace`) |
+| `tymio-mcp persona <id>` | Print one persona Markdown to stdout |
+| `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,100 @@
+# 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.
+6. **Bundled agent personas (PM / PO / DEV / workspace):** optional Markdown prompts ship with the package under `personas/`. **Print a prompt:** `tymio-mcp persona pm` (or `po`, `dev`, `workspace`). **Embed in MCP `instructions`:** set `TYMIO_MCP_PERSONA=pm` (same ids; `hub` aliases `workspace`) on the `tymio-mcp` process — the stdio server appends that persona after this guide so clients that honor `instructions` steer the model without Cursor Skills. **List ids:** `tymio-mcp persona list`.
+
+---
+
+## 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.d.ts

@@ -1,6 +1,8 @@
 /**
  * Minimal Tymio hub API client for the stdio MCP server. Uses DRD_API_BASE_URL and DRD_API_KEY from env.
  */
+export declare function setApiKeyBridgeTenantId(tenantId: string): void;
+export declare function clearApiKeyBridgeTenant(): void;
 /** JSON-friendly body; plain objects are stringified. */
 export type DrdFetchInit = Omit<RequestInit, "body"> & {
     body?: string | Record<string, unknown>;

package/dist/api.js

@@ -1,10 +1,22 @@
 /**
  * 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 ?? "";
+/** Set by API-key stdio after resolving slug → tenant id (never send cross-tenant requests). */
+let bridgeTenantHeaders = {};
+export function setApiKeyBridgeTenantId(tenantId) {
+    bridgeTenantHeaders = { "X-Tenant-Id": tenantId };
+}
+export function clearApiKeyBridgeTenant() {
+    bridgeTenantHeaders = {};
+}
 function headers() {
-    const h = { "Content-Type": "application/json" };
+    const h = {
+        "Content-Type": "application/json",
+        ...bridgeTenantHeaders
+    };
     if (apiKey)
         h["Authorization"] = `Bearer ${apiKey}`;
     return h;

package/dist/apiKeyStdio.d.ts

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