@spekoai/mcp 1.0.4 → 1.0.6

package/README.md

@@ -1,128 +1,42 @@
 # @spekoai/mcp
 
-Local stdio bridge for MCP clients that cannot connect to remote HTTP MCP
-servers directly. It proxies SpekoAI's hosted MCP server and does not contain
-Speko tool logic of its own.
-
-Use the hosted endpoint directly when your client supports remote MCP:
-
-```json
-{
-  "mcpServers": {
-    "spekoai": {
-      "url": "https://mcp.speko.ai/mcp-auth"
-    }
-  }
-}
-```
-
-Use this package for stdio-only clients.
+Interactive installer and local stdio-to-remote bridge for Speko MCP. The
+installer configures Speko's hosted remote MCP endpoint in coding tools that
+support it. The `bridge` command is only for MCP clients that require a local
+stdio command: it speaks stdio to the client, connects to Speko's hosted MCP
+server over HTTP, and does not contain Speko tool logic of its own.
 
 ## Install
 
 ```bash
-npx @spekoai/mcp@latest --help
+npx @spekoai/mcp@latest init
 ```
 
-The package exposes the `spekoai-mcp` binary.
-
-## Claude Code
-
-OAuth-capable remote MCP clients should prefer the hosted endpoint:
-
-```bash
-claude mcp add --transport http spekoai https://mcp.speko.ai/mcp-auth
-```
+The package exposes the `spekoai-mcp` binary. Run `init` for a guided setup
+wizard that can configure Claude Code, Codex, OpenCode, Cursor, and generic MCP
+clients.
 
-For a stdio bridge install:
+For scripted setup, pass the choices explicitly:
 
 ```bash
-claude mcp add spekoai -- npx -y @spekoai/mcp@latest
+npx @spekoai/mcp@latest init --access full --auth oauth --tools claude,codex --scope user --yes
 ```
 
-For API-key auth in a headless setup, provide `SPEKO_API_KEY` in the MCP
-client environment. The bridge forwards it as `Authorization: Bearer ...`.
-
-## Cursor
+## Bridge
 
-Add this to `~/.cursor/mcp.json`:
-
-```json
-{
-  "mcpServers": {
-    "spekoai": {
-      "command": "npx",
-      "args": ["-y", "@spekoai/mcp@latest"]
-    }
-  }
-}
-```
+Most users should run `init`. Use `bridge` only when a client cannot connect to
+remote MCP directly and asks for a local command-based MCP server.
 
-With API-key auth:
-
-```json
-{
-  "mcpServers": {
-    "spekoai": {
-      "command": "npx",
-      "args": ["-y", "@spekoai/mcp@latest"],
-      "env": {
-        "SPEKO_API_KEY": "sk_live_xxx"
-      }
-    }
-  }
-}
+```bash
+npx @spekoai/mcp@latest bridge
 ```
 
-## OpenCode
-
-Add this to `opencode.json`:
-
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "mcp": {
-    "spekoai": {
-      "type": "local",
-      "command": ["pnpm", "dlx", "@spekoai/mcp@latest"],
-      "enabled": true
-    }
-  }
-}
-```
+For API-key auth in a headless bridge setup, provide `SPEKO_API_KEY` in the MCP
+client environment. The bridge forwards it to the hosted MCP server as
+`Authorization: Bearer ...`.
 
-With API-key auth:
-
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "mcp": {
-    "spekoai": {
-      "type": "local",
-      "command": ["pnpm", "dlx", "@spekoai/mcp@latest"],
-      "enabled": true,
-      "environment": {
-        "SPEKO_API_KEY": "{env:SPEKO_API_KEY}"
-      }
-    }
-  }
-}
-```
-
-## Generic MCP Config
-
-```json
-{
-  "mcpServers": {
-    "spekoai": {
-      "command": "npx",
-      "args": ["-y", "@spekoai/mcp@latest"]
-    }
-  }
-}
-```
-
-## Configuration
+The `bridge` command adapts local stdio MCP to Speko's remote HTTP MCP endpoint.
+Use direct remote MCP configuration instead when your client supports it.
 
 Defaults:
 
@@ -131,35 +45,31 @@ Defaults:
 
 Environment variables:
 
-- `SPEKOAI_MCP_AUTH_URL`: override the authenticated endpoint.
-- `SPEKOAI_MCP_URL`: override the public endpoint.
 - `SPEKO_API_KEY`: forward an API key as a bearer token.
 
 CLI examples:
 
 ```bash
-npx @spekoai/mcp@latest
-npx @spekoai/mcp@latest --public
-SPEKO_API_KEY=sk_live_xxx npx @spekoai/mcp@latest
-SPEKOAI_MCP_AUTH_URL=https://mcp-staging.speko.dev/mcp-auth npx @spekoai/mcp@latest
-npx @spekoai/mcp@latest https://mcp-staging.speko.dev/mcp-auth --debug
+npx @spekoai/mcp@latest bridge
+npx @spekoai/mcp@latest bridge --public
+SPEKO_API_KEY=sk_live_xxx npx @spekoai/mcp@latest bridge
 ```
 
-All remaining arguments are passed through to `mcp-remote`.
+All remaining arguments are passed through to
+[`mcp-remote`](https://www.npmjs.com/package/mcp-remote).
 
 ## Troubleshooting
 
 Run:
 
 ```bash
-npx @spekoai/mcp@latest --help
+npx @spekoai/mcp@latest bridge --help
 ```
 
-For `mcp-remote` auth cache issues, restart the MCP client after clearing:
-
-```bash
-rm -rf ~/.mcp-auth
-```
+When using `bridge`, OAuth state is handled by
+[`mcp-remote`](https://www.npmjs.com/package/mcp-remote). It may create
+`~/.mcp-auth` or use `MCP_REMOTE_CONFIG_DIR` to store local OAuth credentials
+and debug logs. The `init` wizard does not write that directory.
 
 For connection or OAuth issues, pass `--debug` and inspect the log path printed
-by `mcp-remote`.
+by [`mcp-remote`](https://www.npmjs.com/package/mcp-remote).

package/dist/constants.d.ts

@@ -0,0 +1,5 @@
+export declare const DEFAULT_AUTH_MCP_URL = "https://mcp.speko.ai/mcp-auth";
+export declare const DEFAULT_PUBLIC_MCP_URL = "https://mcp.speko.ai/mcp";
+export declare const AUTH_HEADER_ENV = "SPEKOAI_MCP_AUTH_HEADER";
+export type Environment = Record<string, string | undefined>;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,oBAAoB,kCAAkC,CAAC;AACpE,eAAO,MAAM,sBAAsB,6BAA6B,CAAC;AACjE,eAAO,MAAM,eAAe,4BAA4B,CAAC;AAEzD,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC"}

package/dist/constants.js

@@ -0,0 +1,3 @@
+export const DEFAULT_AUTH_MCP_URL = 'https://mcp.speko.ai/mcp-auth';
+export const DEFAULT_PUBLIC_MCP_URL = 'https://mcp.speko.ai/mcp';
+export const AUTH_HEADER_ENV = 'SPEKOAI_MCP_AUTH_HEADER';

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
-export declare const DEFAULT_AUTH_MCP_URL = "https://mcp.speko.ai/mcp-auth";
-export declare const DEFAULT_PUBLIC_MCP_URL = "https://mcp.speko.ai/mcp";
-export declare const AUTH_HEADER_ENV = "SPEKOAI_MCP_AUTH_HEADER";
-export type Environment = Record<string, string | undefined>;
+import { AUTH_HEADER_ENV, DEFAULT_AUTH_MCP_URL, DEFAULT_PUBLIC_MCP_URL, type Environment } from './constants.js';
+export type { InitAccess, InitAuth, InitScope, InitTool, ParsedInitArgs, PlannedInitStep, ResolvedInitOptions, } from './init.js';
+export { buildCodexConfig, buildCursorConfig, buildInitPlan, buildOpenCodeConfig, completeInitArgs, DEFAULT_SCOPE, DEFAULT_SELECTED_TOOLS, endpointForAccess, INIT_HELP_TEXT, parseInitArgs, runInitCommand, } from './init.js';
+export type { Environment };
+export { AUTH_HEADER_ENV, DEFAULT_AUTH_MCP_URL, DEFAULT_PUBLIC_MCP_URL };
 export type CliConfig = {
     serverUrl: string;
     passthroughArgs: string[];
@@ -13,7 +14,8 @@ export type AuthHeaderConfig = {
     args: string[];
     envValue?: string;
 };
-export declare const HELP_TEXT = "Usage: spekoai-mcp [url] [mcp-remote flags]\n\nBridge local stdio MCP clients to SpekoAI's hosted MCP server.\n\nDefaults:\n  Authenticated endpoint: https://mcp.speko.ai/mcp-auth\n  Public-only endpoint:   https://mcp.speko.ai/mcp\n\nOptions:\n  --public       Connect to the public docs/scaffolding endpoint.\n  -h, --help     Print this help text.\n\nEnvironment:\n  SPEKOAI_MCP_AUTH_URL   Override the authenticated endpoint.\n  SPEKOAI_MCP_URL        Override the public endpoint.\n  SPEKO_API_KEY          Forward as Authorization bearer token.\n\nExamples:\n  spekoai-mcp\n  spekoai-mcp --public\n  SPEKO_API_KEY=sk_live_xxx spekoai-mcp\n  SPEKOAI_MCP_AUTH_URL=https://mcp-staging.speko.dev/mcp-auth spekoai-mcp\n  spekoai-mcp https://mcp-staging.speko.dev/mcp-auth --debug\n\nAll remaining arguments are passed through to mcp-remote.\n";
+export declare const HELP_TEXT = "Usage: spekoai-mcp <command> [options]\n\nConfigure Speko MCP in coding tools, or run the local stdio bridge for MCP clients that cannot connect to remote HTTP MCP directly.\n\nCommands:\n  init          Configure Speko MCP in coding tools.\n  bridge        Run the local stdio bridge to Speko's hosted MCP server.\n\nOptions:\n  -h, --help    Print this help text.\n\nExamples:\n  spekoai-mcp init\n  spekoai-mcp init --dry-run --access docs --tools cursor --scope project --yes\n  spekoai-mcp bridge\n  spekoai-mcp bridge --public\n";
+export declare const BRIDGE_HELP_TEXT = "Usage: spekoai-mcp bridge [options] [mcp-remote flags]\n\nBridge local stdio MCP clients to Speko's hosted MCP server.\n\nDefaults:\n  Full Speko account access:      https://mcp.speko.ai/mcp-auth\n  Public docs and scaffolds only: https://mcp.speko.ai/mcp\n\nOptions:\n  --public     Connect to the public docs/scaffolding endpoint.\n  -h, --help   Print this help text.\n\nEnvironment:\n  SPEKO_API_KEY   Forward as Authorization bearer token.\n\nExamples:\n  spekoai-mcp bridge\n  spekoai-mcp bridge --public\n  SPEKO_API_KEY=sk_live_xxx spekoai-mcp bridge\n\nAll remaining arguments are passed through to mcp-remote.\n";
 export declare function resolveCliConfig(argv: readonly string[], env?: Environment): CliConfig;
 export declare function buildAuthHeaderArgs(env?: Environment): AuthHeaderConfig;
 export declare function buildProxyArgv(options: {
@@ -24,5 +26,6 @@ export declare function buildProxyArgv(options: {
     passthroughArgs: readonly string[];
 }): string[];
 export declare function resolveProxyPath(): string;
+export declare function isCliEntrypoint(entrypointPath?: string, moduleUrl?: string): boolean;
 export declare function run(argv?: string[], env?: NodeJS.ProcessEnv): Promise<void>;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAKA,eAAO,MAAM,oBAAoB,kCAAkC,CAAC;AACpE,eAAO,MAAM,sBAAsB,6BAA6B,CAAC;AACjE,eAAO,MAAM,eAAe,4BAA4B,CAAC;AAEzD,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAE7D,MAAM,MAAM,SAAS,GAAG;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,UAAU,EAAE,OAAO,CAAC;IACpB,IAAI,EAAE,OAAO,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,eAAO,MAAM,SAAS,g1BAyBrB,CAAC;AAEF,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,GAAG,GAAE,WAAyB,GAC7B,SAAS,CAwBX;AAED,wBAAgB,mBAAmB,CAAC,GAAG,GAAE,WAAyB,GAAG,gBAAgB,CAUpF;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC,GAAG,MAAM,EAAE,CAQX;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED,wBAAsB,GAAG,CAAC,IAAI,WAAwB,EAAE,GAAG,oBAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAuBxF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAKA,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,sBAAsB,EACtB,KAAK,WAAW,EACjB,MAAM,gBAAgB,CAAC;AAGxB,YAAY,EACV,UAAU,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,cAAc,EACd,eAAe,EACf,mBAAmB,GACpB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,mBAAmB,EACnB,gBAAgB,EAChB,aAAa,EACb,sBAAsB,EACtB,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,cAAc,GACf,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,WAAW,EAAE,CAAC;AAC5B,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,CAAC;AAEzE,MAAM,MAAM,SAAS,GAAG;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,UAAU,EAAE,OAAO,CAAC;IACpB,IAAI,EAAE,OAAO,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,eAAO,MAAM,SAAS,2hBAgBrB,CAAC;AAEF,eAAO,MAAM,gBAAgB,mnBAqB5B,CAAC;AAEF,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,GAAG,GAAE,WAAyB,GAC7B,SAAS,CAwBX;AAED,wBAAgB,mBAAmB,CAAC,GAAG,GAAE,WAAyB,GAAG,gBAAgB,CAUpF;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC,GAAG,MAAM,EAAE,CAQX;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED,wBAAgB,eAAe,CAC7B,cAAc,SAAkB,EAChC,SAAS,SAAkB,GAC1B,OAAO,CAWT;AAED,wBAAsB,GAAG,CAAC,IAAI,WAAwB,EAAE,GAAG,oBAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBxF"}

package/dist/index.js

@@ -1,32 +1,47 @@
 #!/usr/bin/env node
+import { realpathSync } from 'node:fs';
 import { createRequire } from 'node:module';
-import { pathToFileURL } from 'node:url';
-export const DEFAULT_AUTH_MCP_URL = 'https://mcp.speko.ai/mcp-auth';
-export const DEFAULT_PUBLIC_MCP_URL = 'https://mcp.speko.ai/mcp';
-export const AUTH_HEADER_ENV = 'SPEKOAI_MCP_AUTH_HEADER';
-export const HELP_TEXT = `Usage: spekoai-mcp [url] [mcp-remote flags]
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { AUTH_HEADER_ENV, DEFAULT_AUTH_MCP_URL, DEFAULT_PUBLIC_MCP_URL, } from './constants.js';
+import { runInitCommand } from './init.js';
+export { buildCodexConfig, buildCursorConfig, buildInitPlan, buildOpenCodeConfig, completeInitArgs, DEFAULT_SCOPE, DEFAULT_SELECTED_TOOLS, endpointForAccess, INIT_HELP_TEXT, parseInitArgs, runInitCommand, } from './init.js';
+export { AUTH_HEADER_ENV, DEFAULT_AUTH_MCP_URL, DEFAULT_PUBLIC_MCP_URL };
+export const HELP_TEXT = `Usage: spekoai-mcp <command> [options]
 
-Bridge local stdio MCP clients to SpekoAI's hosted MCP server.
+Configure Speko MCP in coding tools, or run the local stdio bridge for MCP clients that cannot connect to remote HTTP MCP directly.
+
+Commands:
+  init          Configure Speko MCP in coding tools.
+  bridge        Run the local stdio bridge to Speko's hosted MCP server.
+
+Options:
+  -h, --help    Print this help text.
+
+Examples:
+  spekoai-mcp init
+  spekoai-mcp init --dry-run --access docs --tools cursor --scope project --yes
+  spekoai-mcp bridge
+  spekoai-mcp bridge --public
+`;
+export const BRIDGE_HELP_TEXT = `Usage: spekoai-mcp bridge [options] [mcp-remote flags]
+
+Bridge local stdio MCP clients to Speko's hosted MCP server.
 
 Defaults:
-  Authenticated endpoint: ${DEFAULT_AUTH_MCP_URL}
-  Public-only endpoint:   ${DEFAULT_PUBLIC_MCP_URL}
+  Full Speko account access:      ${DEFAULT_AUTH_MCP_URL}
+  Public docs and scaffolds only: ${DEFAULT_PUBLIC_MCP_URL}
 
 Options:
-  --public       Connect to the public docs/scaffolding endpoint.
-  -h, --help     Print this help text.
+  --public     Connect to the public docs/scaffolding endpoint.
+  -h, --help   Print this help text.
 
 Environment:
-  SPEKOAI_MCP_AUTH_URL   Override the authenticated endpoint.
-  SPEKOAI_MCP_URL        Override the public endpoint.
-  SPEKO_API_KEY          Forward as Authorization bearer token.
+  SPEKO_API_KEY   Forward as Authorization bearer token.
 
 Examples:
-  spekoai-mcp
-  spekoai-mcp --public
-  SPEKO_API_KEY=sk_live_xxx spekoai-mcp
-  SPEKOAI_MCP_AUTH_URL=https://mcp-staging.speko.dev/mcp-auth spekoai-mcp
-  spekoai-mcp https://mcp-staging.speko.dev/mcp-auth --debug
+  spekoai-mcp bridge
+  spekoai-mcp bridge --public
+  SPEKO_API_KEY=sk_live_xxx spekoai-mcp bridge
 
 All remaining arguments are passed through to mcp-remote.
 `;
@@ -75,10 +90,37 @@ export function buildProxyArgv(options) {
 export function resolveProxyPath() {
     return createRequire(import.meta.url).resolve('mcp-remote/dist/proxy.js');
 }
+export function isCliEntrypoint(entrypointPath = process.argv[1], moduleUrl = import.meta.url) {
+    if (!entrypointPath) {
+        return false;
+    }
+    const modulePath = fileURLToPath(moduleUrl);
+    try {
+        return realpathSync(entrypointPath) === realpathSync(modulePath);
+    }
+    catch {
+        return pathToFileURL(entrypointPath).href === moduleUrl;
+    }
+}
 export async function run(argv = process.argv.slice(2), env = process.env) {
+    if (argv[0] === 'init') {
+        await runInitCommand(argv.slice(1), { env });
+        return;
+    }
+    if (argv[0] === 'bridge') {
+        await runBridgeCommand(argv.slice(1), env);
+        return;
+    }
+    if (argv.length === 0 || argv.includes('--help') || argv.includes('-h')) {
+        process.stdout.write(HELP_TEXT);
+        return;
+    }
+    throw new Error(`Unknown command: ${argv[0]}. Run "spekoai-mcp --help" for usage.`);
+}
+async function runBridgeCommand(argv, env) {
     const config = resolveCliConfig(argv, env);
     if (config.help) {
-        process.stdout.write(HELP_TEXT);
+        process.stdout.write(BRIDGE_HELP_TEXT);
         return;
     }
     const auth = buildAuthHeaderArgs(env);
@@ -105,7 +147,7 @@ function envUrl(value, fallback) {
 function isHttpUrl(value) {
     return value?.startsWith('https://') === true || value?.startsWith('http://') === true;
 }
-if (pathToFileURL(process.argv[1] ?? '').href === import.meta.url) {
+if (isCliEntrypoint()) {
     run().catch((error) => {
         process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
         process.exit(1);

package/dist/init.d.ts

@@ -0,0 +1,84 @@
+import { type Environment } from './constants.js';
+export type InitAccess = 'full' | 'docs';
+export type InitAuth = 'oauth' | 'api-key';
+export type InitScope = 'user' | 'project';
+export type InitTool = 'claude' | 'codex' | 'opencode' | 'cursor' | 'other';
+export type ParsedInitArgs = {
+    access?: InitAccess;
+    auth?: InitAuth;
+    tools?: InitTool[];
+    scope?: InitScope;
+    dryRun: boolean;
+    yes: boolean;
+    help: boolean;
+};
+export type ResolvedInitOptions = {
+    access: InitAccess;
+    auth?: InitAuth;
+    tools: InitTool[];
+    scope: InitScope;
+    dryRun: boolean;
+    yes: boolean;
+};
+export type InitPaths = {
+    homeDir: string;
+    cwd: string;
+};
+export type FileUpdateResult = {
+    ok: true;
+    content: string;
+} | {
+    ok: false;
+    reason: string;
+    manualSnippet: string;
+};
+export type PlannedInitStep = {
+    kind: 'command';
+    tool: 'claude';
+    label: string;
+    command: string[];
+    manualSnippet: string;
+    postInstall?: string;
+} | {
+    kind: 'file';
+    tool: 'codex' | 'opencode' | 'cursor';
+    label: string;
+    path: string;
+    build: (existing: string | undefined) => FileUpdateResult;
+    manualSnippet: string;
+    postInstall?: string;
+} | {
+    kind: 'manual';
+    tool: InitTool;
+    label: string;
+    manualSnippet: string;
+    postInstall?: string;
+};
+type InitDependencies = {
+    env?: Environment;
+    homeDir?: string;
+    cwd?: string;
+    stdin?: NodeJS.ReadStream;
+    stdout?: NodeJS.WriteStream;
+    stderr?: NodeJS.WriteStream;
+    timestamp?: () => string;
+    runCommand?: (command: readonly string[]) => {
+        ok: boolean;
+        message: string;
+    };
+};
+export declare const DEFAULT_SELECTED_TOOLS: readonly InitTool[];
+export declare const DEFAULT_SCOPE: InitScope;
+export declare const INIT_HELP_TEXT = "Usage: spekoai-mcp init [options]\n\nConfigure Speko MCP in Claude Code, Codex, OpenCode, Cursor, or another MCP client.\n\nOptions:\n  --access <full|docs>        full uses https://mcp.speko.ai/mcp-auth; docs uses https://mcp.speko.ai/mcp\n  --auth <oauth|api-key>      Authentication mode for full access.\n  --tools <list>              Comma-separated tools: claude,codex,opencode,cursor,other\n  --scope <user|project>      Install globally for the user or in the current project.\n  --dry-run                   Print the planned changes without writing files or running commands.\n  --yes                       Skip the final confirmation prompt.\n  -h, --help                  Print this help text.\n\nExamples:\n  spekoai-mcp init\n  spekoai-mcp init --dry-run --access docs --tools cursor --scope project --yes\n  spekoai-mcp init --access full --auth oauth --tools claude,codex --scope user --yes\n";
+export declare function parseInitArgs(argv: readonly string[]): ParsedInitArgs;
+export declare function completeInitArgs(parsed: ParsedInitArgs): ResolvedInitOptions;
+export declare function endpointForAccess(access: InitAccess): string;
+export declare function isApiKeyAuth(options: Pick<ResolvedInitOptions, 'access' | 'auth'>): boolean;
+export declare function buildCursorConfig(existing: string | undefined, endpoint: string, apiKeyAuth: boolean): FileUpdateResult;
+export declare function buildOpenCodeConfig(existing: string | undefined, endpoint: string, apiKeyAuth: boolean): FileUpdateResult;
+export declare function buildCodexConfig(existing: string | undefined, endpoint: string, apiKeyAuth: boolean): FileUpdateResult;
+export declare function buildInitPlan(options: ResolvedInitOptions, paths: InitPaths): PlannedInitStep[];
+export declare function renderPlanSummary(options: ResolvedInitOptions, steps: readonly PlannedInitStep[]): string;
+export declare function runInitCommand(argv?: readonly string[], deps?: InitDependencies): Promise<void>;
+export {};
+//# sourceMappingURL=init.d.ts.map

package/dist/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"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"}

package/dist/init.js

@@ -0,0 +1,661 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { copyFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { confirm, intro, isCancel, log, multiselect, note, outro, select } from '@clack/prompts';
+import { applyEdits, modify, parse as parseJsonc } from 'jsonc-parser';
+import { parse as parseToml } from 'smol-toml';
+import { DEFAULT_AUTH_MCP_URL, DEFAULT_PUBLIC_MCP_URL } from './constants.js';
+const TOOL_SPECS = [
+    { tool: 'claude', label: 'Claude Code' },
+    { tool: 'codex', label: 'Codex' },
+    { tool: 'opencode', label: 'OpenCode' },
+    { tool: 'cursor', label: 'Cursor' },
+    { tool: 'other', label: 'Other clients' },
+];
+export const DEFAULT_SELECTED_TOOLS = ['claude', 'opencode'];
+export const DEFAULT_SCOPE = 'project';
+const TOOL_LABELS = new Map(TOOL_SPECS.map((spec) => [spec.tool, spec.label]));
+export const INIT_HELP_TEXT = `Usage: spekoai-mcp init [options]
+
+Configure Speko MCP in Claude Code, Codex, OpenCode, Cursor, or another MCP client.
+
+Options:
+  --access <full|docs>        full uses ${DEFAULT_AUTH_MCP_URL}; docs uses ${DEFAULT_PUBLIC_MCP_URL}
+  --auth <oauth|api-key>      Authentication mode for full access.
+  --tools <list>              Comma-separated tools: claude,codex,opencode,cursor,other
+  --scope <user|project>      Install globally for the user or in the current project.
+  --dry-run                   Print the planned changes without writing files or running commands.
+  --yes                       Skip the final confirmation prompt.
+  -h, --help                  Print this help text.
+
+Examples:
+  spekoai-mcp init
+  spekoai-mcp init --dry-run --access docs --tools cursor --scope project --yes
+  spekoai-mcp init --access full --auth oauth --tools claude,codex --scope user --yes
+`;
+export function parseInitArgs(argv) {
+    const parsed = { dryRun: false, yes: false, help: false };
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        switch (arg) {
+            case '--dry-run':
+                parsed.dryRun = true;
+                break;
+            case '--yes':
+            case '-y':
+                parsed.yes = true;
+                break;
+            case '--help':
+            case '-h':
+                parsed.help = true;
+                break;
+            case '--access':
+                parsed.access = parseAccess(readFlagValue(argv, index, arg));
+                index += 1;
+                break;
+            case '--auth':
+                parsed.auth = parseAuth(readFlagValue(argv, index, arg));
+                index += 1;
+                break;
+            case '--tools':
+                parsed.tools = parseTools(readFlagValue(argv, index, arg));
+                index += 1;
+                break;
+            case '--scope':
+                parsed.scope = parseScope(readFlagValue(argv, index, arg));
+                index += 1;
+                break;
+            default:
+                if (arg.startsWith('--access=')) {
+                    parsed.access = parseAccess(readInlineFlagValue(arg));
+                }
+                else if (arg.startsWith('--auth=')) {
+                    parsed.auth = parseAuth(readInlineFlagValue(arg));
+                }
+                else if (arg.startsWith('--tools=')) {
+                    parsed.tools = parseTools(readInlineFlagValue(arg));
+                }
+                else if (arg.startsWith('--scope=')) {
+                    parsed.scope = parseScope(readInlineFlagValue(arg));
+                }
+                else {
+                    throw new Error(`Unknown init option: ${arg}`);
+                }
+        }
+    }
+    return parsed;
+}
+export function completeInitArgs(parsed) {
+    const missing = [];
+    if (!parsed.access)
+        missing.push('--access');
+    if (parsed.access === 'full' && !parsed.auth)
+        missing.push('--auth');
+    if (!parsed.tools?.length)
+        missing.push('--tools');
+    if (!parsed.scope)
+        missing.push('--scope');
+    if (!parsed.dryRun && !parsed.yes)
+        missing.push('--yes or --dry-run');
+    if (missing.length > 0) {
+        throw new Error(`spekoai-mcp init is running non-interactively. Provide ${missing.join(', ')} or run it in an interactive terminal.`);
+    }
+    const access = parsed.access;
+    const tools = parsed.tools;
+    const scope = parsed.scope;
+    if (!access || !tools?.length || !scope) {
+        throw new Error('spekoai-mcp init options are incomplete.');
+    }
+    return {
+        access,
+        auth: access === 'full' ? parsed.auth : undefined,
+        tools,
+        scope,
+        dryRun: parsed.dryRun,
+        yes: parsed.yes,
+    };
+}
+export function endpointForAccess(access) {
+    return access === 'full' ? DEFAULT_AUTH_MCP_URL : DEFAULT_PUBLIC_MCP_URL;
+}
+export function isApiKeyAuth(options) {
+    return options.access === 'full' && options.auth === 'api-key';
+}
+export function buildCursorConfig(existing, endpoint, apiKeyAuth) {
+    const server = apiKeyAuth
+        ? {
+            url: endpoint,
+            headers: {
+                Authorization: `Bearer $${'{env:SPEKO_API_KEY}'}`,
+            },
+        }
+        : { url: endpoint };
+    return updateJsonc(existing, ['mcpServers', 'speko'], server, cursorSnippet(endpoint, apiKeyAuth));
+}
+export function buildOpenCodeConfig(existing, endpoint, apiKeyAuth) {
+    const server = apiKeyAuth
+        ? {
+            type: 'remote',
+            url: endpoint,
+            oauth: false,
+            headers: {
+                Authorization: 'Bearer {env:SPEKO_API_KEY}',
+            },
+            enabled: true,
+        }
+        : {
+            type: 'remote',
+            url: endpoint,
+            enabled: true,
+        };
+    const withSchema = updateJsonc(existing, ['$schema'], 'https://opencode.ai/config.json', openCodeSnippet(endpoint, apiKeyAuth));
+    if (!withSchema.ok)
+        return withSchema;
+    return updateJsonc(withSchema.content, ['mcp', 'speko'], server, openCodeSnippet(endpoint, apiKeyAuth));
+}
+export function buildCodexConfig(existing, endpoint, apiKeyAuth) {
+    const source = existing ?? '';
+    try {
+        parseToml(source || '');
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: `Could not parse existing TOML: ${error instanceof Error ? error.message : String(error)}`,
+            manualSnippet: codexSnippet(endpoint, apiKeyAuth),
+        };
+    }
+    const nextBlock = codexSnippet(endpoint, apiKeyAuth);
+    const withoutExisting = source.replace(/(^|\r?\n)\[mcp_servers\.speko\]\r?\n(?:(?!\r?\n\[).)*(?:\r?\n)?/s, '$1');
+    const trimmed = withoutExisting.replace(/\s+$/, '');
+    const content = `${trimmed ? `${trimmed}\n\n` : ''}${nextBlock}\n`;
+    try {
+        parseToml(content);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: `Generated TOML failed validation: ${error instanceof Error ? error.message : String(error)}`,
+            manualSnippet: nextBlock,
+        };
+    }
+    return { ok: true, content };
+}
+export function buildInitPlan(options, paths) {
+    const endpoint = endpointForAccess(options.access);
+    const apiKeyAuth = isApiKeyAuth(options);
+    const steps = [];
+    for (const tool of options.tools) {
+        if (tool === 'claude') {
+            steps.push(buildClaudeStep(options, endpoint, apiKeyAuth));
+        }
+        else if (tool === 'codex') {
+            steps.push({
+                kind: 'file',
+                tool,
+                label: 'Codex config',
+                path: join(paths.homeDir, '.codex', 'config.toml'),
+                build: (existing) => buildCodexConfig(existing, endpoint, apiKeyAuth),
+                manualSnippet: codexSnippet(endpoint, apiKeyAuth),
+                postInstall: options.access === 'full' && !apiKeyAuth ? 'Run: codex mcp login speko' : undefined,
+            });
+        }
+        else if (tool === 'opencode') {
+            const configPath = options.scope === 'user'
+                ? join(paths.homeDir, '.config', 'opencode', 'opencode.json')
+                : join(paths.cwd, 'opencode.json');
+            steps.push({
+                kind: 'file',
+                tool,
+                label: 'OpenCode config',
+                path: configPath,
+                build: (existing) => buildOpenCodeConfig(existing, endpoint, apiKeyAuth),
+                manualSnippet: openCodeSnippet(endpoint, apiKeyAuth),
+                postInstall: options.access === 'full' && !apiKeyAuth ? 'Run: opencode mcp auth speko' : undefined,
+            });
+        }
+        else if (tool === 'cursor') {
+            const configPath = options.scope === 'user'
+                ? join(paths.homeDir, '.cursor', 'mcp.json')
+                : join(paths.cwd, '.cursor', 'mcp.json');
+            steps.push({
+                kind: 'file',
+                tool,
+                label: 'Cursor config',
+                path: configPath,
+                build: (existing) => buildCursorConfig(existing, endpoint, apiKeyAuth),
+                manualSnippet: cursorSnippet(endpoint, apiKeyAuth),
+            });
+        }
+        else {
+            steps.push({
+                kind: 'manual',
+                tool,
+                label: 'Other MCP clients',
+                manualSnippet: otherClientSnippet(endpoint, options.access, apiKeyAuth),
+            });
+        }
+    }
+    return steps;
+}
+export function renderPlanSummary(options, steps) {
+    const endpoint = endpointForAccess(options.access);
+    const lines = [
+        `Access: ${options.access === 'full' ? 'Full access' : 'Docs and scaffolds only'}`,
+        `Endpoint: ${endpoint}`,
+        `Auth: ${options.access === 'full' ? (options.auth === 'api-key' ? 'SPEKO_API_KEY' : 'OAuth') : 'None'}`,
+        `Scope: ${options.scope}`,
+        '',
+        'Planned changes:',
+        ...steps.map((step) => {
+            if (step.kind === 'command') {
+                return `- ${step.label}: run ${formatCommand(step.command)}`;
+            }
+            if (step.kind === 'file') {
+                return `- ${step.label}: update ${step.path}`;
+            }
+            return `- ${step.label}: print manual Streamable HTTP settings`;
+        }),
+    ];
+    const postInstall = steps
+        .map((step) => step.postInstall)
+        .filter((value) => Boolean(value));
+    if (postInstall.length > 0) {
+        lines.push('', 'After configuring:', ...postInstall.map((step) => `- ${step}`));
+    }
+    return lines.join('\n');
+}
+export async function runInitCommand(argv = process.argv.slice(2), deps = {}) {
+    const env = deps.env ?? process.env;
+    const stdout = deps.stdout ?? process.stdout;
+    const stderr = deps.stderr ?? process.stderr;
+    const parsed = parseInitArgs(argv);
+    if (parsed.help) {
+        stdout.write(INIT_HELP_TEXT);
+        return;
+    }
+    const interactive = Boolean((deps.stdin ?? process.stdin).isTTY && stdout.isTTY);
+    const options = interactive ? await promptForMissingOptions(parsed) : completeInitArgs(parsed);
+    const paths = {
+        homeDir: deps.homeDir ?? env.HOME ?? homedir(),
+        cwd: deps.cwd ?? process.cwd(),
+    };
+    const steps = buildInitPlan(options, paths);
+    const summary = renderPlanSummary(options, steps);
+    if (interactive) {
+        note(summary, options.dryRun ? 'Dry run' : 'Ready to configure Speko MCP');
+    }
+    else {
+        stdout.write(`${summary}\n`);
+    }
+    if (options.dryRun) {
+        stdout.write(`${renderManualSnippets(steps)}\n`);
+        printApiKeyReminder(options, env, stdout);
+        return;
+    }
+    if (!options.yes) {
+        const shouldApply = await confirm({ message: 'Apply these changes?' });
+        if (isCancel(shouldApply) || !shouldApply) {
+            cancelInit('No changes applied.');
+            return;
+        }
+    }
+    const applied = await applyInitPlan(steps, {
+        timestamp: deps.timestamp ?? defaultTimestamp,
+        runCommand: deps.runCommand ?? runExternalCommand,
+    });
+    const resultText = renderAppliedSteps(applied);
+    if (interactive) {
+        outro(resultText);
+    }
+    else {
+        stdout.write(`${resultText}\n`);
+    }
+    stdout.write(`${renderManualSnippets(steps.filter((step) => step.kind === 'manual'))}\n`);
+    stdout.write(`${renderFailedManualSnippets(applied)}\n`);
+    printApiKeyReminder(options, env, stdout);
+    const failures = applied.filter((step) => !step.ok);
+    if (failures.length > 0) {
+        stderr.write(`Some selected tools were not configured automatically. Use the printed manual snippets for those tools.\n`);
+    }
+}
+async function promptForMissingOptions(parsed) {
+    intro('Configure Speko MCP');
+    const access = parsed.access ??
+        (await promptValue(select({
+            message: 'Which Speko MCP endpoint do you want?',
+            options: [
+                {
+                    value: 'full',
+                    label: 'Full Speko account access',
+                    hint: 'private actions like balance, logs, builds, tests, deploys, plus docs',
+                },
+                {
+                    value: 'docs',
+                    label: 'Public docs and scaffolds only',
+                    hint: 'no sign-in; docs, package guidance, recommendations, and example scaffolds',
+                },
+            ],
+        })));
+    const auth = access === 'full'
+        ? (parsed.auth ??
+            (await promptValue(select({
+                message: 'How should full access authenticate?',
+                options: [
+                    { value: 'oauth', label: 'OAuth', hint: 'recommended when your tool supports it' },
+                    { value: 'api-key', label: 'SPEKO_API_KEY', hint: 'uses an environment variable' },
+                ],
+            }))))
+        : undefined;
+    const tools = parsed.tools ??
+        (await promptValue(multiselect({
+            message: 'Which coding tools should be configured?',
+            required: true,
+            initialValues: [...DEFAULT_SELECTED_TOOLS],
+            options: TOOL_SPECS.map((spec) => ({ value: spec.tool, label: spec.label })),
+        })));
+    const scope = parsed.scope ??
+        (await promptValue(select({
+            message: 'Where should supported configs be written?',
+            initialValue: DEFAULT_SCOPE,
+            options: [
+                { value: 'project', label: 'Current project config' },
+                { value: 'user', label: 'Global/user config' },
+            ],
+        })));
+    return {
+        access,
+        auth,
+        tools,
+        scope,
+        dryRun: parsed.dryRun,
+        yes: parsed.yes,
+    };
+}
+async function promptValue(value) {
+    const resolved = await value;
+    if (isCancel(resolved)) {
+        cancelInit('No changes applied.');
+        throw new Error('Init cancelled.');
+    }
+    return resolved;
+}
+function cancelInit(message) {
+    log.warn(message);
+    outro('Cancelled');
+}
+async function applyInitPlan(steps, deps) {
+    const applied = [];
+    const timestamp = deps.timestamp();
+    for (const step of steps) {
+        if (step.kind === 'manual') {
+            applied.push({ label: step.label, ok: true, message: 'Manual instructions printed.' });
+            continue;
+        }
+        if (step.kind === 'command') {
+            const result = deps.runCommand(step.command);
+            applied.push({
+                label: step.label,
+                ok: result.ok,
+                message: result.message,
+                manualSnippet: result.ok ? undefined : step.manualSnippet,
+            });
+            continue;
+        }
+        const existing = existsSync(step.path) ? readFileSync(step.path, 'utf8') : undefined;
+        const next = step.build(existing);
+        if (!next.ok) {
+            applied.push({
+                label: step.label,
+                ok: false,
+                message: next.reason,
+                manualSnippet: next.manualSnippet,
+            });
+            continue;
+        }
+        if (existing === next.content) {
+            applied.push({ label: step.label, ok: true, message: `Already up to date: ${step.path}` });
+            continue;
+        }
+        mkdirSync(dirname(step.path), { recursive: true });
+        if (existing !== undefined) {
+            const backupPath = `${step.path}.${timestamp}.bak`;
+            await copyFile(step.path, backupPath);
+        }
+        writeFileSync(step.path, next.content);
+        applied.push({ label: step.label, ok: true, message: `Updated ${step.path}` });
+    }
+    return applied;
+}
+function buildClaudeStep(options, endpoint, apiKeyAuth) {
+    const manualSnippet = claudeSnippet(endpoint, options.scope, apiKeyAuth);
+    if (apiKeyAuth) {
+        return {
+            kind: 'manual',
+            tool: 'claude',
+            label: 'Claude Code',
+            manualSnippet,
+        };
+    }
+    return {
+        kind: 'command',
+        tool: 'claude',
+        label: 'Claude Code',
+        command: [
+            'claude',
+            'mcp',
+            'add',
+            '--transport',
+            'http',
+            '--scope',
+            options.scope,
+            'speko',
+            endpoint,
+        ],
+        manualSnippet,
+        postInstall: options.access === 'full' ? 'In Claude Code, run /mcp and complete sign-in.' : undefined,
+    };
+}
+function updateJsonc(existing, path, value, manualSnippet) {
+    const source = existing?.trim() ? existing : '{}\n';
+    const errors = [];
+    const parsed = parseJsonc(source, errors, { allowTrailingComma: true, disallowComments: false });
+    if (errors.length > 0) {
+        return {
+            ok: false,
+            reason: `Could not parse existing JSON/JSONC config.`,
+            manualSnippet,
+        };
+    }
+    if (!isRecord(parsed)) {
+        return {
+            ok: false,
+            reason: 'Existing JSON/JSONC config root is not an object.',
+            manualSnippet,
+        };
+    }
+    const edits = modify(source, [...path], value, {
+        formattingOptions: {
+            insertSpaces: true,
+            tabSize: 2,
+            eol: '\n',
+        },
+    });
+    return { ok: true, content: ensureTrailingNewline(applyEdits(source, edits)) };
+}
+function codexSnippet(endpoint, apiKeyAuth) {
+    return `[mcp_servers.speko]
+url = "${endpoint}"${apiKeyAuth ? '\nbearer_token_env_var = "SPEKO_API_KEY"' : ''}`;
+}
+function openCodeSnippet(endpoint, apiKeyAuth) {
+    const server = apiKeyAuth
+        ? `{
+      "type": "remote",
+      "url": "${endpoint}",
+      "oauth": false,
+      "headers": {
+        "Authorization": "Bearer {env:SPEKO_API_KEY}"
+      },
+      "enabled": true
+    }`
+        : `{
+      "type": "remote",
+      "url": "${endpoint}",
+      "enabled": true
+    }`;
+    return `{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "speko": ${server}
+  }
+}`;
+}
+function cursorSnippet(endpoint, apiKeyAuth) {
+    const server = apiKeyAuth
+        ? `{
+      "url": "${endpoint}",
+      "headers": {
+        "Authorization": "Bearer $${'{env:SPEKO_API_KEY}'}"
+      }
+    }`
+        : `{
+      "url": "${endpoint}"
+    }`;
+    return `{
+  "mcpServers": {
+    "speko": ${server}
+  }
+}`;
+}
+function claudeSnippet(endpoint, scope, apiKeyAuth) {
+    return apiKeyAuth
+        ? `claude mcp add --transport http --scope ${scope} speko ${endpoint} \\
+  --header "Authorization: Bearer sk_live_xxx"`
+        : `claude mcp add --transport http --scope ${scope} speko ${endpoint}`;
+}
+function otherClientSnippet(endpoint, access, apiKeyAuth) {
+    const auth = access === 'docs'
+        ? 'Authentication: None'
+        : apiKeyAuth
+            ? 'API key auth: Send Authorization: Bearer sk_live_xxx'
+            : "OAuth: Use the client's OAuth flow";
+    return `Name: speko
+URL: ${endpoint}
+${auth}`;
+}
+function renderManualSnippets(steps) {
+    const snippets = steps
+        .filter((step) => step.kind === 'manual')
+        .map((step) => `${step.label}:\n${step.manualSnippet}`);
+    return snippets.length > 0 ? `\nManual steps:\n\n${snippets.join('\n\n')}\n` : '';
+}
+function renderAppliedSteps(steps) {
+    return steps
+        .map((step) => `${step.ok ? 'OK' : 'SKIP'} ${step.label}: ${step.message}`)
+        .join('\n');
+}
+function renderFailedManualSnippets(steps) {
+    const snippets = steps
+        .filter((step) => !step.ok && step.manualSnippet)
+        .map((step) => `${step.label}:\n${step.manualSnippet}`);
+    return snippets.length > 0 ? `\nManual fallback:\n\n${snippets.join('\n\n')}\n` : '';
+}
+function printApiKeyReminder(options, env, stdout) {
+    if (!isApiKeyAuth(options) || env.SPEKO_API_KEY?.trim()) {
+        return;
+    }
+    stdout.write(`\nSPEKO_API_KEY is not set. Before using API-key auth, run:\n${apiKeyExportCommand(env.SHELL)}\n`);
+}
+function apiKeyExportCommand(shell) {
+    if (shell?.endsWith('/fish')) {
+        return 'set -gx SPEKO_API_KEY sk_live_xxx';
+    }
+    if (process.platform === 'win32') {
+        return '$env:SPEKO_API_KEY = "sk_live_xxx"';
+    }
+    return 'export SPEKO_API_KEY=sk_live_xxx';
+}
+function runExternalCommand(command) {
+    const result = spawnSync(command[0] ?? '', command.slice(1), {
+        encoding: 'utf8',
+        stdio: 'pipe',
+    });
+    if (result.error) {
+        return { ok: false, message: result.error.message };
+    }
+    if (result.status !== 0) {
+        return {
+            ok: false,
+            message: result.stderr.trim() || result.stdout.trim() || `Exited with ${result.status}`,
+        };
+    }
+    return { ok: true, message: `Ran ${formatCommand(command)}` };
+}
+function formatCommand(command) {
+    return command.map(shellQuote).join(' ');
+}
+function shellQuote(value) {
+    return /^[a-zA-Z0-9_./:@=-]+$/.test(value) ? value : JSON.stringify(value);
+}
+function defaultTimestamp() {
+    return new Date()
+        .toISOString()
+        .replace(/[-:]/g, '')
+        .replace(/\.\d{3}Z$/, 'Z');
+}
+function ensureTrailingNewline(value) {
+    return value.endsWith('\n') ? value : `${value}\n`;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function readFlagValue(argv, index, flag) {
+    const value = argv[index + 1];
+    if (!value || value.startsWith('--')) {
+        throw new Error(`Missing value for ${flag}`);
+    }
+    return value;
+}
+function readInlineFlagValue(arg) {
+    const value = arg.slice(arg.indexOf('=') + 1);
+    if (!value) {
+        throw new Error(`Missing value for ${arg.slice(0, arg.indexOf('='))}`);
+    }
+    return value;
+}
+function parseAccess(value) {
+    if (value === 'full' || value === 'docs')
+        return value;
+    throw new Error(`Invalid --access value: ${value}`);
+}
+function parseAuth(value) {
+    if (value === 'oauth' || value === 'api-key')
+        return value;
+    throw new Error(`Invalid --auth value: ${value}`);
+}
+function parseScope(value) {
+    if (value === 'user' || value === 'project')
+        return value;
+    throw new Error(`Invalid --scope value: ${value}`);
+}
+function parseTools(value) {
+    const tools = value
+        .split(',')
+        .map((item) => normalizeTool(item.trim()))
+        .filter((item) => Boolean(item));
+    if (tools.length === 0) {
+        throw new Error('At least one tool is required.');
+    }
+    return Array.from(new Set(tools));
+}
+function normalizeTool(value) {
+    if (!value)
+        return undefined;
+    if (value === 'claude-code' || value === 'claude_code')
+        return 'claude';
+    if (TOOL_LABELS.has(value))
+        return value;
+    throw new Error(`Invalid tool: ${value}`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spekoai/mcp",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Local stdio bridge for the hosted SpekoAI MCP server",
   "license": "MIT",
   "author": "Speko",
@@ -47,7 +47,10 @@
     "provenance": true
   },
   "dependencies": {
+    "@clack/prompts": "^1.4.0",
+    "jsonc-parser": "^3.3.1",
     "mcp-remote": "^0.1.38",
+    "smol-toml": "^1.6.1",
     "tslib": "^2.3.0"
   },
   "devDependencies": {