@tymio/mcp-server 1.0.0 → 2.0.0

package/dist/apiKeyStdio.js

@@ -0,0 +1,332 @@
+/**
+ * REST/API-key stdio bridge (subset of hub tools). Set DRD_API_BASE_URL + DRD_API_KEY (or API_KEY).
+ * Requires TYMIO_WORKSPACE_SLUG or DRD_WORKSPACE_SLUG (unless TYMIO_MCP_SKIP_WORKSPACE_PINNING=1 for tests).
+ */
+import { z } from "zod";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { resolveTenantIdForWorkspaceSlug } from "./apiKeyTenantResolve.js";
+import { drdFetch, drdFetchText, getBaseUrl, hasApiKey, setApiKeyBridgeTenantId } from "./api.js";
+import { getMcpServerInstructions } from "./persona.js";
+import { toolTextWithFeedback } from "./mcpFeedbackFooter.js";
+import { writeStdioStartupHint } from "./stdioHints.js";
+import { assertToolArgsMatchPinnedWorkspace, omitWorkspaceSlug, readPinnedWorkspaceSlugForStdio, WORKSPACE_SLUG_ZOD } from "./workspaceSlug.js";
+export async function runApiKeyStdio() {
+    writeStdioStartupHint("api-key");
+    const pinnedSlug = readPinnedWorkspaceSlugForStdio();
+    if (pinnedSlug) {
+        try {
+            const tenantId = await resolveTenantIdForWorkspaceSlug(pinnedSlug);
+            setApiKeyBridgeTenantId(tenantId);
+        }
+        catch (e) {
+            process.stderr.write(`[tymio-mcp] API-key bridge: cannot resolve workspace: ${e}\n`);
+            process.exit(1);
+        }
+    }
+    const server = new McpServer({ name: "tymio-hub", version: "1.0.0" }, { instructions: getMcpServerInstructions() });
+    async function textContent(text) {
+        return toolTextWithFeedback(getBaseUrl(), text);
+    }
+    function assertPin(args, tool) {
+        if (pinnedSlug)
+            assertToolArgsMatchPinnedWorkspace(args, pinnedSlug, tool);
+    }
+    const ws = { workspaceSlug: WORKSPACE_SLUG_ZOD };
+    server.registerTool("drd_health", {
+        title: "Tymio API health check",
+        description: "Check if the Tymio hub API is reachable. Requires workspaceSlug (must match server pin).",
+        inputSchema: z.object(ws)
+    }, async (args) => {
+        assertPin(args, "drd_health");
+        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(ws)
+    }, async (args) => {
+        assertPin(args, "drd_meta");
+        const data = await drdFetch("/api/meta");
+        return textContent(JSON.stringify(data, null, 2));
+    });
+    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()
+    })
+        .extend(ws);
+    server.registerTool("drd_list_initiatives", {
+        title: "List initiatives",
+        description: "List initiatives with optional filters: domainId, ownerId, horizon, priority, isGap.",
+        inputSchema: listInitiativesSchema
+    }, async (args) => {
+        assertPin(args, "drd_list_initiatives");
+        const { workspaceSlug: _w, ...filters } = args;
+        const params = new URLSearchParams();
+        if (filters.domainId)
+            params.set("domainId", filters.domainId);
+        if (filters.ownerId)
+            params.set("ownerId", filters.ownerId);
+        if (filters.horizon)
+            params.set("horizon", filters.horizon);
+        if (filters.priority)
+            params.set("priority", filters.priority);
+        if (filters.isGap !== undefined)
+            params.set("isGap", String(filters.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") }).extend(ws)
+    }, async (args) => {
+        assertPin(args, "drd_get_initiative");
+        const { id } = omitWorkspaceSlug(args);
+        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()
+        })
+            .extend(ws)
+    }, async (args) => {
+        assertPin(args, "drd_create_initiative");
+        const body = omitWorkspaceSlug(args);
+        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()
+        })
+            .extend(ws)
+    }, async (args) => {
+        assertPin(args, "drd_update_initiative");
+        const { id, ...body } = omitWorkspaceSlug(args);
+        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() }).extend(ws)
+    }, async (args) => {
+        assertPin(args, "drd_delete_initiative");
+        const { id } = omitWorkspaceSlug(args);
+        await drdFetch(`/api/initiatives/${id}`, { method: "DELETE" });
+        return textContent(JSON.stringify({ ok: true }));
+    });
+    server.registerTool("drd_list_domains", {
+        title: "List domains",
+        description: "List all domains.",
+        inputSchema: z.object(ws)
+    }, async (args) => {
+        assertPin(args, "drd_list_domains");
+        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()
+        })
+            .extend(ws)
+    }, async (args) => {
+        assertPin(args, "drd_create_domain");
+        const body = omitWorkspaceSlug(args);
+        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(ws)
+    }, async (args) => {
+        assertPin(args, "drd_list_products");
+        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(ws)
+    }, async (args) => {
+        assertPin(args, "drd_list_personas");
+        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(ws)
+    }, async (args) => {
+        assertPin(args, "drd_list_accounts");
+        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(ws)
+    }, async (args) => {
+        assertPin(args, "drd_list_partners");
+        const data = await drdFetch("/api/partners");
+        return textContent(JSON.stringify(data.partners, null, 2));
+    });
+    server.registerTool("drd_list_kpis", {
+        title: "List KPIs",
+        description: "List all initiative KPIs with their initiative context (title, domain, owner).",
+        inputSchema: z.object(ws)
+    }, async (args) => {
+        assertPin(args, "drd_list_kpis");
+        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(ws)
+    }, async (args) => {
+        assertPin(args, "drd_list_milestones");
+        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(ws)
+    }, async (args) => {
+        assertPin(args, "drd_list_demands");
+        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(ws)
+    }, async (args) => {
+        assertPin(args, "drd_list_revenue_streams");
+        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(ws)
+    }, async (args) => {
+        assertPin(args, "tymio_get_coding_agent_guide");
+        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")
+        })
+            .extend(ws)
+    }, async (args) => {
+        assertPin(args, "tymio_get_agent_brief");
+        const { mode, format } = omitWorkspaceSlug(args);
+        const params = new URLSearchParams({ mode, format });
+        const q = params.toString();
+        const raw = await drdFetchText(`/api/ontology/brief?${q}`);
+        if (format === "json") {
+            try {
+                const parsed = JSON.parse(raw);
+                return textContent(JSON.stringify(parsed, null, 2));
+            }
+            catch {
+                return textContent(raw);
+            }
+        }
+        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() }).extend(ws)
+    }, async (args) => {
+        assertPin(args, "tymio_list_capabilities");
+        const { status } = omitWorkspaceSlug(args);
+        const params = new URLSearchParams();
+        if (status)
+            params.set("status", 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() })
+            .extend(ws)
+    }, async (args) => {
+        assertPin(args, "tymio_get_capability");
+        const { id, slug } = omitWorkspaceSlug(args);
+        if (id) {
+            const data = await drdFetch(`/api/ontology/capabilities/${id}`);
+            return textContent(JSON.stringify(data, null, 2));
+        }
+        if (slug) {
+            const data = await drdFetch(`/api/ontology/capabilities/by-slug/${encodeURIComponent(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/apiKeyTenantResolve.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Resolve workspace slug to tenant id for API-key bridge; verifies ACTIVE membership for the API key user.
+ */
+export declare function resolveTenantIdForWorkspaceSlug(expectedSlug: string): Promise<string>;

package/dist/apiKeyTenantResolve.js

@@ -0,0 +1,17 @@
+import { drdFetch } from "./api.js";
+import { isValidWorkspaceSlugFormat } from "./workspaceSlug.js";
+/**
+ * Resolve workspace slug to tenant id for API-key bridge; verifies ACTIVE membership for the API key user.
+ */
+export async function resolveTenantIdForWorkspaceSlug(expectedSlug) {
+    if (!isValidWorkspaceSlugFormat(expectedSlug)) {
+        throw new Error(`Invalid workspace slug: ${JSON.stringify(expectedSlug)}`);
+    }
+    const want = expectedSlug.toLowerCase();
+    const data = await drdFetch("/api/me/tenants");
+    const row = data.tenants.find((m) => m.tenant.slug.toLowerCase() === want && m.tenant.status === "ACTIVE");
+    if (!row) {
+        throw new Error(`API key user has no ACTIVE membership for workspace slug "${expectedSlug}". Check TYMIO_WORKSPACE_SLUG and hub memberships.`);
+    }
+    return row.tenant.id;
+}

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,40 @@
+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";
+import { runPersonaCli } from "./persona.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 (args[0] === "persona") {
+        process.exitCode = runPersonaCli(args.slice(1));
+        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 persona list       Bundled PM/PO/DEV/workspace prompts (see also TYMIO_MCP_PERSONA)\n  tymio-mcp persona <id>       Print one persona Markdown to stdout (pm | po | dev | workspace)\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  TYMIO_WORKSPACE_SLUG   Required for stdio (or DRD_WORKSPACE_SLUG): hub workspace slug this process is pinned to; every tool call must use the same slug (tests: TYMIO_MCP_SKIP_WORKSPACE_PINNING=1)\n  TYMIO_MCP_PERSONA      Optional: pm | po | dev | workspace (hub aliases workspace) \u2014 appended to MCP server instructions\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;

package/dist/cliMessages.js

@@ -0,0 +1,57 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const GUIDANCE_FILE = "TYMIO_MCP_CLI_AGENT_GUIDANCE.md";
+function loadAgentGuidanceMarkdown() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const packaged = path.join(here, "..", GUIDANCE_FILE);
+    try {
+        if (existsSync(packaged))
+            return readFileSync(packaged, "utf8");
+    }
+    catch {
+        /* fall through */
+    }
+    return [
+        "# Tymio MCP CLI",
+        "",
+        "The guidance file `TYMIO_MCP_CLI_AGENT_GUIDANCE.md` was not found next to this package (expected beside `dist/`). Reinstall `@tymio/mcp-server` or run from the repository checkout.",
+        "",
+        "## Critical (read before advising the user)",
+        "",
+        "- **No per-user MCP API key** exists in Tymio Settings, Profile, or Account. Do not tell users to copy one from the UI.",
+        "- **OAuth:** remote MCP URL `https://tymio.app/mcp` (or your host) in the IDE, or install `@tymio/mcp-server` and run `tymio-mcp login` for stdio **without** `DRD_API_KEY`/`API_KEY` on that process unless you want API-key mode.",
+        "- **`DRD_API_KEY`/`API_KEY`** on the stdio process is the **server deployment** automation secret, not a personal user key.",
+        "",
+        "After fixing the install: `tymio-mcp instructions`",
+    ].join("\n");
+}
+/** Short usage (stderr) — keep in sync with guidance file for agents. */
+export const HELP_SUMMARY = `Tymio MCP CLI (@tymio/mcp-server)
+
+Commands:
+  tymio-mcp                    Start stdio MCP (default: OAuth → hosted Tymio MCP)
+  tymio-mcp login [url]        Sign in with Google (browser). Saves tokens locally.
+  tymio-mcp logout             Delete saved OAuth client + tokens
+  tymio-mcp instructions       Full setup text for humans & coding agents (print this)
+  tymio-mcp persona list       Bundled PM/PO/DEV/workspace prompts (see also TYMIO_MCP_PERSONA)
+  tymio-mcp persona <id>       Print one persona Markdown to stdout (pm | po | dev | workspace)
+  tymio-mcp help               This summary
+
+Environment:
+  TYMIO_MCP_URL          Hosted MCP URL (default https://tymio.app/mcp)
+  TYMIO_OAUTH_PORT       Loopback port for login callback (default 19876)
+  TYMIO_MCP_QUIET        If set, suppress stderr hints when starting stdio
+  TYMIO_WORKSPACE_SLUG   Required for stdio (or DRD_WORKSPACE_SLUG): hub workspace slug this process is pinned to; every tool call must use the same slug (tests: TYMIO_MCP_SKIP_WORKSPACE_PINNING=1)
+  TYMIO_MCP_PERSONA      Optional: pm | po | dev | workspace (hub aliases workspace) — appended to MCP server instructions
+  DRD_API_KEY / API_KEY  If set → API-key REST tool bridge (subset), not OAuth proxy
+  DRD_API_BASE_URL       Hub origin for API-key bridge (default https://tymio.app)
+
+Critical for agents: There is NO MCP API key in Tymio user Settings — use OAuth (remote /mcp URL or tymio-mcp login).
+Tip: Run  tymio-mcp instructions  for the full Markdown guide, Cursor JSON, and troubleshooting.
+`;
+/**
+ * Long-form instructions for coding agents and operators (Markdown).
+ * Loaded from `TYMIO_MCP_CLI_AGENT_GUIDANCE.md` beside the installed package / dist output.
+ */
+export const AGENT_INSTRUCTIONS = loadAgentGuidanceMarkdown();

package/dist/configPaths.d.ts

@@ -0,0 +1,6 @@
+/** XDG-style config directory for OAuth tokens and dynamic client registration. */
+export declare function getTymioConfigDir(): string;
+export declare function ensureConfigDir(): string;
+export declare function defaultMcpUrl(): URL;
+/** Loopback redirect port for OAuth `login` (must stay stable across runs for dynamic client registration). */
+export declare function defaultOAuthRedirectUrl(): URL;

package/dist/configPaths.js

@@ -0,0 +1,32 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+/** XDG-style config directory for OAuth tokens and dynamic client registration. */
+export function getTymioConfigDir() {
+    const base = process.env.XDG_CONFIG_HOME ?? (process.platform === "darwin" ? path.join(os.homedir(), "Library", "Application Support") : path.join(os.homedir(), ".config"));
+    return path.join(base, "tymio-mcp");
+}
+export function ensureConfigDir() {
+    const dir = getTymioConfigDir();
+    fs.mkdirSync(dir, { recursive: true });
+    return dir;
+}
+export function defaultMcpUrl() {
+    const raw = (process.env.TYMIO_MCP_URL ?? "https://tymio.app/mcp").trim();
+    const fallback = "https://tymio.app/mcp";
+    const base = raw.length > 0 ? raw : fallback;
+    const trimmed = base.replace(/\/+$/, "");
+    const withMcp = trimmed.endsWith("/mcp") ? trimmed : `${trimmed}/mcp`;
+    return new URL(withMcp);
+}
+/** Loopback redirect port for OAuth `login` (must stay stable across runs for dynamic client registration). */
+export function defaultOAuthRedirectUrl() {
+    const raw = process.env.TYMIO_OAUTH_PORT;
+    let port = 19876;
+    if (raw !== undefined && raw.trim() !== "") {
+        const n = Number(raw);
+        if (Number.isInteger(n) && n >= 1 && n <= 65535)
+            port = n;
+    }
+    return new URL(`http://127.0.0.1:${port}/callback`);
+}

package/dist/fileOAuthProvider.d.ts

@@ -0,0 +1,27 @@
+import type { OAuthClientProvider, OAuthDiscoveryState } from "@modelcontextprotocol/sdk/client/auth.js";
+import type { OAuthClientInformationMixed, OAuthClientMetadata, OAuthTokens } from "@modelcontextprotocol/sdk/shared/auth.js";
+/**
+ * Persists MCP OAuth dynamic registration + tokens for the Tymio hub Streamable HTTP endpoint.
+ */
+export declare class FileOAuthProvider implements OAuthClientProvider {
+    private readonly dir;
+    private readonly redirect;
+    private codeVerifierValue?;
+    private oauthState?;
+    constructor(redirectUrl: URL);
+    get redirectUrl(): URL;
+    get clientMetadata(): OAuthClientMetadata;
+    clientInformation(): OAuthClientInformationMixed | undefined;
+    saveClientInformation(clientInformation: OAuthClientInformationMixed): void;
+    tokens(): OAuthTokens | undefined;
+    saveTokens(tokens: OAuthTokens): void;
+    saveCodeVerifier(codeVerifier: string): void;
+    codeVerifier(): string;
+    state(): Promise<string>;
+    clearLoginSession(): void;
+    redirectToAuthorization(authorizationUrl: URL): void;
+    saveDiscoveryState(state: OAuthDiscoveryState): Promise<void>;
+    discoveryState(): Promise<OAuthDiscoveryState | undefined>;
+    invalidateCredentials(scope: "all" | "client" | "tokens" | "verifier" | "discovery"): Promise<void>;
+}
+export declare function removeAllOAuthFiles(): void;

package/dist/fileOAuthProvider.js

@@ -0,0 +1,127 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { randomBytes } from "node:crypto";
+import { ensureConfigDir, getTymioConfigDir } from "./configPaths.js";
+const CLIENT_FILE = "oauth-client.json";
+const TOKENS_FILE = "oauth-tokens.json";
+const DISCOVERY_FILE = "oauth-discovery.json";
+function readJson(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function writeJson(file, data) {
+    fs.writeFileSync(file, JSON.stringify(data, null, 2), "utf8");
+}
+function openUrlInBrowser(url) {
+    if (process.platform === "darwin") {
+        spawn("open", [url], { detached: true, stdio: "ignore" }).unref();
+    }
+    else if (process.platform === "win32") {
+        spawn("cmd", ["/c", "start", "", url], { detached: true, stdio: "ignore" }).unref();
+    }
+    else {
+        spawn("xdg-open", [url], { detached: true, stdio: "ignore" }).unref();
+    }
+}
+/**
+ * Persists MCP OAuth dynamic registration + tokens for the Tymio hub Streamable HTTP endpoint.
+ */
+export class FileOAuthProvider {
+    dir;
+    redirect;
+    codeVerifierValue;
+    oauthState;
+    constructor(redirectUrl) {
+        this.dir = ensureConfigDir();
+        this.redirect = redirectUrl;
+    }
+    get redirectUrl() {
+        return this.redirect;
+    }
+    get clientMetadata() {
+        return {
+            redirect_uris: [this.redirect.toString()],
+            client_name: "Tymio MCP CLI",
+            grant_types: ["authorization_code", "refresh_token"],
+            response_types: ["code"],
+            token_endpoint_auth_method: "none",
+            scope: "mcp:tools"
+        };
+    }
+    clientInformation() {
+        return readJson(path.join(this.dir, CLIENT_FILE));
+    }
+    saveClientInformation(clientInformation) {
+        writeJson(path.join(this.dir, CLIENT_FILE), clientInformation);
+    }
+    tokens() {
+        return readJson(path.join(this.dir, TOKENS_FILE));
+    }
+    saveTokens(tokens) {
+        writeJson(path.join(this.dir, TOKENS_FILE), tokens);
+    }
+    saveCodeVerifier(codeVerifier) {
+        this.codeVerifierValue = codeVerifier;
+    }
+    codeVerifier() {
+        if (!this.codeVerifierValue)
+            throw new Error("Missing PKCE code verifier");
+        return this.codeVerifierValue;
+    }
+    async state() {
+        if (!this.oauthState) {
+            this.oauthState = randomBytes(16).toString("hex");
+        }
+        return this.oauthState;
+    }
+    clearLoginSession() {
+        this.codeVerifierValue = undefined;
+        this.oauthState = undefined;
+    }
+    redirectToAuthorization(authorizationUrl) {
+        process.stderr.write(`Opening browser to sign in to Tymio…\n${authorizationUrl.toString()}\n`);
+        openUrlInBrowser(authorizationUrl.toString());
+    }
+    async saveDiscoveryState(state) {
+        writeJson(path.join(this.dir, DISCOVERY_FILE), state);
+    }
+    async discoveryState() {
+        return readJson(path.join(this.dir, DISCOVERY_FILE));
+    }
+    async invalidateCredentials(scope) {
+        const base = getTymioConfigDir();
+        const rm = (f) => {
+            try {
+                fs.unlinkSync(path.join(base, f));
+            }
+            catch {
+                /* ignore */
+            }
+        };
+        if (scope === "all" || scope === "tokens")
+            rm(TOKENS_FILE);
+        if (scope === "all" || scope === "client")
+            rm(CLIENT_FILE);
+        if (scope === "all" || scope === "discovery")
+            rm(DISCOVERY_FILE);
+        if (scope === "all" || scope === "verifier") {
+            this.codeVerifierValue = undefined;
+        }
+    }
+}
+export function removeAllOAuthFiles() {
+    const base = getTymioConfigDir();
+    for (const f of [CLIENT_FILE, TOKENS_FILE, DISCOVERY_FILE]) {
+        try {
+            fs.unlinkSync(path.join(base, f));
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}

package/dist/hubProxyStdio.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Stdio MCP server that proxies to the hosted Tymio Streamable HTTP MCP endpoint with OAuth tokens on disk.
+ */
+export declare function runHubOAuthStdio(mcpUrl?: URL): Promise<void>;