mikser-io-mcp 0.2.0 → 1.0.0

package/README.md

@@ -15,27 +15,67 @@ MCP (Model Context Protocol) substrate and tools for [mikser-io](https://github.
 npm install mikser-io-mcp
 ```
 
-Peer dependencies: `mikser-io ^8.2.0`, `zod ^4.0.0`.
+Peer dependencies: `mikser-io ^9.0.0`, `zod ^4.0.0`.
 
 ## Activate
 
-Add `'mcp'` to your mikser project's plugins array. **List it FIRST** — the plugin factory creates `runtime.options.mcp` synchronously so any plugins that register tools (api, layouts, refs, vector, etc.) can gate on it at their own `onLoaded` hook:
+Import the `mcp` factory and call it **first** in your mikser project's plugins array — the closure runs synchronously and creates `runtime.options.mcp` so any plugins that register tools (api, layouts, refs, vector, etc.) can gate on it at their own `onLoaded` hook:
 
 ```js
 // mikser.config.js
+import { mcp } from 'mikser-io-mcp'
+
 export default {
-    plugins: ['mcp', /* … your other plugins */],
-    mcp: {
-        path: '/mcp',          // optional; default '/mcp' (also serves as the base for `endpoints` below)
-        endpoints: { /* … */ } // optional; same shape as the in-core era
-    },
+    plugins: [
+        mcp({
+            path: '/mcp',          // optional; default '/mcp' (also serves as the base for `endpoints` below)
+            endpoints: { /* … */ } // optional; same shape as the in-core era
+        }),
+        /* … your other plugins */
+    ],
 }
 ```
 
-If `runtime.config.mcp` is absent the plugin runs as a no-op (loads but creates no substrate, mounts no transport). That lets you list `'mcp'` in plugins without forcing config.
+Calling `mcp()` with no options is a no-op activation — the factory runs but creates no substrate and mounts no transport. To skip MCP entirely, leave the factory call out of `plugins`.
 
 Run mikser with `--server`; the MCP transport mounts at the configured path on the same Express server the api / preview / data plugins use.
 
+## Register with a client
+
+Once the plugin is installed in your mikser project, the package ships a CLI you can invoke via `npx` to connect MCP-speaking clients. Connector name + description are read automatically from the project's `package.json`.
+
+### Claude Desktop
+
+```bash
+npx mikser-io-mcp register claude                                  # default URL http://localhost:3001/mcp
+npx mikser-io-mcp register claude --url http://localhost:4000/mcp  # custom port
+npx mikser-io-mcp register claude --dry-run                        # show what would change
+npx mikser-io-mcp register claude --force                          # overwrite a different existing entry
+npx mikser-io-mcp register claude --unregister                     # remove the entry
+```
+
+Writes a `mcpServers` entry into Claude Desktop's per-OS config file:
+
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%/Claude/claude_desktop_config.json`
+- Linux: `~/.config/Claude/claude_desktop_config.json`
+
+The entry launches `supergateway` (npx-installed on demand) as a stdio→streamable-HTTP bridge to your running mikser server. Fully quit + reopen Claude Desktop after registering.
+
+### ChatGPT
+
+```bash
+npx mikser-io-mcp register chatgpt --url https://YOUR-TUNNEL.example/mcp
+```
+
+ChatGPT's MCP integration is server-side — OpenAI's servers connect to your MCP endpoint directly. `localhost` is unreachable; you must expose mikser via a public tunnel (`ngrok http 3001`, Cloudflare Tunnel, etc.) before running this.
+
+The script doesn't write a file (ChatGPT has no local config). It prints the three fields (Name, Description, MCP Server URL) you paste into ChatGPT's UI: Settings → Connectors → Advanced → Developer mode → Create.
+
+Notes:
+- ChatGPT Developer mode + custom MCP connectors are **beta** and require a Plus / Pro / Business / Enterprise / Edu account.
+- Connectors don't auto-enable per chat — toggle on each new conversation.
+
 ## Documentation
 
 - [Full MCP tour, twelve worked scenarios, every tool and resource](./documentation/mcp.md)

package/index.js

@@ -655,20 +655,25 @@ 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.
-export default (core) => {
+// 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 function mcp(options = {}) {
+    return (core) => {
     // Use the runtime singleton imported above for substrate-internal
     // code paths (createMcpSubstrate etc. reference it directly via
     // closure). The factory arg `core.runtime` is the same object;
     // 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' }
-    }
+    // Mirror plugin options into runtime.config.mcp so non-plugin
+    // helpers (mountMcpOnExpress and friends, called by embedders that
+    // wire MCP up directly without `plugins:`) keep finding their
+    // config there. Plugin-side reads use `options.X` and never touch
+    // runtime.config.mcp.
+    runtime.config.mcp = options
 
     // Contribute MCP transport headers to engine's CORS arrays so
     // browser-side MCP clients (basic-host, mcp-ui, etc.) can read
@@ -686,7 +691,7 @@ export default (core) => {
     // runtime.options.mcp by the time those run. The mcp plugin MUST
     // be FIRST in the user's plugins array for that contract to hold.
     runtime.options.mcp = createMcpSubstrate()
-    runtime.options.mcpPath = runtime.config.mcp.path ?? '/mcp'
+    runtime.options.mcpPath = options.path ?? '/mcp'
 
     // Compose the MCP-UI surface in the same package — shell
     // resource, mikser_preview_ui, mikser_ui_action, mikser_preview_render,
@@ -916,7 +921,7 @@ export default (core) => {
         const mcp = runtime.options.mcp
 
         const { render: mcpRender } = useRenderer(runtime, {
-            defaultTimeout: runtime.config.mcp?.renderTimeout ?? 30_000,
+            defaultTimeout: options.renderTimeout ?? 30_000,
         })
 
         const ok = (data) => ({
@@ -1062,4 +1067,5 @@ export default (core) => {
     })
 
     return { name: 'mcp' }
+    }
 }

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "mikser-io-mcp",
-  "version": "0.2.0",
+  "version": "1.0.0",
   "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"
   ],
@@ -37,7 +41,7 @@
     "minimatch": "^10.0.3"
   },
   "peerDependencies": {
-    "mikser-io": "^8.2.0",
+    "mikser-io": "^9.0.0",
     "zod": "^4.0.0"
   },
   "devDependencies": {

package/scripts/chatgpt.js

@@ -0,0 +1,106 @@
+// 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 = {}
+    let expectUrl = false
+    for (const a of args) {
+        if (a.startsWith('--url=')) opts.url = a.slice(6)
+        else if (a === '--url')     expectUrl = true
+        else if (expectUrl)         { opts.url = a; 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,122 @@
+// 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 = {}
+    let expectUrl = false
+    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')       expectUrl = true
+        else if (expectUrl)           { opts.url = a; 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)
+}