snaphost 1.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SnapHost
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,34 @@
+# snaphost
+
+Connect your AI agent to [SnapHost](https://snaphost.ai) in one command.
+
+```bash
+npx snaphost connect
+```
+
+It finds the agent clients installed on your machine and configures each one for the hosted
+SnapHost MCP server (`https://app.snaphost.ai/api/mcp`). No token or password is involved: the
+first time a client uses SnapHost, your browser opens so you can click **Authorize**.
+
+Supported clients: Claude Code, Cursor, VS Code, Windsurf, Codex CLI, Gemini CLI. For Claude on
+the web or the desktop app, it prints the two clicks you need instead.
+
+## Options
+
+```
+npx snaphost connect [--client <name>]... [--all] [--dry-run] [--endpoint <url>] [--json]
+```
+
+- `--client <name>`: configure only these clients (`claude-code`, `cursor`, `vscode`, `windsurf`,
+  `codex`, `gemini`). Repeatable.
+- `--all`: configure every supported client whether or not it is detected.
+- `--dry-run`: print what would change without writing or running anything.
+- `--endpoint <url>`: point at another SnapHost deployment.
+- `--json`: print the plan as JSON.
+
+Config files it edits (`~/.cursor/mcp.json`, `~/.codeium/windsurf/mcp_config.json`) keep every
+other entry; an existing `snaphost` entry is replaced and a `.bak` copy of the previous file is
+written first. Clients with their own CLI (Claude Code, VS Code, Codex, Gemini) are configured
+through that CLI.
+
+Docs: https://snaphost.ai/docs/mcp-server

package/dist/action.js

@@ -0,0 +1,13 @@
+export function describeAction(action) {
+    switch (action.kind) {
+        case 'exec':
+            return `run: ${action.argv.map(quote).join(' ')}`;
+        case 'merge-json':
+            return `write: ${action.path} (mcpServers.${action.key})`;
+        case 'instruction':
+            return action.text;
+    }
+}
+function quote(argument) {
+    return /[\s"']/.test(argument) ? `'${argument.replace(/'/g, "'\\''")}'` : argument;
+}

package/dist/argument.js

@@ -0,0 +1,51 @@
+import { clientNames } from './client.js';
+export const DEFAULT_ENDPOINT = 'https://app.snaphost.ai/api/mcp';
+export class UsageError extends Error {
+}
+export function parseConnectArguments(argv) {
+    const options = {
+        clients: [],
+        all: false,
+        dryRun: false,
+        endpoint: DEFAULT_ENDPOINT,
+        json: false,
+    };
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        switch (argument) {
+            case '--client': {
+                const name = argv[index + 1];
+                if (name === undefined || name.startsWith('--')) {
+                    throw new UsageError('--client needs a name');
+                }
+                if (!clientNames().includes(name)) {
+                    throw new UsageError(`Unknown client "${name}". Supported: ${clientNames().join(', ')}`);
+                }
+                options.clients.push(name);
+                index += 1;
+                break;
+            }
+            case '--all':
+                options.all = true;
+                break;
+            case '--dry-run':
+                options.dryRun = true;
+                break;
+            case '--json':
+                options.json = true;
+                break;
+            case '--endpoint': {
+                const endpoint = argv[index + 1];
+                if (endpoint === undefined || !/^https?:\/\//.test(endpoint)) {
+                    throw new UsageError('--endpoint needs an http(s) URL');
+                }
+                options.endpoint = endpoint;
+                index += 1;
+                break;
+            }
+            default:
+                throw new UsageError(`Unknown option "${argument}"`);
+        }
+    }
+    return options;
+}

package/dist/bin.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import { createRequire } from 'node:module';
+import { connect, EXIT_USAGE } from './connect.js';
+import { nodeEnvironment } from './node-environment.js';
+const USAGE = `snaphost <command>
+
+Commands:
+  connect    Configure your AI clients for the SnapHost MCP server
+             [--client <name>]... [--all] [--dry-run] [--endpoint <url>] [--json]
+
+Docs: https://snaphost.ai/docs/mcp-server`;
+function version() {
+    const manifest = createRequire(import.meta.url)('../package.json');
+    return manifest.version;
+}
+const [command, ...rest] = process.argv.slice(2);
+const environment = nodeEnvironment();
+switch (command) {
+    case 'connect':
+        process.exitCode = connect(rest, environment);
+        break;
+    case '--version':
+    case '-v':
+        environment.print(version());
+        break;
+    case '--help':
+    case '-h':
+    case undefined:
+        environment.print(USAGE);
+        break;
+    default:
+        environment.printError(`Unknown command "${command}"\n\n${USAGE}`);
+        process.exitCode = EXIT_USAGE;
+}

package/dist/client.js

@@ -0,0 +1,99 @@
+export const SERVER_NAME = 'snaphost';
+function homePath(environment, ...segments) {
+    return [environment.homeDirectory, ...segments].join('/');
+}
+// Each client is configured the way its own documentation prescribes: through its CLI where it
+// has one (so its own validation and scoping apply), and by editing its config file where it does
+// not. User scope everywhere, so the connection works in every project.
+export const CLIENTS = [
+    {
+        name: 'claude-code',
+        label: 'Claude Code',
+        detect: environment => environment.hasExecutable('claude'),
+        plan: endpoint => [
+            {
+                kind: 'exec',
+                argv: [
+                    'claude',
+                    'mcp',
+                    'add',
+                    '--transport',
+                    'http',
+                    '--scope',
+                    'user',
+                    SERVER_NAME,
+                    endpoint,
+                ],
+            },
+        ],
+    },
+    {
+        name: 'cursor',
+        label: 'Cursor',
+        detect: environment => environment.directoryExists(homePath(environment, '.cursor')),
+        plan: (endpoint, environment) => [
+            {
+                kind: 'merge-json',
+                path: homePath(environment, '.cursor', 'mcp.json'),
+                key: SERVER_NAME,
+                value: { url: endpoint },
+            },
+        ],
+    },
+    {
+        name: 'vscode',
+        label: 'VS Code',
+        detect: environment => environment.hasExecutable('code'),
+        plan: endpoint => [
+            {
+                kind: 'exec',
+                argv: [
+                    'code',
+                    '--add-mcp',
+                    JSON.stringify({ name: SERVER_NAME, type: 'http', url: endpoint }),
+                ],
+            },
+        ],
+    },
+    {
+        name: 'windsurf',
+        label: 'Windsurf',
+        detect: environment => environment.directoryExists(homePath(environment, '.codeium', 'windsurf')),
+        plan: (endpoint, environment) => [
+            {
+                kind: 'merge-json',
+                path: homePath(environment, '.codeium', 'windsurf', 'mcp_config.json'),
+                key: SERVER_NAME,
+                value: { serverUrl: endpoint },
+            },
+        ],
+    },
+    {
+        name: 'codex',
+        label: 'Codex CLI',
+        detect: environment => environment.hasExecutable('codex'),
+        plan: endpoint => [
+            { kind: 'exec', argv: ['codex', 'mcp', 'add', SERVER_NAME, '--url', endpoint] },
+        ],
+    },
+    {
+        name: 'gemini',
+        label: 'Gemini CLI',
+        detect: environment => environment.hasExecutable('gemini'),
+        plan: endpoint => [
+            { kind: 'exec', argv: ['gemini', 'mcp', 'add', '--transport', 'http', SERVER_NAME, endpoint] },
+        ],
+    },
+];
+export function clientNames() {
+    return CLIENTS.map(client => client.name);
+}
+// Claude on the web and the desktop app take connectors through account settings, which no
+// command can reach, so they get the two clicks in words.
+export function manualConnectorInstruction(endpoint) {
+    return {
+        kind: 'instruction',
+        text: 'Claude on the web or desktop: open Settings, Connectors, Add custom connector, and paste ' +
+            `${endpoint} as the URL. Claude detects OAuth; leave the defaults and click Add.`,
+    };
+}

package/dist/connect.js

@@ -0,0 +1,88 @@
+import { describeAction } from './action.js';
+import { parseConnectArguments, UsageError } from './argument.js';
+import { CLIENTS, clientNames, manualConnectorInstruction } from './client.js';
+import { ExecutionError, executeAction } from './execute.js';
+export const EXIT_OK = 0;
+export const EXIT_FAILED = 1;
+export const EXIT_USAGE = 2;
+const AUTHORIZE_LINE = 'Done. The first time each client uses SnapHost, your browser opens: click Authorize and ' +
+    'you are connected. No token or password is ever needed.';
+// Detect, plan, then either print or apply: `--dry-run` and `--json` stop after the plan, which
+// is why nothing in the plan can touch the machine.
+export function connect(argv, environment) {
+    let options;
+    try {
+        options = parseConnectArguments(argv);
+    }
+    catch (error) {
+        if (error instanceof UsageError) {
+            environment.printError(error.message);
+            return EXIT_USAGE;
+        }
+        throw error;
+    }
+    const plans = planClients(options, environment);
+    if (options.json) {
+        environment.print(JSON.stringify(planReport(options.endpoint, plans), null, 2));
+        return EXIT_OK;
+    }
+    if (plans.length === 0) {
+        environment.print(`No supported AI client found. Supported: ${clientNames().join(', ')}. ` +
+            'Pass --client <name> or --all to configure one anyway.');
+        environment.print(describeAction(manualConnectorInstruction(options.endpoint)));
+        return EXIT_OK;
+    }
+    if (options.dryRun) {
+        for (const plan of plans) {
+            environment.print(`${plan.client.label}:`);
+            for (const action of plan.actions) {
+                environment.print(`  ${describeAction(action)}`);
+            }
+        }
+        environment.print(describeAction(manualConnectorInstruction(options.endpoint)));
+        return EXIT_OK;
+    }
+    let failed = false;
+    for (const plan of plans) {
+        try {
+            for (const action of plan.actions) {
+                executeAction(action, environment);
+            }
+            environment.print(`Configured ${plan.client.label}.`);
+        }
+        catch (error) {
+            if (error instanceof ExecutionError) {
+                failed = true;
+                environment.printError(`${plan.client.label}: ${error.message}`);
+                continue;
+            }
+            throw error;
+        }
+    }
+    environment.print(describeAction(manualConnectorInstruction(options.endpoint)));
+    environment.print(AUTHORIZE_LINE);
+    return failed ? EXIT_FAILED : EXIT_OK;
+}
+function planClients(options, environment) {
+    return CLIENTS.filter(client => {
+        if (options.clients.length > 0) {
+            return options.clients.includes(client.name);
+        }
+        return options.all || client.detect(environment);
+    }).map(client => ({
+        client,
+        detected: client.detect(environment),
+        actions: client.plan(options.endpoint, environment),
+    }));
+}
+function planReport(endpoint, plans) {
+    return {
+        endpoint,
+        clients: plans.map(plan => ({
+            name: plan.client.name,
+            label: plan.client.label,
+            detected: plan.detected,
+            actions: plan.actions,
+        })),
+    };
+}

package/dist/environment.js

@@ -0,0 +1 @@
+export {};

package/dist/execute.js

@@ -0,0 +1,53 @@
+export class ExecutionError extends Error {
+}
+export function executeAction(action, environment) {
+    switch (action.kind) {
+        case 'exec': {
+            const status = environment.run(action.argv);
+            if (status !== 0) {
+                throw new ExecutionError(`${action.argv[0]} exited with status ${status}`);
+            }
+            return;
+        }
+        case 'merge-json':
+            mergeServerEntry(action.path, action.key, action.value, environment);
+            return;
+        case 'instruction':
+            environment.print(action.text);
+            return;
+    }
+}
+// The config file belongs to the user and may hold other servers and unrelated settings, so the
+// merge touches only `mcpServers.<key>` and keeps a copy of what was there before.
+function mergeServerEntry(path, key, value, environment) {
+    const existing = environment.fileExists(path) ? environment.readFile(path) : undefined;
+    const config = parseConfig(existing, path);
+    const servers = isRecord(config.mcpServers) ? config.mcpServers : {};
+    const next = { ...config, mcpServers: { ...servers, [key]: value } };
+    if (existing !== undefined) {
+        environment.writeFile(`${path}.bak`, existing);
+    }
+    else {
+        environment.makeDirectory(path.slice(0, path.lastIndexOf('/')));
+    }
+    environment.writeFile(path, `${JSON.stringify(next, null, 2)}\n`);
+}
+function parseConfig(content, path) {
+    if (content === undefined || content.trim() === '') {
+        return {};
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch {
+        throw new ExecutionError(`${path} is not valid JSON; fix or remove it and run again`);
+    }
+    if (!isRecord(parsed)) {
+        throw new ExecutionError(`${path} must hold a JSON object; fix or remove it and run again`);
+    }
+    return parsed;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/node-environment.js

@@ -0,0 +1,29 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, join } from 'node:path';
+const WINDOWS = process.platform === 'win32';
+// Windows resolves `claude` to `claude.cmd`, which only a shell can start; elsewhere the argv
+// runs as given so no argument is ever re-parsed by a shell.
+export function nodeEnvironment() {
+    return {
+        homeDirectory: homedir().replace(/\\/g, '/'),
+        hasExecutable: name => onPath(name),
+        fileExists: path => existsSync(path) && statSync(path).isFile(),
+        directoryExists: path => existsSync(path) && statSync(path).isDirectory(),
+        readFile: path => readFileSync(path, 'utf8'),
+        writeFile: (path, content) => writeFileSync(path, content, 'utf8'),
+        makeDirectory: path => mkdirSync(path, { recursive: true }),
+        run: argv => {
+            const result = spawnSync(argv[0], argv.slice(1), { stdio: 'inherit', shell: WINDOWS });
+            return result.status ?? 1;
+        },
+        print: line => process.stdout.write(`${line}\n`),
+        printError: line => process.stderr.write(`${line}\n`),
+    };
+}
+function onPath(name) {
+    const directories = (process.env.PATH ?? '').split(delimiter).filter(Boolean);
+    const extensions = WINDOWS ? (process.env.PATHEXT ?? '.EXE;.CMD;.BAT').split(';') : [''];
+    return directories.some(directory => extensions.some(extension => existsSync(join(directory, `${name}${extension}`))));
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "snaphost",
+  "version": "1.3.0",
+  "description": "Connect your AI agent to SnapHost in one command: configures Claude Code, Cursor, VS Code, Windsurf, Codex CLI, and Gemini CLI for the hosted SnapHost MCP server.",
+  "keywords": [
+    "snaphost",
+    "mcp",
+    "model-context-protocol",
+    "claude-code",
+    "cursor",
+    "publish",
+    "share"
+  ],
+  "homepage": "https://snaphost.ai/docs/mcp-server",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/snaphost-ai/snaphost"
+  },
+  "license": "MIT",
+  "type": "module",
+  "bin": "dist/bin.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "yarn build",
+    "test": "vitest run --passWithNoTests",
+    "lint": "eslint ."
+  },
+  "devDependencies": {
+    "@types/node": "^24.12.0",
+    "typescript": "~5.9.3",
+    "vitest": "^4.1.0"
+  }
+}