cito-mcp 0.2.6 → 0.2.7

package/README.md

@@ -38,33 +38,39 @@ Composites multi-fetch server-side, return a **stable JSON envelope**, and isola
 
 ## Install
 
-### One-liner (published package)
+### One command (recommended)
 
 ```bash
-npx cito-mcp
+npx cito-mcp install --key cito_your_key_here
 ```
 
-Requires `CITO_API_KEY` in the environment (see [Environment](#environment)). Most hosts inject env via their MCP config rather than a bare shell.
+Detects the MCP clients installed on your machine — Claude Code, Claude Desktop, Cursor, Windsurf, Codex CLI — and writes the config for each. Then restart your editor.
 
-### Claude Code
+It is safe to re-run: existing config is merged, not replaced, your other MCP servers are left alone, a `.cito-bak` backup is written before the first change, and running it again just rotates the key rather than adding a second entry.
 
 ```bash
-claude mcp add cito -e CITO_API_KEY=cito_your_key_here -- npx cito-mcp
+npx cito-mcp install --dry-run                     # show the plan, write nothing
+npx cito-mcp install --key … --client cursor       # one client only
+npx cito-mcp install --help
 ```
 
-Windows — if `npx` fails under Claude:
+Get a key at [citoapi.com/dashboard](https://citoapi.com/dashboard).
+
+### Manual — Claude Code
 
 ```bash
-claude mcp add cito -e CITO_API_KEY=cito_your_key_here -- cmd /c npx cito-mcp
+claude mcp add cito -e CITO_API_KEY=cito_your_key_here "--" npx -y cito-mcp
 ```
 
+**Quote the `--`.** PowerShell 5.1 strips a bare `--` before the CLI sees it; because `-e` takes a variable number of values it then swallows `npx -y cito-mcp` as env vars and fails with `unknown option '-y'`. The quoted form works in PowerShell, cmd, bash and zsh alike. `npx cito-mcp install` avoids the problem entirely.
+
 From a local clone (development):
 
 ```bash
 cd mcp
 npm install
 npm run build
-claude mcp add cito -e CITO_API_KEY=cito_your_key_here -- node "%CD%\dist\index.js"
+claude mcp add cito -e CITO_API_KEY=cito_your_key_here "--" node "%CD%\dist\index.js"
 ```
 
 ### Cursor
@@ -460,13 +466,20 @@ Package: **`cito-mcp@0.2.4`**
    - `live_matches`
    - `resolve_entity` (e.g. T1 / s1mple)
    - `match_summary` with a real `matchId` from live/schedule
-4. Confirm `package.json` version and README match the shipped tool list (15).
+4. Confirm `package.json` version and README match the shipped tool list.
 5. `npm publish` from `mcp/` (or your release pipeline) with appropriate npm auth / access.
+   `prepublishOnly` runs build + tests + smoke, so a broken build cannot ship.
 
 ### Install line for docs & marketing
 
 ```bash
-claude mcp add cito -e CITO_API_KEY=cito_… -- npx cito-mcp
+npx cito-mcp install --key cito_…
+```
+
+Manual fallback (note the quoted `--`, required for PowerShell):
+
+```bash
+claude mcp add cito -e CITO_API_KEY=cito_… "--" npx -y cito-mcp
 ```
 
 ```json

package/dist/index.js

@@ -19,6 +19,18 @@ import { SERVER_INSTRUCTIONS } from './instructions.js';
 import { allTools, getTool } from './tools/index.js';
 import { runTool } from './tools/types.js';
 import { PACKAGE_VERSION } from './version.js';
+/**
+ * Subcommands run and exit before any transport exists.
+ *
+ * `install` writes editor config and prints to stdout, which would corrupt the
+ * JSON-RPC channel if it ran alongside the server — hence the early return.
+ * Handled here rather than in a second binary so the documented entry point
+ * stays `npx cito-mcp`.
+ */
+if (process.argv[2] === 'install') {
+    const { runInstall } = await import('./install.js');
+    process.exit(await runInstall(process.argv.slice(3)));
+}
 const API_KEY = process.env.CITO_API_KEY;
 /**
  * Tools that need no API key. These must keep working with the server

package/dist/install.js

@@ -0,0 +1,340 @@
+/**
+ * `npx cito-mcp install` — write the server config for whichever MCP clients
+ * are actually installed.
+ *
+ * Why this exists: the documented one-liner
+ *
+ *   claude mcp add cito -e CITO_API_KEY=… -- npx -y cito-mcp
+ *
+ * is broken in PowerShell 5.1, which strips the bare `--`. Because `-e` is a
+ * variadic option, it then swallows `npx -y cito-mcp` as extra env values and
+ * the CLI dies on "unknown option '-y'". Quoting the separator fixes it, but
+ * expecting every Windows user to know that is not onboarding — it is a trap.
+ * A subcommand has no separator to mangle and works identically everywhere.
+ *
+ * Rules this follows, because it edits files the user did not open:
+ *  - only touch clients that are already installed
+ *  - back up before the first write of a run
+ *  - merge into existing config; never rewrite a file wholesale
+ *  - idempotent: re-running replaces our entry and nothing else
+ *  - --dry-run prints the plan and writes nothing
+ *  - never print the full API key
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync } from 'node:fs';
+import { homedir, platform } from 'node:os';
+import { dirname, join } from 'node:path';
+import { PACKAGE_VERSION } from './version.js';
+const SERVER_NAME = 'cito';
+function envHome(name, fallback) {
+    const v = process.env[name];
+    return v && v.trim() ? v : fallback;
+}
+function clientsFor() {
+    const home = homedir();
+    const os = platform();
+    const appData = envHome('APPDATA', join(home, 'AppData', 'Roaming'));
+    const desktopConfig = os === 'win32'
+        ? join(appData, 'Claude', 'claude_desktop_config.json')
+        : os === 'darwin'
+            ? join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json')
+            : join(home, '.config', 'Claude', 'claude_desktop_config.json');
+    return [
+        {
+            id: 'claude-code',
+            label: 'Claude Code',
+            configPath: join(home, '.claude.json'),
+            detectPath: join(home, '.claude.json'),
+            format: 'json-mcpServers',
+        },
+        {
+            id: 'claude-desktop',
+            label: 'Claude Desktop',
+            configPath: desktopConfig,
+            detectPath: dirname(desktopConfig),
+            format: 'json-mcpServers',
+        },
+        {
+            id: 'cursor',
+            label: 'Cursor',
+            configPath: join(home, '.cursor', 'mcp.json'),
+            detectPath: join(home, '.cursor'),
+            format: 'json-mcpServers',
+        },
+        {
+            id: 'windsurf',
+            label: 'Windsurf',
+            configPath: join(home, '.codeium', 'windsurf', 'mcp_config.json'),
+            detectPath: join(home, '.codeium', 'windsurf'),
+            format: 'json-mcpServers',
+        },
+        {
+            id: 'codex',
+            label: 'Codex CLI',
+            configPath: join(home, '.codex', 'config.toml'),
+            detectPath: join(home, '.codex'),
+            format: 'toml-mcp_servers',
+        },
+    ];
+}
+export function maskKey(key) {
+    if (key.length <= 12)
+        return '****';
+    return `${key.slice(0, 9)}…${key.slice(-4)}`;
+}
+/** The stdio entry every JSON-based client understands. */
+function serverEntry(key, base) {
+    return {
+        type: 'stdio',
+        command: 'npx',
+        args: ['-y', 'cito-mcp'],
+        env: { CITO_API_KEY: key, ...(base ? { CITO_API_BASE: base } : {}) },
+    };
+}
+function readJson(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, 'utf8').trim();
+        if (!raw)
+            return {};
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Escape a TOML basic string. Only the characters TOML actually requires —
+ * an API key with a quote or backslash would otherwise produce a file the
+ * client cannot parse.
+ */
+function tomlString(v) {
+    return `"${v.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+function tomlBlock(key, base) {
+    const envLines = [`CITO_API_KEY = ${tomlString(key)}`]
+        .concat(base ? [`CITO_API_BASE = ${tomlString(base)}`] : [])
+        .join('\n');
+    return [
+        `[mcp_servers.${SERVER_NAME}]`,
+        `command = "npx"`,
+        `args = ["-y", "cito-mcp"]`,
+        ``,
+        `[mcp_servers.${SERVER_NAME}.env]`,
+        envLines,
+        ``,
+    ].join('\n');
+}
+/**
+ * Replace an existing [mcp_servers.cito] block (and its .env subtable) or
+ * append a new one. Deliberately conservative: it only recognises the exact
+ * headers it writes, so a hand-edited file is appended to rather than mangled.
+ */
+export function upsertTomlBlock(existing, key, base) {
+    const block = tomlBlock(key, base);
+    const header = new RegExp(`^\\[mcp_servers\\.${SERVER_NAME}(\\.[A-Za-z_]+)?\\]\\s*$`);
+    const anyHeader = /^\[[^\]]+\]\s*$/;
+    const lines = existing.split(/\r?\n/);
+    const kept = [];
+    let skipping = false;
+    for (const line of lines) {
+        if (header.test(line)) {
+            skipping = true;
+            continue;
+        }
+        if (skipping && anyHeader.test(line))
+            skipping = false;
+        if (!skipping)
+            kept.push(line);
+    }
+    const body = kept.join('\n').replace(/\n{3,}$/, '\n\n').replace(/\s*$/, '');
+    return (body ? `${body}\n\n` : '') + block;
+}
+/**
+ * Claude Code owns the schema of ~/.claude.json and stores far more than MCP
+ * config in it, so let its own CLI do the write when it is on PATH. Direct
+ * editing is the fallback, not the default.
+ */
+function tryClaudeCli(key, base, dryRun) {
+    const json = JSON.stringify(serverEntry(key, base));
+    // On Windows `claude` is a .cmd shim, which execFileSync cannot spawn
+    // directly — it needs a shell. Quoting matters there because the JSON
+    // payload contains spaces and double quotes.
+    const isWin = platform() === 'win32';
+    const run = (args) => {
+        if (!isWin) {
+            execFileSync('claude', args, { stdio: 'ignore' });
+            return;
+        }
+        execFileSync('cmd', ['/c', 'claude', ...args], { stdio: 'ignore' });
+    };
+    try {
+        if (dryRun) {
+            run(['--version']);
+            return 'would use `claude mcp add-json` (CLI detected)';
+        }
+        run(['mcp', 'add-json', SERVER_NAME, json, '-s', 'user']);
+        return 'via `claude mcp add-json` (user scope)';
+    }
+    catch {
+        return null;
+    }
+}
+function writeJsonClient(c, key, base, dryRun) {
+    const current = readJson(c.configPath);
+    if (current === null && existsSync(c.configPath)) {
+        return {
+            client: c,
+            status: 'failed',
+            note: `${c.configPath} is not valid JSON — left untouched`,
+        };
+    }
+    const config = current ?? {};
+    const servers = (config.mcpServers ?? {});
+    const existed = Object.prototype.hasOwnProperty.call(servers, SERVER_NAME);
+    const next = { ...config, mcpServers: { ...servers, [SERVER_NAME]: serverEntry(key, base) } };
+    if (dryRun) {
+        return {
+            client: c,
+            status: 'planned',
+            note: `${existed ? 'replace' : 'add'} "${SERVER_NAME}" in ${c.configPath}`,
+        };
+    }
+    mkdirSync(dirname(c.configPath), { recursive: true });
+    if (existsSync(c.configPath))
+        copyFileSync(c.configPath, `${c.configPath}.cito-bak`);
+    writeFileSync(c.configPath, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+    return {
+        client: c,
+        status: 'written',
+        note: `${existed ? 'updated' : 'added'} in ${c.configPath}`,
+    };
+}
+function writeTomlClient(c, key, base, dryRun) {
+    const existing = existsSync(c.configPath) ? readFileSync(c.configPath, 'utf8') : '';
+    const existed = new RegExp(`\\[mcp_servers\\.${SERVER_NAME}\\]`).test(existing);
+    if (dryRun) {
+        return {
+            client: c,
+            status: 'planned',
+            note: `${existed ? 'replace' : 'add'} [mcp_servers.${SERVER_NAME}] in ${c.configPath}`,
+        };
+    }
+    mkdirSync(dirname(c.configPath), { recursive: true });
+    if (existsSync(c.configPath))
+        copyFileSync(c.configPath, `${c.configPath}.cito-bak`);
+    writeFileSync(c.configPath, upsertTomlBlock(existing, key, base), 'utf8');
+    return {
+        client: c,
+        status: 'written',
+        note: `${existed ? 'updated' : 'added'} in ${c.configPath}`,
+    };
+}
+function parseArgs(argv) {
+    const out = { key: undefined, base: undefined, only: [], dryRun: false, help: false };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        const eat = () => argv[++i];
+        if (a === '--help' || a === '-h')
+            out.help = true;
+        else if (a === '--dry-run' || a === '-n')
+            out.dryRun = true;
+        else if (a === '--key')
+            out.key = eat();
+        else if (a?.startsWith('--key='))
+            out.key = a.slice(6);
+        else if (a === '--base')
+            out.base = eat();
+        else if (a?.startsWith('--base='))
+            out.base = a.slice(7);
+        else if (a === '--client')
+            out.only.push(...(eat() ?? '').split(',').filter(Boolean));
+        else if (a?.startsWith('--client='))
+            out.only.push(...a.slice(9).split(',').filter(Boolean));
+    }
+    return out;
+}
+const HELP = `cito-mcp install — configure the Cito MCP server for your editors
+
+Usage:
+  npx cito-mcp install --key cito_xxx
+  npx cito-mcp install --key cito_xxx --client cursor,claude-code
+  npx cito-mcp install --dry-run
+
+Options:
+  --key <key>       Cito API key. Falls back to $CITO_API_KEY.
+  --client <ids>    Comma-separated: claude-code, claude-desktop, cursor, windsurf, codex.
+                    Default: every client detected on this machine.
+  --base <url>      Override API base (staging / self-hosted).
+  --dry-run, -n     Show what would change; write nothing.
+  --help, -h        This message.
+
+Get a key at https://citoapi.com/dashboard`;
+export async function runInstall(argv) {
+    const args = parseArgs(argv);
+    if (args.help) {
+        console.log(HELP);
+        return 0;
+    }
+    const key = args.key ?? process.env.CITO_API_KEY;
+    if (!key && !args.dryRun) {
+        console.error('No API key. Pass --key cito_xxx or set CITO_API_KEY.\n');
+        console.error('Get one at https://citoapi.com/dashboard');
+        return 1;
+    }
+    const all = clientsFor();
+    const unknown = args.only.filter((id) => !all.some((c) => c.id === id));
+    if (unknown.length) {
+        console.error(`Unknown client(s): ${unknown.join(', ')}`);
+        console.error(`Valid: ${all.map((c) => c.id).join(', ')}`);
+        return 1;
+    }
+    // An explicit --client is a instruction, not a guess: honour it even if we
+    // cannot detect the client (fresh install, portable install, unusual path).
+    const selected = args.only.length
+        ? all.filter((c) => args.only.includes(c.id))
+        : all.filter((c) => existsSync(c.detectPath));
+    if (selected.length === 0) {
+        console.error('No supported MCP clients detected.');
+        console.error(`Looked for: ${all.map((c) => c.label).join(', ')}`);
+        console.error('Use --client <id> to configure one anyway.');
+        return 1;
+    }
+    console.log(`cito-mcp ${PACKAGE_VERSION} installer`);
+    console.log(key ? `key: ${maskKey(key)}` : 'key: (none — dry run)');
+    console.log(args.dryRun ? 'mode: dry run, nothing will be written\n' : '');
+    const effectiveKey = key ?? 'CITO_API_KEY';
+    const results = [];
+    for (const c of selected) {
+        if (c.id === 'claude-code') {
+            const viaCli = tryClaudeCli(effectiveKey, args.base, args.dryRun);
+            if (viaCli) {
+                results.push({ client: c, status: args.dryRun ? 'planned' : 'written', note: viaCli });
+                continue;
+            }
+        }
+        results.push(c.format === 'toml-mcp_servers'
+            ? writeTomlClient(c, effectiveKey, args.base, args.dryRun)
+            : writeJsonClient(c, effectiveKey, args.base, args.dryRun));
+    }
+    for (const r of results) {
+        const mark = r.status === 'failed' ? '✗' : r.status === 'skipped' ? '–' : '✓';
+        console.log(`  ${mark} ${r.client.label.padEnd(16)} ${r.note}`);
+    }
+    const failed = results.filter((r) => r.status === 'failed');
+    console.log('');
+    if (args.dryRun) {
+        console.log('Dry run complete. Re-run without --dry-run to apply.');
+    }
+    else {
+        console.log('Restart your editor to load the server, then ask it:');
+        console.log('  "what UFC events are coming up?"');
+    }
+    if (failed.length) {
+        console.log(`\n${failed.length} client(s) could not be configured (see above).`);
+        return 1;
+    }
+    return 0;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cito-mcp",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "Standalone MCP server for the Cito esports API — 15 curated outcome tools for agents (live, schedule, profiles, standings, previews, event cards).",
   "type": "module",
   "bin": {