Tymio MCP CLI (@tymio/mcp-server)

Canonical Markdown for coding agents: 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).

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 or …/t/<workspace-slug>/mcp via TYMIO_MCP_URL) 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). Workspace atlas MCP tools (tymio_get_workspace_atlas, etc.) are hub-only — use OAuth stdio or remote /mcp / /t/.../mcp for those; see client/public/wiki/articles/workspace-atlas.md.

Quick start (OAuth, production)

1. Install the CLI (from npm when published, or npm install -g /path/to/repo/mcp).

2. In a terminal:

   tymio-mcp login

   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).

3. Point your MCP client at stdio without setting DRD_API_KEY:

   {
     "mcpServers": {
       "tymio": {
         "command": "tymio-mcp",
         "args": []
       }
     }
   }

4. Optional: tymio-mcp logout removes saved OAuth files.

Agents / IDE: MCP clients that support server instructions 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.

Bundled agent personas (PM / PO / DEV)

The package ships Markdown prompts in personas/ (aligned with Cursor Skills in the monorepo).

| 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:

{
  "mcpServers": {
    "tymio-po": {
      "command": "tymio-mcp",
      "args": [],
      "env": { "TYMIO_MCP_PERSONA": "po" }
    }
  }
}

OAuth callback port

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.

Hub URL

| Variable | Default | Purpose | |----------|---------|---------| | TYMIO_MCP_URL | https://tymio.app/mcp | Hosted MCP endpoint for OAuth proxy + login (may be https://host/t/<slug>/mcp; CLI appends /mcp if omitted) |

API-key mode (REST subset, CI / automation)

If TYMIO_API_KEY (legacy 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 | |----------|---------|---------| | TYMIO_API_BASE_URL | https://tymio.app | Hub origin (no /mcp; legacy DRD_API_BASE_URL) | | TYMIO_API_KEY / API_KEY | — | Bearer key (server API_KEY; legacy DRD_API_KEY) |

Example:

{
  "mcpServers": {
    "tymio-api-key": {
      "command": "tymio-mcp",
      "args": [],
      "env": {
        "TYMIO_API_KEY": "your-key",
        "TYMIO_API_BASE_URL": "https://tymio.app"
      }
    }
  }
}

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 doctor | Diagnostics: version, Node, OAuth files, masked env hints (stderr) | | tymio-mcp bootstrap [--help] | Preview onboarding steps; full client merge tracked in repo TYMIO_BOOTSTRAP.md | | tymio-mcp help | Usage |

Install globally (npm)

The package is published on the public registry: npmjs.com/package/@tymio/mcp-server. Current release line: 2.0.1 (see CHANGELOG.md for notes).

npm install -g @tymio/mcp-server

Or run without a global install:

npx @tymio/mcp-server help

Maintainers — publish a new version (from monorepo root, after bumping mcp/package.json and updating CHANGELOG.md):

npm login
npm publish -w mcp --access public

Or install from a local clone (development):

npm install -g /absolute/path/to/proproman/mcp

Build and run (monorepo)

npm run mcp:build
npm run mcp:start

From mcp/, run unit tests (uses vitest.config.ts in this folder):

npm test

From the repo root, use:

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:

{
  "mcpServers": {
    "tymio": {
      "url": "https://tymio.app/mcp"
    }
  }
}

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:

npm run test --workspace mcp && npm run build --workspace mcp && npm publish -w mcp --access public --dry-run

Architecture reference

Hosted MCP, OAuth, and Google callback URLs: 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.