{"feedbackReporting":"How to send feedback to Tymio (bugs, ideas, product improvements):\n\n1. In the Tymio web app, switch to the **Tymio** workspace (reserved product hub) using the workspace switcher, or open the sign-in path for that workspace: `https://tymio.app/t/tymio`.\n2. Connect the **Tymio MCP** from that workspace context (same OAuth/API flow you use here) to submit feedback, bugs, and suggestions—those tools are exposed from the Tymio hub workspace.\n3. If MCP is not available, use your team’s normal support channel or contact your Tymio administrator.\n\nWhen assisting users in any customer workspace, offer to help them report issues upstream using the steps above so the Tymio team can act on them.","supportedUiLocales":{"codes":["en","cs","sk","uk","pl"],"locales":[{"code":"en","name":"English","ogLocale":"en_US"},{"code":"cs","name":"Czech","ogLocale":"cs_CZ"},{"code":"sk","name":"Slovak","ogLocale":"sk_SK"},{"code":"uk","name":"Ukrainian","ogLocale":"uk_UA"},{"code":"pl","name":"Polish","ogLocale":"pl_PL"}],"workspaceNote":"The SPA ships these interface languages (ISO 639-1 style codes: en, cs, sk, uk, pl). Workspace owners or admins may restrict the in-app language picker via Tenant.settings.enabledLocales; guests pick a language on public pages (stored in localStorage)."},"scopeReference":{"pattern":"<workspace-slug>/<product-slug>","purpose":"Stable human- and agent-readable label for which hub workspace and product line you mean. Not an access-control boundary: initiatives may omit a product; agents can create cross-product or non-product work inside the same workspace.","workspaceUrls":"Humans often open /t/<workspace-slug> on this host.","dataSources":"Workspace slug is on the Tenant; product slug is on each Product row (see MCP tymio_meta / tymio_list_products and REST GET /api/meta, /api/products)."},"tymioMcpCliAgentGuidanceMarkdown":"# Tymio MCP and `@tymio/mcp-server` — guidance for autonomous agents\n\n**Published package:** [npmjs.com/package/@tymio/mcp-server](https://www.npmjs.com/package/@tymio/mcp-server) — install with `npm install -g @tymio/mcp-server` or `npx @tymio/mcp-server`. Release history: `CHANGELOG.md` next to this file in the monorepo.\n\n## Critical — read before advising the user\n\n0. **Autonomous agents — OAuth before tools:** Establish a **signed-in MCP session** first (`mcp_auth` with `{}` if exposed, else IDE **Connect / Sign in**). **`POST …/mcp`** (root) exposes **only** **`tymio_list_my_workspaces`** and **`tymio_mcp_routing_guide`** — not backlog tools. For the **full** workspace-scoped **`tymio_*`** tool surface (backlog CRUD, atlas, briefs), the client must use **`POST …/t/<workspace-slug>/mcp`**. **Verify** with **`tymio_health`** / **`tymio_get_agent_brief`** on a **workspace** URL only.\n1. **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.\n2. **Normal connection = OAuth**, not a personal secret from the UI:\n   - **Remote MCP in the IDE:** **`https://tymio.app/mcp`** = **discovery only** (list workspaces + routing guide). **`https://tymio.app/t/<workspace-slug>/mcp`** = **full** workspace MCP (`tymio_*`, atlas, brief, …). Same **Connect / Sign in** OAuth flow for both; trim **no trailing spaces** in Server URL. Use your deployment origin when not on production. **No API key to paste.**\n   - **Stdio npm package (default):** install `@tymio/mcp-server`, run `tymio-mcp login` with **`TYMIO_MCP_URL`** / URL = **`…/t/<slug>/mcp`** for full tools. Root **`…/mcp`** only proxies two discovery tools. Configure the MCP client to run `tymio-mcp` **without** setting `TYMIO_API_KEY` (legacy `DRD_API_KEY`) or `API_KEY` unless you want API-key mode.\n3. **`TYMIO_API_KEY` / `API_KEY` on the stdio process** (legacy `DRD_API_KEY`) 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).\n4. **Default vs API-key stdio:** If `TYMIO_API_KEY` (legacy `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`).\n5. **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.\n6. **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`.\n\n7. **One user, many workspaces:** Same **Google** user, many **Workspaces**. Use **`tymio_list_my_workspaces`** on root **`…/mcp`** to get each **`…/t/<slug>/mcp`** URL. **Do not** reuse backlog **IDs** across workspaces. **State the workspace** when reporting hub changes.\n\n8. **Discovery-only session → per-project MCP config:** If the client is connected to root **`…/mcp`**, call **`tymio_list_my_workspaces`**, then **`tymio_mcp_routing_guide`** for copy-paste JSON. **Create** (if you have repo write access) **`.cursor/mcp.json`** (Cursor) or **`.mcp.json`** (Claude Code) at the **repository root** with **`mcpServers.*.url`** = **`…/t/<slug>/mcp`**, or **explain** the exact path + JSON to the user. **Restart / reload MCP** after saving. Root **`…/mcp`** alone does not expose backlog CRUD — the workspace URL is required for the full **`tymio_*`** hub tool surface.\n9. **Cursor Cloud Agents:** Desktop/IDE OAuth does **not** authenticate Cloud Agents. On **https://cursor.com/agents** add a **custom HTTP** MCP server with **`…/t/<slug>/mcp`**, then **Connect / Sign in**. Do **not** tell users to paste **`TYMIO_API_KEY`** into Cloud Agent Secrets for this path (that env var is a deployment operator secret). Follow-up auth (workspace PATs, device-code, service keys) is tracked on hub epic **Cloud and headless agent auth**.\n\n---\n\n## What `@tymio/mcp-server` is\n\n- **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).\n- **With `TYMIO_API_KEY` (legacy `DRD_API_KEY`) or `API_KEY` set:** A **REST/API-key** stdio server with a **smaller, fixed tool set** (good for CI/scripts).\n\n---\n\n## One-time setup (OAuth, stdio package)\n\n1. Install: `npm install -g @tymio/mcp-server` (or run a built `dist/index.js` via `node`).\n2. Run: `tymio-mcp login` — browser opens; complete Google sign-in for Tymio.\n3. Tokens and OAuth client metadata live under the user config directory (e.g. Linux: `~/.config/tymio-mcp`, macOS: `~/Library/Application Support/tymio-mcp`).\n4. **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.\n\n---\n\n## Cursor / IDE (stdio, OAuth — recommended for this package)\n\nAdd an MCP server that runs the binary **without** `TYMIO_API_KEY` / `API_KEY` (legacy `DRD_API_KEY`):\n\n```json\n{\n  \"mcpServers\": {\n    \"tymio\": {\n      \"command\": \"tymio-mcp\",\n      \"args\": []\n    }\n  }\n}\n```\n\nIf `tymio-mcp` is not on `PATH`, use `node` with an absolute path to `dist/index.js`.\n\n---\n\n## Alternative: remote MCP URL (no npm CLI)\n\nIf the host supports **URL** transport, point at the hub (OAuth handled by the IDE). Use **`/mcp`** (follows the user’s **currently active** workspace — risky if they use **multiple** workspaces) **or** **`/t/<workspace-slug>/mcp`** to **pin** one workspace (recommended when the user names a workspace or juggles several orgs):\n\n```json\n{\n  \"mcpServers\": {\n    \"tymio\": {\n      \"url\": \"https://tymio.app/mcp\"\n    },\n    \"tymio-acme\": {\n      \"url\": \"https://tymio.app/t/acme/mcp\"\n    }\n  }\n}\n```\n\nReplace the host and slug when not using production. **Pattern:** add **`tymio-<slug>`** per workspace so the agent and user always know which tenant a server targets.\n\n---\n\n## API-key mode (REST subset, intentional)\n\nSet `TYMIO_API_KEY` (or legacy `DRD_API_KEY`, or `API_KEY`) and optionally `TYMIO_API_BASE_URL` (legacy `DRD_API_BASE_URL`, default `https://tymio.app`). Then `tymio-mcp` uses the REST bridge, **not** OAuth to the hosted MCP tool list.\n\n---\n\n## Environment reference\n\n| Variable | Default | Purpose |\n|----------|---------|---------|\n| `TYMIO_MCP_URL` | `https://tymio.app/mcp` | Hosted MCP URL for OAuth proxy + `login` (may be `https://host/t/<slug>/mcp`; if the value has no `/mcp` suffix, the CLI appends it) |\n| `TYMIO_OAUTH_PORT` | `19876` | Loopback port for login callback |\n| `TYMIO_OAUTH_LOGIN_TIMEOUT_MS` | unset | If set (positive ms), `tymio-mcp login` fails after that wait instead of hanging forever if the user never completes OAuth |\n| `TYMIO_MCP_QUIET` | unset | If set, suppress stderr hints when starting stdio |\n| `TYMIO_API_KEY` / `API_KEY` | unset | If set → API-key REST bridge (subset), not OAuth proxy (legacy `DRD_API_KEY`) |\n| `TYMIO_API_BASE_URL` | `https://tymio.app` | Hub origin for API-key bridge (legacy `DRD_API_BASE_URL`) |\n\n---\n\n## Troubleshooting\n\n- **401 / not signed in (stdio OAuth):** Run `tymio-mcp login` again.\n- **User asks where to copy MCP API key:** Explain there is **no** such key in the UI; use **remote `/mcp` or `/t/<slug>/mcp` + OAuth** or **`tymio-mcp login`**.\n- **Port in use on login:** Change `TYMIO_OAUTH_PORT` and re-run `login` (redirect URI must stay consistent).\n- **Login waits forever:** The user closed the browser without finishing OAuth — set `TYMIO_OAUTH_LOGIN_TIMEOUT_MS` (e.g. `900000` for 15 minutes) so the CLI exits with a clear error, or press Ctrl+C.\n- **Cursor: no `tymio_*` tools / `workspaceSlug` rejected:** Server URL is probably root **`…/mcp`**. Set **`…/t/<slug>/mcp`**, trim spaces, **disconnect + re-auth**. Use **`tymio_list_my_workspaces`** on discovery to list slugs.\n- **Cursor Cloud Agent unauthenticated:** MCP was configured only in the IDE. Add **`…/t/<slug>/mcp`** on **https://cursor.com/agents** and complete Connect there.\n- **Help:** `tymio-mcp help` — **full guide:** `tymio-mcp instructions`\n\n---\n\n## Machine-readable pointers\n\n- **JSON (public):** `GET https://tymio.app/api/mcp/agent-context` — includes `tymioMcpCliAgentGuidanceMarkdown` (this file’s contents when the server can read it from disk).\n- **Markdown site summary:** `https://tymio.app/llms.txt`\n- **Repository:** `mcp/README.md`, `docs/HUB.md` §6, `docs/CODING_AGENT_HANDOFF_TYMIO_APP.md`\n\n## Workspace atlas (full MCP only)\n\nWhen using **remote** `…/mcp`, remote `…/t/<slug>/mcp`, or stdio **without** `TYMIO_API_KEY`/`API_KEY` (OAuth proxy; legacy `DRD_API_KEY`), the hub may expose **`tymio_get_workspace_atlas`**, **`tymio_search_workspace_objects`**, **`tymio_get_workspace_object`**, **`tymio_explain_workspace_object`**, and **`tymio_rebuild_workspace_atlas`**. These read a **compiled JSON** backlog snapshot for the active workspace — complementary to **`tymio_get_agent_brief`** (capabilities). They are **not** part of the API-key REST stdio subset.\n\n**Public article:** `https://tymio.app/wiki/workspace-atlas` (raw: `/wiki/articles/workspace-atlas.md`). Operators: persistent **`WORKSPACE_ATLAS_DATA_DIR`** on ephemeral hosts if you want the atlas to survive process restarts without an explicit rebuild.\n","tymioMcpCliPackage":"@tymio/mcp-server","tymioMcpCliBinary":"tymio-mcp","tymioMcpCliInstructionsCommand":"tymio-mcp instructions","tymioMcpNoUserSettingsApiKey":true}