@feasibleone/blong-gogo 1.31.3 → 1.32.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [1.32.0](https://github.com/feasibleone/blong/compare/blong-gogo-v1.31.3...blong-gogo-v1.32.0) (2026-09-12)
+
+
+### Features
+
+* blong-kukum scaffolding as api ([abb1e0b](https://github.com/feasibleone/blong/commit/abb1e0b4836f25e4a04b035cbc3f2b4bbab94a9b))
+
+
+### Bug Fixes
+
+* small test fixes ([4adb7eb](https://github.com/feasibleone/blong/commit/4adb7eb1b899099fe71b05b96cd210af7d7ce51a))
+* small test/lint fixes ([0f52e7a](https://github.com/feasibleone/blong/commit/0f52e7a30fa479c1a91f95ba5d8bb1ae4706856c))
+
 ## [1.31.3](https://github.com/feasibleone/blong/compare/blong-gogo-v1.31.2...blong-gogo-v1.31.3) (2026-09-10)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feasibleone/blong-gogo",
-  "version": "1.31.3",
+  "version": "1.32.0",
   "repository": {
     "url": "git+https://github.com/feasibleone/blong.git"
   },
@@ -10,7 +10,8 @@
       "browser": "./src/loadBrowser.ts",
       "import": "./src/loadServer.ts"
     },
-    "./ConfigRuntime.js": "./src/ConfigRuntime.ts"
+    "./ConfigRuntime.js": "./src/ConfigRuntime.ts",
+    "./cli.ts": "./src/cli.ts"
   },
   "bin": {
     "blong": "./bin/blong.ts",
@@ -19,6 +20,7 @@
   },
   "dependencies": {
     "@apidevtools/swagger-parser": "^12.1.0",
+    "@modelcontextprotocol/sdk": "^1.0.0",
     "@aws-sdk/client-s3": "^3.1037.0",
     "@fastify/basic-auth": "^6.2.0",
     "@fastify/bearer-auth": "^10.1.2",
@@ -88,7 +90,7 @@
     "tap": "^21.6.3",
     "typescript": "^6.0.3",
     "vite": "^8.2.1",
-    "@feasibleone/blong-dev": "1.2.2"
+    "@feasibleone/blong-dev": "1.3.0"
   },
   "scripts": {
     "browser-check": "node scripts/browser-compat-check.mjs",

package/src/AdapterBase.ts

@@ -87,6 +87,7 @@ export class AdapterBase<T, C extends IContext> implements AdapterHandlerContext
     log: unknown = null;
     importedMap?: Map<string, Record<string, (...args: unknown[]) => unknown>>;
     platform: IApi['platform'];
+    registry: IApi['registry'];
 
     // These are prefixed with _ rather than using # private class fields.
     // The adapter uses Object.setPrototypeOf(current, base) to set the base as
@@ -125,6 +126,7 @@ export class AdapterBase<T, C extends IContext> implements AdapterHandlerContext
             | 'attachCheckpoint'
             | 'render'
             | 'platform'
+            | 'registry'
             | 'attach'
         >,
         configBase: string,
@@ -137,6 +139,7 @@ export class AdapterBase<T, C extends IContext> implements AdapterHandlerContext
         this._methodId = api.methodId;
         this._getPath = api.getPath;
         this.platform = api.platform;
+        this.registry = api.registry;
         this._api = api;
         this._createLog = api.createLog;
         this._attachCheckpoint = api.attachCheckpoint;

package/src/Gateway.ts

@@ -5,6 +5,7 @@ import type {
     IErrorFactory,
     IErrorMap,
     IGateway,
+    IGatewayRoute,
     ILocal,
     ILog,
     IManifest,
@@ -194,6 +195,25 @@ export default class Gateway extends Internal implements IGateway {
     #rpcClient: IRpcClient;
     #routes: RouteOptions[] = [];
     #local: ILocal;
+
+    /**
+     * The registered routes as plain data.
+     *
+     * Derived from the same list that is handed to fastify, so callers (for
+     * example the MCP server) see exactly the surface that is served — including
+     * the per-route auth requirement, which is not inferable from the method name.
+     */
+    public describe(): IGatewayRoute[] {
+        return this.#routes.map(route => {
+            const config = route.config as {methodName?: string; auth?: unknown} | undefined;
+            return {
+                method: config?.methodName ?? '',
+                url: route.url,
+                httpMethod: String(route.method ?? 'POST'),
+                auth: config?.auth ?? 'jwt',
+            };
+        });
+    }
     #errorFields: [string, unknown][] = [];
     #plugins: {plugin: unknown; options: unknown}[] = [];
     #platform: IPlatformApi;

package/src/Mcp.ts

@@ -0,0 +1,227 @@
+import type {IGateway, IGatewayRoute, ILog, IRegistry, IRemote} from '@feasibleone/blong/types';
+import {Internal} from '@feasibleone/blong/types';
+import type {FastifyInstance} from 'fastify';
+import fp from 'fastify-plugin';
+
+interface IConfig {
+    enabled: boolean;
+    routePrefix: string;
+    auth: false | 'jwt';
+    /** Server identity reported during the MCP initialise handshake. */
+    name: string;
+    version: string;
+    /**
+     * Method-name patterns to expose as tools. Defaults to the kukum API —
+     * widen this to expose other namespaces, or set `['.']` to expose every
+     * registered route.
+     */
+    tools: string[];
+    /** Free-text guidance sent to the client during initialise. */
+    instructions?: string;
+    logLevel?: string;
+}
+
+interface IApiRef {
+    log?: ILog;
+    gateway?: IGateway;
+    registry?: IRegistry;
+    remote?: IRemote;
+}
+
+/**
+ * MCP (Model Context Protocol) server for a Blong gateway, served over
+ * Streamable HTTP at `routePrefix` (default `/mcp`).
+ *
+ * Tools are derived from the gateway's own route table, so the MCP surface can
+ * never drift from the API: whatever `kukum.*` (or another configured namespace)
+ * route is registered becomes a callable tool, and invoking it dispatches
+ * through the same `remote` path an HTTP call would use.
+ *
+ * Off by default — this exposes an API to any MCP client that can reach the
+ * gateway, so it must be enabled deliberately (a suite can enable it in its own
+ * `dev` config without affecting anyone else). The SDK is imported lazily so the
+ * dependency is not loaded on the default path.
+ */
+export default class Mcp extends Internal {
+    #config: IConfig = {
+        enabled: false,
+        routePrefix: '/mcp',
+        auth: false,
+        name: 'blong',
+        version: '0.0.0',
+        tools: ['^kukum\\.'],
+    };
+
+    #apiRef: IApiRef;
+    /** Sanitised tool name → gateway method name. */
+    #tools: Map<string, string> = new Map();
+
+    public constructor(config: IConfig, apiRef: IApiRef) {
+        super({log: apiRef.log});
+        this.merge(this.#config, config);
+        this.#apiRef = apiRef;
+    }
+
+    /** MCP tool names must be `[A-Za-z0-9_-]`; the dotted method maps 1:1. */
+    static toolName(method: string): string {
+        return method.replaceAll('.', '_').replaceAll('/', '_');
+    }
+
+    /**
+     * Routes to expose as tools.
+     *
+     * `tools` entries are regular expressions matched against the wired method
+     * name, so the default `^kukum\\.` selects the whole kukum API. They are used
+     * verbatim — anchoring is the caller's choice.
+     */
+    public routes(): IGatewayRoute[] {
+        const patterns = this.#config.tools.map(pattern => new RegExp(pattern));
+        return (this.#apiRef.gateway?.describe?.() ?? []).filter(
+            route => route.method && patterns.some(pattern => pattern.test(route.method)),
+        );
+    }
+
+    public async init(): Promise<void> {
+        if (!this.#config.enabled || !this.#apiRef.gateway) return;
+
+        const remote = this.#apiRef.remote;
+        if (!remote) {
+            this.log?.warn?.('mcp is enabled but no remote dispatcher is available; skipping');
+            return;
+        }
+
+        const prefix = this.#config.routePrefix;
+        const authConfig = this.#config.auth;
+        const logger = this.log;
+        const {name, version, instructions, tools: toolPatterns} = this.#config;
+
+        // Deferred into the plugin factory on purpose: fastify runs plugin
+        // factories during `gateway.start()`, which is AFTER `registry.start()`
+        // has published the validations. Reading `gateway.describe()` in
+        // `init()` would see an empty route table.
+        const plugin = fp(
+            async (instance: FastifyInstance) => {
+                const routes = this.routes();
+                if (!routes.length) {
+                    logger?.warn?.(
+                        `mcp is enabled but no routes match ${JSON.stringify(toolPatterns)}`,
+                    );
+                }
+
+                // Lazy: nothing on the default path should pay for the SDK.
+                const {McpServer} = await import('@modelcontextprotocol/sdk/server/mcp.js');
+                const {StreamableHTTPServerTransport} =
+                    await import('@modelcontextprotocol/sdk/server/streamableHttp.js');
+                const {randomUUID} = await import('node:crypto');
+
+                const server = new McpServer({name, version}, {instructions});
+                for (const route of routes) {
+                    const tool = Mcp.toolName(route.method);
+                    this.#tools.set(tool, route.method);
+                    server.registerTool(
+                        tool,
+                        {
+                            title: route.method,
+                            description:
+                                `${route.method} — POST ${route.url}` +
+                                (route.auth === false ? ' (no auth required)' : ''),
+                        },
+                        async (args: unknown) => {
+                            const params = (args ?? {}) as Record<string, unknown>;
+                            const result = await remote.remote(route.method)(params, {
+                                method: route.method,
+                            });
+                            return {
+                                content: [
+                                    {type: 'text' as const, text: JSON.stringify(result, null, 2)},
+                                ],
+                            };
+                        },
+                    );
+                }
+
+                /**
+                 * One transport per MCP session, keyed by `Mcp-Session-Id`.
+                 *
+                 * Sessions are stateful because the protocol requires
+                 * `initialize` to precede other methods on the same session: a
+                 * stateless per-request server answers every follow-up with
+                 * "Method not found".
+                 */
+                const sessions = new Map<
+                    string,
+                    InstanceType<typeof StreamableHTTPServerTransport>
+                >();
+
+                const sessionFor = async (sessionId?: string) => {
+                    const existing = sessionId ? sessions.get(sessionId) : undefined;
+                    if (existing) return existing;
+                    const transport = new StreamableHTTPServerTransport({
+                        sessionIdGenerator: () => randomUUID(),
+                        onsessioninitialized: id => {
+                            sessions.set(id, transport);
+                        },
+                        // Plain JSON responses rather than SSE streams: kukum
+                        // calls are request/response with no server-initiated
+                        // messages, which keeps the endpoint usable from curl and
+                        // simple CLI clients.
+                        enableJsonResponse: true,
+                    });
+                    transport.onclose = () => {
+                        if (transport.sessionId) sessions.delete(transport.sessionId);
+                    };
+                    await server.connect(transport);
+                    return transport;
+                };
+
+                const handle = async (
+                    request: Parameters<Parameters<FastifyInstance['route']>[0]['handler']>[0],
+                    reply: Parameters<Parameters<FastifyInstance['route']>[0]['handler']>[1],
+                ) => {
+                    // The transport writes the response itself (including SSE
+                    // streams), so hand it the raw Node objects and tell fastify
+                    // not to touch the reply.
+                    reply.hijack();
+                    const sessionId = request.headers['mcp-session-id'] as string | undefined;
+                    try {
+                        const transport = await sessionFor(sessionId);
+                        await transport.handleRequest(request.raw, reply.raw, request.body);
+                    } catch (error) {
+                        // `reply.hijack()` means fastify will not produce an error
+                        // response — without this the client just sees an empty 500.
+                        logger?.error?.({error}, 'mcp request failed');
+                        if (!reply.raw.headersSent) {
+                            reply.raw.writeHead(500, {'content-type': 'application/json'});
+                        }
+                        reply.raw.end(
+                            JSON.stringify({
+                                jsonrpc: '2.0',
+                                error: {code: -32603, message: (error as Error).message},
+                                id: null,
+                            }),
+                        );
+                    }
+                };
+
+                instance.route({
+                    method: ['GET', 'POST', 'DELETE'],
+                    url: prefix,
+                    config: {auth: authConfig},
+                    handler: handle,
+                });
+                instance.addHook('onClose', async () => {
+                    for (const transport of sessions.values()) await transport.close();
+                    sessions.clear();
+                });
+
+                logger?.warn?.(
+                    `mcp server enabled at ${prefix} — exposing ${routes.length} tool(s); ` +
+                        'do not enable in production',
+                );
+            },
+            {name: 'mcp'},
+        );
+
+        this.#apiRef.gateway.registerPlugin(plugin);
+    }
+}

package/src/Registry.ts

@@ -14,6 +14,7 @@ import type {
     IObjectSchema,
     IPlatformApi,
     IRegistry,
+    IRegistryDescription,
     IRemote,
     IRpcServer,
 } from '@feasibleone/blong/types';
@@ -375,6 +376,19 @@ export default class Registry extends Internal implements IRegistry {
                 renderAll(Array.isArray(what) ? merge(...what) : what, this.#platform.context),
             timing: this.#platform.timing,
             ...blongLib,
+            // The runtime services a `library()` function needs, mirroring the
+            // port API (`registry: this`, `platform: …`).
+            //
+            // A `library()` *factory* is not given the platform: `layerApi`
+            // carries only config/handler/errors/schema/gateway/apiSchema. And
+            // the lib proxy returns an attached function **raw**, so `this`
+            // inside it is this object — not the port, which is only bound in the
+            // proxy's not-yet-attached fallback path. Without these keys a
+            // library function therefore cannot reach the platform or registry at
+            // all, which is what a library needs to be reusable outside a
+            // request.
+            platform: this.#platform,
+            registry: this,
         };
         const local = {};
         const literals: object[] = [];
@@ -469,6 +483,31 @@ export default class Registry extends Internal implements IRegistry {
         return await this.#watch.test(framework);
     }
 
+    /**
+     * Structural snapshot of the loaded realm graph.
+     *
+     * Combines the live registry (realms, ports, registered method groups) with
+     * the on-disk view owned by `Watch` (handler folders and files). This is the
+     * runtime source of truth that tooling and agents should query instead of
+     * re-deriving layout from conventions.
+     */
+    public describe(): IRegistryDescription {
+        const disk = this.#watch?.describe?.();
+        return {
+            realms: Array.from(this.modules.keys()).filter(
+                (key): key is string => typeof key === 'string',
+            ),
+            ports: Array.from(this.ports.keys()),
+            groups: Array.from(this.methods.entries()).map(([name, handlers]) => ({
+                name,
+                handlerCount: handlers.length,
+            })),
+            folders: disk?.folders ?? [],
+            files: disk?.files ?? [],
+            layerFiles: disk?.layerFiles ?? [],
+        };
+    }
+
     public async stop(): Promise<IRegistry> {
         if (this.#stopped) return this;
         await this.#watch?.stop();

package/src/Watch.ts

@@ -36,6 +36,18 @@ export interface IWatch {
     setConfigRuntime?(configRuntime: IConfigRuntime): void;
     /** Attach the registry objectSchema so hot-reload paths can pass it to layerProxy */
     setObjectSchema?(schema: IObjectSchema): void;
+    /**
+     * Structural snapshot of the handler folders/files discovered on disk.
+     * Data-only so it can be returned straight from an API endpoint.
+     */
+    describe(): IWatchDescription;
+}
+
+/** Handler folders/files discovered from disk, keyed by their owning realm. */
+export interface IWatchDescription {
+    folders: Array<{group: string; realm: string; dir: string}>;
+    files: Array<{file: string; realm: string}>;
+    layerFiles: Array<{file: string; realm: string}>;
 }
 
 interface ITestContext {
@@ -97,6 +109,13 @@ export default class Watch extends Internal implements IWatch {
         new Map();
     #handlerFiles: Map<string, {name: string; pkg: IModuleConfig['pkg']; base: string}> = new Map();
     #layerFiles: Map<string, {name: string; pkg: IModuleConfig['pkg']; base: string}> = new Map();
+    /**
+     * Every code file discovered inside a handler folder, mapped to its realm.
+     * Kept separate from `#handlerFiles` (which drives hot-reload decisions and
+     * is deliberately populated only for single-file loads) so introspection can
+     * report the full file set without changing reload behaviour.
+     */
+    #discoveredFiles: Map<string, string> = new Map();
     #watchers: IWatcher[] = [];
     #port: () => unknown;
     #error: IErrorFactory;
@@ -138,6 +157,35 @@ export default class Watch extends Internal implements IWatch {
         this.#objectSchema = schema;
     }
 
+    /**
+     * Structural snapshot of what is loaded from disk.
+     *
+     * Group ids follow the same convention the loader registers with
+     * (`<realm>.<folder>`, see `_loadHandlers`). Paths are made relative to the
+     * process cwd so the result is stable across machines.
+     */
+    public describe(): IWatchDescription {
+        const relative = (file: string): string => this.#platform.relative('.', file);
+        const folderEntries = Array.from(this.#handlerFolders.entries()).map(([dir, config]) => ({
+            group: `${config.name}.${this.#platform.basename(dir)}`,
+            realm: config.name,
+            dir: relative(dir),
+        }));
+        const toFiles = (map: Map<string, {name: string}>): Array<{file: string; realm: string}> =>
+            Array.from(map.entries()).map(([file, config]) => ({
+                file: relative(file),
+                realm: config.name,
+            }));
+        return {
+            folders: folderEntries,
+            files: Array.from(this.#discoveredFiles.entries()).map(([file, realm]) => ({
+                file: relative(file),
+                realm,
+            })),
+            layerFiles: toFiles(this.#layerFiles),
+        };
+    }
+
     /** Attach a ConfigRuntime so config-file changes trigger in-process reloads */
     public setConfigRuntime(configRuntime: IConfigRuntime): void {
         this.#configRuntime = configRuntime;
@@ -327,6 +375,7 @@ export default class Watch extends Internal implements IWatch {
                 filename,
                 this.#platform.extname(filename),
             );
+            this.#discoveredFiles.set(filename, config.name);
             const name = expectedName;
             (kind(item) === 'validation'
                 ? validations
@@ -659,13 +708,14 @@ export default class Watch extends Internal implements IWatch {
         remote: IRemote,
         configOverride: object,
     ): Promise<void> {
-        this.log?.debug?.({
-            $meta: {mtid: 'event', method: 'watch.start'},
-            dir: Array.from(this.#handlerFolders.keys())
-                .concat(Array.from(this.#handlerFiles.keys()))
-                .concat(Array.from(this.#layerFiles.keys()))
-                .map(folder => this.#platform.relative('.', folder)),
-        });
+        if (this.#config.enabled)
+            this.log?.debug?.({
+                $meta: {mtid: 'event', method: 'watch.start'},
+                dir: Array.from(this.#handlerFolders.keys())
+                    .concat(Array.from(this.#handlerFiles.keys()))
+                    .concat(Array.from(this.#layerFiles.keys()))
+                    .map(folder => this.#platform.relative('.', folder)),
+            });
         if (this.#config.test) {
             this.#emit.addEventListener('test', async (event: Event) => {
                 const {done, test} = ((event as CustomEvent).detail ?? {}) as {