mikser-io-mcp 0.2.0 → 0.2.1

package/index.js

@@ -655,9 +655,11 @@ function pinoLevelNumber(name) {
 //     endpoints: { ... }             // same shape as the previous mcp.endpoints
 //   }
 //
-// If runtime.config.mcp is absent, the plugin runs as a no-op (loads
-// but creates no substrate, mounts no transport). Lets users include
-// 'mcp' in plugins without forcing them to also provide config.
+// Presence in the plugins array IS the activation signal. The `mcp`
+// config block is for tuning (path, endpoints, renderTimeout). When
+// absent, defaults apply. For conditional activation, toggle the
+// plugins array — `...(process.env.MCP ? ['mcp'] : [])` — same shape
+// other plugins use.
 export default (core) => {
     // Use the runtime singleton imported above for substrate-internal
     // code paths (createMcpSubstrate etc. reference it directly via
@@ -665,10 +667,9 @@ export default (core) => {
     // they're both mikser-io's exported runtime singleton.
     const { onLoaded, useLogger } = core
 
-    if (!runtime.config.mcp) {
-        useLogger?.()?.debug('mikser-io-mcp loaded but runtime.config.mcp is absent — no substrate created')
-        return { name: 'mcp' }
-    }
+    // Default the config block so every downstream `runtime.config.mcp.X`
+    // reference Just Works without optional-chaining everywhere.
+    runtime.config.mcp = runtime.config.mcp ?? {}
 
     // Contribute MCP transport headers to engine's CORS arrays so
     // browser-side MCP clients (basic-host, mcp-ui, etc.) can read

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "mikser-io-mcp",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "MCP (Model Context Protocol) substrate and tools for mikser-io. Extracted from core to iterate on its own release cadence.",
   "main": "index.js",
   "type": "module",
+  "bin": {
+    "mikser-io-mcp": "./scripts/index.js"
+  },
   "files": [
     "index.js",
     "preview.js",
     "public",
+    "scripts",
     "README.md",
     "LICENSE"
   ],

package/scripts/chatgpt.js

@@ -0,0 +1,105 @@
+// register chatgpt — print copy-paste instructions for adding mikser
+// to ChatGPT Desktop as a custom MCP connector.
+//
+// ChatGPT does NOT use a local config file. Connectors live in the
+// user's OpenAI account, configured through the UI. OpenAI's servers
+// connect to the MCP endpoint directly, so localhost won't work — a
+// publicly-reachable HTTPS URL is mandatory.
+//
+// This script can't drop a file. The most it can do is render the
+// exact name / description / URL the user pastes into the UI.
+
+import { readFileSync, existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+function parseArgs(args) {
+    const opts = {}
+    for (const a of args) {
+        if (a.startsWith('--url=')) opts.url = a.slice(6)
+        else if (a === '--url')     opts._expectUrl = true
+        else if (opts._expectUrl)   { opts.url = a; opts._expectUrl = false }
+    }
+    return opts
+}
+
+function readProjectMeta() {
+    const pkgPath = resolve(process.cwd(), 'package.json')
+    if (!existsSync(pkgPath)) {
+        throw new Error(`No package.json in ${process.cwd()} — run this from inside a mikser project directory.`)
+    }
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+    if (!pkg.name) throw new Error('package.json has no "name" field — set one before registering.')
+    return {
+        name: pkg.name,
+        description: pkg.description ?? `MCP connector for ${pkg.name}.`,
+    }
+}
+
+export async function runChatGPT(args) {
+    const opts = parseArgs(args)
+
+    if (!opts.url) {
+        process.stderr.write(
+`! ChatGPT needs a publicly-reachable HTTPS URL.
+
+OpenAI's servers connect to your MCP endpoint directly — there's no stdio
+bridge, no localhost. You'll need to expose mikser via a tunnel first:
+
+  ngrok http 3001
+  # or:
+  cloudflared tunnel --url http://localhost:3001
+
+Then re-run with the public URL:
+
+  npx mikser-io-mcp register chatgpt --url https://YOUR-TUNNEL.example/mcp
+
+ChatGPT's Developer mode + custom MCP connectors are currently in BETA
+and require a Plus / Pro / Business / Enterprise / Edu account. See
+https://help.openai.com/en/articles/12584461 for the current state.
+`
+        )
+        process.exit(1)
+    }
+
+    const { name, description } = readProjectMeta()
+
+    process.stdout.write(
+`✓ Connector details for "${name}"
+
+ChatGPT doesn't have a local config file — connectors are added through
+the UI. Copy the three fields below.
+
+Open ChatGPT (Desktop or web) and navigate to:
+  Settings → Connectors → Advanced → Developer mode (toggle ON)
+  Click + Create
+
+Paste these into the form:
+
+  Name:            ${name}
+  Description:     ${description}
+  MCP Server URL:  ${opts.url}
+  Authentication:  None     (or your scheme of choice for production)
+
+Click Create. Then to use it:
+
+  1. Start a NEW chat (saved connectors are off-by-default per chat)
+  2. Open the composer's Developer Mode tool picker
+  3. Enable "${name}"
+  4. Try: "Use mikser_query_entities to show me everything in this catalog"
+
+Notes:
+  - Mikser must be running and the URL must be reachable from
+    OpenAI's servers (not just your machine).
+  - Connectors do NOT auto-enable per chat — toggle on for each new
+    conversation.
+  - Developer mode + arbitrary custom MCP connectors are BETA. Plus /
+    Pro / Business / Enterprise / Edu only; Free tier excluded.
+  - "ChatGPT Apps" is the GA but read-only variant of MCP integration;
+    this script targets the full read+write Developer mode beta.
+
+Reference:
+  https://help.openai.com/en/articles/12584461
+  https://developers.openai.com/apps-sdk/deploy/connect-chatgpt
+`
+    )
+}

package/scripts/claude.js

@@ -0,0 +1,121 @@
+// register claude — drop a connector entry into Claude Desktop's
+// config file so the app picks up the local mikser server.
+//
+// Claude Desktop launches MCP servers as stdio subprocesses, so we
+// register supergateway as the launcher — it bridges Claude's stdio
+// to mikser's streamable-HTTP endpoint. The mikser server must be
+// running for Claude to find anything.
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs'
+import { homedir, platform } from 'node:os'
+import { join, dirname, resolve } from 'node:path'
+
+const DEFAULT_URL = 'http://localhost:3001/mcp'
+
+function configPath() {
+    const home = homedir()
+    switch (platform()) {
+        case 'darwin': return join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json')
+        case 'win32':  return join(process.env.APPDATA ?? join(home, 'AppData', 'Roaming'), 'Claude', 'claude_desktop_config.json')
+        case 'linux':  return join(home, '.config', 'Claude', 'claude_desktop_config.json')
+        default:       throw new Error(`register-mcp: unsupported platform "${platform()}"`)
+    }
+}
+
+function parseArgs(args) {
+    const opts = {}
+    for (const a of args) {
+        if (a === '--unregister')     opts.unregister = true
+        else if (a === '--dry-run')   opts.dryRun = true
+        else if (a === '--force')     opts.force = true
+        else if (a.startsWith('--url=')) opts.url = a.slice(6)
+        else if (a === '--url')       opts._expectUrl = true
+        else if (opts._expectUrl)     { opts.url = a; opts._expectUrl = false }
+    }
+    return opts
+}
+
+function readProjectName() {
+    const pkgPath = resolve(process.cwd(), 'package.json')
+    if (!existsSync(pkgPath)) {
+        throw new Error(`No package.json in ${process.cwd()} — run this from inside a mikser project directory.`)
+    }
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+    if (!pkg.name) throw new Error('package.json has no "name" field — set one before registering.')
+    return pkg.name
+}
+
+export async function runClaude(args) {
+    const opts = parseArgs(args)
+    const name = readProjectName()
+    const url  = opts.url ?? DEFAULT_URL
+
+    const entry = {
+        command: 'npx',
+        args: ['-y', 'supergateway', '--streamableHttp', url],
+    }
+
+    const path = configPath()
+    let config = {}
+    let existed = false
+
+    if (existsSync(path)) {
+        existed = true
+        try {
+            config = JSON.parse(readFileSync(path, 'utf8'))
+        } catch (err) {
+            process.stderr.write(`! Existing Claude Desktop config at\n    ${path}\nis not valid JSON. Refusing to overwrite — fix it manually first.\n  Error: ${err.message}\n`)
+            process.exit(1)
+        }
+    }
+
+    config.mcpServers = config.mcpServers || {}
+
+    // Unregister branch.
+    if (opts.unregister) {
+        if (!(name in config.mcpServers)) {
+            process.stdout.write(`✓ "${name}" is not registered. Nothing to do.\n`)
+            return
+        }
+        if (opts.dryRun) {
+            process.stdout.write(`[dry-run] Would remove "${name}" from ${path}\n`)
+            return
+        }
+        delete config.mcpServers[name]
+        writeFileSync(path, JSON.stringify(config, null, 2) + '\n')
+        process.stdout.write(`✓ Removed "${name}" from ${path}\n  Restart Claude Desktop to apply.\n`)
+        return
+    }
+
+    // Idempotent — bail if already matching.
+    const existing = config.mcpServers[name]
+    if (existing && JSON.stringify(existing) === JSON.stringify(entry)) {
+        process.stdout.write(`✓ "${name}" is already registered with the matching config.\n  Nothing to change. (Use --force to re-write anyway.)\n`)
+        return
+    }
+    if (existing && !opts.force) {
+        process.stderr.write(`! "${name}" is already registered but with a different config:\n    ${JSON.stringify(existing)}\n  Wanted:\n    ${JSON.stringify(entry)}\n  Re-run with --force to overwrite.\n`)
+        process.exit(1)
+    }
+    if (opts.dryRun) {
+        process.stdout.write(`[dry-run] Would ${existing ? 'overwrite' : 'add'} "${name}" in ${path}:\n${JSON.stringify(entry, null, 2)}\n`)
+        return
+    }
+
+    config.mcpServers[name] = entry
+    mkdirSync(dirname(path), { recursive: true })
+    writeFileSync(path, JSON.stringify(config, null, 2) + '\n')
+
+    process.stdout.write(
+`✓ Registered "${name}" in
+    ${path}
+  ${existed ? '(merged into existing config)' : '(created new config file)'}
+
+Next steps:
+  1. Make sure mikser is running and reachable at ${url}
+  2. Restart Claude Desktop (fully quit, then reopen)
+  3. The mikser tools should appear in Claude's tool list
+
+To remove: npx mikser-io-mcp register claude --unregister
+`)
+}

package/scripts/index.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+// Bin entry for mikser-io-mcp. Dispatches subcommands.
+//
+// Usage:
+//   npx mikser-io-mcp register claude [--url URL] [--dry-run] [--force] [--unregister]
+//   npx mikser-io-mcp register chatgpt --url URL [--dry-run]
+//
+// Run from inside a mikser project directory — registration scripts
+// read ./package.json for the project name (used as the connector
+// label).
+
+import { runClaude }  from './claude.js'
+import { runChatGPT } from './chatgpt.js'
+
+function usage(code = 0) {
+    process.stdout.write(`mikser-io-mcp — register this project with an MCP-speaking client
+
+Usage:
+  npx mikser-io-mcp register claude [options]
+  npx mikser-io-mcp register chatgpt --url <URL>
+
+Common options:
+  --url=<URL>      MCP endpoint URL. Default for claude: http://localhost:3001/mcp.
+                   REQUIRED for chatgpt (must be publicly reachable HTTPS).
+  --dry-run        Show what would change without writing.
+
+Claude-only options:
+  --unregister     Remove this project's entry from Claude Desktop's config.
+  --force          Overwrite an existing entry that doesn't match.
+
+Run from inside a mikser project directory — the project's package.json
+is read for the connector name.
+`)
+    process.exit(code)
+}
+
+const [, , cmd, host, ...rest] = process.argv
+
+if (!cmd) usage(0)
+if (cmd === '-h' || cmd === '--help') usage(0)
+
+if (cmd !== 'register') {
+    process.stderr.write(`Unknown command: ${cmd}\n\n`)
+    usage(1)
+}
+
+if (host === 'claude') {
+    await runClaude(rest)
+} else if (host === 'chatgpt') {
+    await runChatGPT(rest)
+} else if (!host) {
+    process.stderr.write(`'register' needs a target host: claude | chatgpt\n\n`)
+    usage(1)
+} else {
+    process.stderr.write(`Unknown host: ${host}. Supported: claude, chatgpt.\n\n`)
+    usage(1)
+}