@nimrobo/mcporter-remote 0.1.0

package/mcporter.schema.json

@@ -0,0 +1,263 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "mcpServers": {
+      "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "description": {
+            "description": "Human-readable description of the server",
+            "type": "string"
+          },
+          "baseUrl": {
+            "description": "Base URL for HTTP/SSE transport (camelCase)",
+            "type": "string"
+          },
+          "base_url": {
+            "description": "Base URL for HTTP/SSE transport (snake_case)",
+            "type": "string"
+          },
+          "url": {
+            "description": "Server URL for HTTP/SSE transport",
+            "type": "string"
+          },
+          "serverUrl": {
+            "description": "Server URL for HTTP/SSE transport (camelCase)",
+            "type": "string"
+          },
+          "server_url": {
+            "description": "Server URL for HTTP/SSE transport (snake_case)",
+            "type": "string"
+          },
+          "command": {
+            "description": "Command to spawn for stdio transport (string or array of arguments)",
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            ]
+          },
+          "executable": {
+            "description": "Executable path for stdio transport",
+            "type": "string"
+          },
+          "args": {
+            "description": "Arguments to pass to the stdio command",
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "headers": {
+            "description": "HTTP headers for requests. Supports $VAR and $env:VAR placeholders",
+            "type": "object",
+            "propertyNames": {
+              "type": "string"
+            },
+            "additionalProperties": {
+              "type": "string"
+            }
+          },
+          "env": {
+            "description": "Environment variables for stdio commands. Supports $VAR and fallback syntax",
+            "type": "object",
+            "propertyNames": {
+              "type": "string"
+            },
+            "additionalProperties": {
+              "type": "string"
+            }
+          },
+          "auth": {
+            "description": "Authentication method (e.g., \"oauth\")",
+            "type": "string"
+          },
+          "tokenCacheDir": {
+            "description": "Directory for caching OAuth tokens (camelCase)",
+            "type": "string"
+          },
+          "token_cache_dir": {
+            "description": "Directory for caching OAuth tokens (snake_case)",
+            "type": "string"
+          },
+          "clientName": {
+            "description": "Client identifier for server telemetry (camelCase)",
+            "type": "string"
+          },
+          "client_name": {
+            "description": "Client identifier for server telemetry (snake_case)",
+            "type": "string"
+          },
+          "oauthRedirectUrl": {
+            "description": "Custom OAuth redirect URL (camelCase)",
+            "type": "string"
+          },
+          "oauth_redirect_url": {
+            "description": "Custom OAuth redirect URL (snake_case)",
+            "type": "string"
+          },
+          "oauthScope": {
+            "description": "OAuth scope override (camelCase)",
+            "type": "string"
+          },
+          "oauth_scope": {
+            "description": "OAuth scope override (snake_case)",
+            "type": "string"
+          },
+          "oauthCommand": {
+            "description": "Custom OAuth command configuration for stdio servers (camelCase)",
+            "type": "object",
+            "properties": {
+              "args": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Arguments for the OAuth command"
+              }
+            },
+            "required": [
+              "args"
+            ],
+            "additionalProperties": false
+          },
+          "oauth_command": {
+            "description": "Custom OAuth command configuration for stdio servers (snake_case)",
+            "type": "object",
+            "properties": {
+              "args": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Arguments for the OAuth command"
+              }
+            },
+            "required": [
+              "args"
+            ],
+            "additionalProperties": false
+          },
+          "bearerToken": {
+            "description": "Static bearer token for authentication (camelCase)",
+            "type": "string"
+          },
+          "bearer_token": {
+            "description": "Static bearer token for authentication (snake_case)",
+            "type": "string"
+          },
+          "bearerTokenEnv": {
+            "description": "Environment variable name containing the bearer token (camelCase)",
+            "type": "string"
+          },
+          "bearer_token_env": {
+            "description": "Environment variable name containing the bearer token (snake_case)",
+            "type": "string"
+          },
+          "lifecycle": {
+            "anyOf": [
+              {
+                "type": "string",
+                "const": "keep-alive",
+                "description": "Keep the server connection alive"
+              },
+              {
+                "type": "string",
+                "const": "ephemeral",
+                "description": "Connect only when needed"
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "mode": {
+                    "anyOf": [
+                      {
+                        "type": "string",
+                        "const": "keep-alive"
+                      },
+                      {
+                        "type": "string",
+                        "const": "ephemeral"
+                      }
+                    ],
+                    "description": "Connection lifecycle mode"
+                  },
+                  "idleTimeoutMs": {
+                    "description": "Idle timeout in milliseconds before disconnecting",
+                    "type": "integer",
+                    "exclusiveMinimum": 0,
+                    "maximum": 9007199254740991
+                  }
+                },
+                "required": [
+                  "mode"
+                ],
+                "additionalProperties": false
+              }
+            ],
+            "description": "Server connection lifecycle: keep-alive maintains persistent connections, ephemeral connects on-demand"
+          },
+          "logging": {
+            "description": "Logging configuration for the server",
+            "type": "object",
+            "properties": {
+              "daemon": {
+                "description": "Daemon-specific logging configuration",
+                "type": "object",
+                "properties": {
+                  "enabled": {
+                    "description": "Enable daemon logging for this server",
+                    "type": "boolean"
+                  }
+                },
+                "additionalProperties": false
+              }
+            },
+            "additionalProperties": false
+          }
+        },
+        "additionalProperties": false,
+        "description": "MCP server definition supporting both HTTP/SSE and stdio transports"
+      },
+      "description": "Map of server names to their configurations"
+    },
+    "imports": {
+      "description": "Editor configurations to import servers from. Omit to use defaults, or set to [] to disable imports",
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": [
+          "cursor",
+          "claude-code",
+          "claude-desktop",
+          "codex",
+          "windsurf",
+          "opencode",
+          "vscode"
+        ],
+        "description": "Supported editor/client configurations to import MCP servers from"
+      }
+    },
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema URL for IDE validation and autocomplete"
+    }
+  },
+  "required": [
+    "mcpServers"
+  ],
+  "additionalProperties": false,
+  "description": "mcporter configuration file schema",
+  "$id": "https://raw.githubusercontent.com/steipete/mcporter/main/mcporter.schema.json"
+}

package/package.json

@@ -0,0 +1,105 @@
+{
+  "name": "@nimrobo/mcporter-remote",
+  "version": "0.1.0",
+  "description": "TypeScript runtime and CLI for connecting to configured Model Context Protocol servers.",
+  "packageManager": "pnpm@10.22.0",
+  "pnpm": {
+    "overrides": {
+      "body-parser": "2.2.1"
+    }
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./cli": {
+      "import": "./dist/cli.js",
+      "types": "./dist/cli.d.ts"
+    }
+  },
+  "bin": {
+    "mcporter": "dist/cli.js"
+  },
+  "scripts": {
+    "mcporter": "tsx src/cli.ts",
+    "mcp": "pnpm exec tsx src/cli.ts",
+    "build": "tsc -p tsconfig.build.json",
+    "build:bun": "bun scripts/build-bun.ts",
+    "check": "pnpm lint:biome && pnpm lint:oxlint && pnpm typecheck",
+    "lint": "pnpm check",
+    "lint:biome": "biome check",
+    "lint:oxlint": "oxlint --type-aware --tsconfig tsconfig.json --max-warnings=0",
+    "typecheck": "tsgo --project tsconfig.json --noEmit",
+    "test": "cross-env MCPORTER_TEST_REPORTER=quiet pnpm test:verbose",
+    "test:quiet": "cross-env MCPORTER_TEST_REPORTER=quiet pnpm test:verbose",
+    "test:verbose": "node scripts/test-runner.js",
+    "test:live": "MCP_LIVE_TESTS=1 vitest run tests/live",
+    "clean": "rimraf dist",
+    "dev": "tsc -w -p tsconfig.build.json",
+    "prepublishOnly": "pnpm check && pnpm test && pnpm build",
+    "docs:list": "pnpm exec tsx scripts/docs-list.ts",
+    "generate:schema": "tsx scripts/generate-json-schema.ts",
+    "mcporter:list": "pnpm exec tsx src/cli.ts list",
+    "mcporter:call": "pnpm exec tsx src/cli.ts call"
+  },
+  "dependencies": {
+    "@iarna/toml": "^2.2.5",
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "acorn": "^8.16.0",
+    "commander": "^14.0.3",
+    "es-toolkit": "^1.45.0",
+    "jsonc-parser": "^3.3.1",
+    "ora": "^9.3.0",
+    "rolldown": "1.0.0-rc.6",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.5",
+    "@types/estree": "^1.0.8",
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.3.3",
+    "@typescript/native-preview": "7.0.0-dev.20260302.1",
+    "@vitest/coverage-v8": "^4.0.18",
+    "bun-types": "^1.3.10",
+    "cross-env": "^10.1.0",
+    "express": "^5.2.1",
+    "oxlint": "^1.51.0",
+    "oxlint-tsgolint": "^0.15.0",
+    "rimraf": "^6.1.3",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "engines": {
+    "node": ">=20.11.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Nimrobo/mcporter-remote"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "cli",
+    "sweetistics"
+  ],
+  "homepage": "https://nimroboai.com",
+  "author": "Nimrobo AI",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devEngines": {
+    "runtime": [
+      {
+        "name": "node",
+        "version": ">=20"
+      }
+    ]
+  }
+}

package/pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+onlyBuiltDependencies:
+  - esbuild

package/runner

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# Guardrail shim that wraps every command with the Bun runner; when behavior changes, record the note via ./scripts/committer \"docs: update AGENTS for runner\" \"AGENTS.md\" so fellow agents keep pace.
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+if ! command -v bun >/dev/null 2>&1; then
+  echo "[runner] bun is required but was not found on PATH." >&2
+  echo "[runner] Install Bun from https://bun.sh and retry." >&2
+  exit 1
+fi
+
+exec bun "$ROOT_DIR/scripts/runner.ts" "$@"

package/scripts/agent-send.ts

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+
+/**
+ * Lightweight helper to send a one-off message to a tmux-based agent session.
+ *
+ * Usage:
+ *   bun scripts/agent-send.ts --session claude-haiku -- "/model"
+ *
+ * Options:
+ *   --session NAME             Target tmux session (or session:window.pane)
+ *   --entry single|double|none How many Enter keys to send (default single)
+ *   --escape                   Send ESC before typing (to interrupt/resume)
+ *   --wait-ms N                Extra wait (ms) after typing before Enter
+ */
+
+import { spawnSync } from 'node:child_process';
+
+type EntryMode = 'single' | 'double' | 'none';
+
+interface CliOptions {
+  session: string;
+  entry: EntryMode;
+  escape: boolean;
+  waitMs: number;
+  message: string;
+}
+
+function usage(message?: string): never {
+  if (message) {
+    console.error(`Error: ${message}`);
+  }
+  console.error(`\
+Usage: bun scripts/agent-send.ts --session <name[:window[.pane]]> [--entry single|double|none] [--escape] [--wait-ms N] -- "<message>"
+
+Examples:
+  bun scripts/agent-send.ts --session claude-haiku -- "/model"
+  bun scripts/agent-send.ts --session ma-worker-1 --escape --entry double -- "Continue and focus on API routes"
+`);
+  process.exit(1);
+}
+
+function parseArgs(argv: string[]): CliOptions {
+  let session: string | undefined;
+  let entry: EntryMode = 'single';
+  let shouldEscape = false;
+  let waitMs = 400;
+  const literalSeparator = argv.indexOf('--');
+  const optionPart = literalSeparator === -1 ? argv : argv.slice(0, literalSeparator);
+  const literalPart = literalSeparator === -1 ? [] : argv.slice(literalSeparator + 1);
+
+  for (let i = 0; i < optionPart.length; i += 1) {
+    const token = optionPart[i];
+    if (typeof token !== 'string' || !token.startsWith('--')) {
+      usage(`Unexpected argument: ${token ?? ''}`);
+    }
+    const key = token.slice(2);
+    switch (key) {
+      case 'session': {
+        const value = optionPart[i + 1];
+        if (!value) {
+          usage('--session requires a value');
+        }
+        session = value;
+        i += 1;
+        break;
+      }
+      case 'entry': {
+        const value = optionPart[i + 1];
+        if (value !== 'single' && value !== 'double' && value !== 'none') {
+          usage(`Unknown entry mode: ${value}`);
+        }
+        entry = value;
+        i += 1;
+        break;
+      }
+      case 'escape': {
+        shouldEscape = true;
+        break;
+      }
+      case 'wait-ms': {
+        const value = optionPart[i + 1];
+        if (!value || Number.isNaN(Number.parseInt(value, 10))) {
+          usage('--wait-ms requires an integer value');
+        }
+        waitMs = Number.parseInt(value, 10);
+        i += 1;
+        break;
+      }
+      default:
+        usage(`Unknown option: --${key}`);
+    }
+  }
+
+  const message = literalPart.join(' ').trim();
+  if (!session) {
+    usage('Missing --session');
+  }
+  if (!message) {
+    usage('Missing message (provide text after -- separator)');
+  }
+
+  return { session, entry, escape: shouldEscape, waitMs, message };
+}
+
+function runTmux(args: string[], allowFailure = false): string {
+  const result = spawnSync('tmux', args, { encoding: 'utf8' });
+  if (result.error) {
+    if (allowFailure) {
+      return '';
+    }
+    throw result.error;
+  }
+  if (result.status !== 0) {
+    if (allowFailure) {
+      return result.stderr?.trim() ?? '';
+    }
+    throw new Error(`tmux ${args.join(' ')} failed: ${result.stderr?.trim()}`);
+  }
+  return result.stdout?.trimEnd() ?? '';
+}
+
+function ensureSession(target: string): void {
+  const session = target.split(':')[0] ?? target;
+  const result = spawnSync('tmux', ['has-session', '-t', session]);
+  if (result.status !== 0) {
+    usage(`tmux session '${session}' not found. Start it first (e.g., tmux new-session -s ${session} ...)`);
+  }
+}
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+async function sendMessage(options: CliOptions): Promise<void> {
+  ensureSession(options.session);
+
+  if (options.escape) {
+    runTmux(['send-keys', '-t', options.session, 'Escape'], true);
+    await sleep(200);
+  }
+
+  // Clear existing prompt
+  runTmux(['send-keys', '-t', options.session, 'Escape'], true);
+  await sleep(120);
+  runTmux(['send-keys', '-t', options.session, 'C-u'], true);
+  await sleep(120);
+
+  // Type the message
+  runTmux(['send-keys', '-t', options.session, '-l', options.message], true);
+  await sleep(Math.max(120, options.waitMs));
+
+  // Send Enter(s)
+  const pressEnter = () => runTmux(['send-keys', '-t', options.session, 'C-m'], true);
+  switch (options.entry) {
+    case 'single':
+      pressEnter();
+      break;
+    case 'double':
+      pressEnter();
+      await sleep(200);
+      pressEnter();
+      break;
+    case 'none':
+      break;
+    default: {
+      const _never: never = options.entry;
+      usage('Unsupported entry mode');
+    }
+  }
+
+  await sleep(600);
+  const tail = runTmux(['capture-pane', '-pt', options.session, '-S', '-6'], true);
+  console.log(tail);
+}
+
+try {
+  const options = parseArgs(process.argv.slice(2));
+  await sendMessage(options);
+} catch (error) {
+  usage(error instanceof Error ? error.message : String(error));
+}

package/scripts/build-bun.ts

@@ -0,0 +1,125 @@
+#!/usr/bin/env bun
+/**
+ * Build a self-contained mcporter binary using Bun's --compile mode.
+ * Mirrors the poltergeist release flow so we can dual-publish via npm + Homebrew.
+ */
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+interface Options {
+  readonly target?: string;
+  readonly bytecode: boolean;
+  readonly minify: boolean;
+  readonly output?: string;
+}
+
+// parseArgs walks CLI flags and produces normalized build options.
+function parseArgs(argv: string[]): Options {
+  let target: string | undefined;
+  let bytecode = false;
+  let minify = true;
+  let output: string | undefined;
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token) {
+      continue;
+    }
+    if (token === '--target') {
+      target = requireValue(token, argv[++index]);
+      continue;
+    }
+    if (token === '--bytecode') {
+      bytecode = true;
+      continue;
+    }
+    if (token === '--no-minify') {
+      minify = false;
+      continue;
+    }
+    if (token === '--output') {
+      output = requireValue(token, argv[++index]);
+      continue;
+    }
+    throw new Error(`Unknown flag "${token}"`);
+  }
+
+  return { target, bytecode, minify, output };
+}
+
+// requireValue asserts that a flag includes a value.
+function requireValue(flag: string, value: string | undefined): string {
+  if (!value) {
+    throw new Error(`${flag} requires a value`);
+  }
+  return value;
+}
+
+// main orchestrates the Bun compile flow for the mcporter binary.
+async function main(): Promise<void> {
+  const options = parseArgs(process.argv.slice(2));
+  const projectRoot = path.join(fs.realpathSync(path.dirname(new URL(import.meta.url).pathname)), '..');
+  const distDir = path.join(projectRoot, 'dist-bun');
+  if (!fs.existsSync(distDir)) {
+    fs.mkdirSync(distDir, { recursive: true });
+  }
+
+  const outputPath = options.output
+    ? path.resolve(options.output)
+    : path.join(distDir, options.target ? `mcporter-${options.target}` : 'mcporter');
+
+  const buildArgs = ['build', path.join(projectRoot, 'src/cli.ts'), '--compile', '--outfile', outputPath];
+
+  if (options.minify) {
+    buildArgs.push('--minify');
+  }
+  if (options.bytecode) {
+    buildArgs.push('--bytecode');
+  }
+  if (options.target) {
+    buildArgs.push('--target', options.target);
+  }
+
+  console.log(`Building mcporter binary → ${outputPath}`);
+  const result = spawnSync('bun', buildArgs, { stdio: 'inherit' });
+  if (result.status !== 0) {
+    throw new Error(`bun build exited with status ${result.status ?? 'unknown'}`);
+  }
+
+  if (process.platform !== 'win32') {
+    fs.chmodSync(outputPath, 0o755);
+  }
+
+  try {
+    const sizeBytes = fs.statSync(outputPath).size;
+    const human = formatSize(sizeBytes);
+    console.log(`✅ Built ${outputPath} (${human})`);
+  } catch {
+    console.log(`✅ Built ${outputPath}`);
+  }
+}
+
+function formatSize(bytes: number): string {
+  if (bytes < 1024) {
+    return `${bytes} B`;
+  }
+  if (bytes < 1024 ** 2) {
+    return `${(bytes / 1024).toFixed(1)} KB`;
+  }
+  if (bytes < 1024 ** 3) {
+    return `${(bytes / 1024 ** 2).toFixed(1)} MB`;
+  }
+  return `${(bytes / 1024 ** 3).toFixed(1)} GB`;
+}
+
+main().catch((error) => {
+  console.error('mcporter Bun build failed.');
+  if (error instanceof Error) {
+    console.error(error.message);
+  } else {
+    console.error(error);
+  }
+  process.exit(1);
+});