@onlyne/mcp-gateway 0.0.0-stage → 3.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dbydd
+
+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

@@ -1,3 +1,46 @@
-# Temporary Holding Version
+# @onlyne/mcp-gateway
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An Onlyne node that hosts MCP servers as resources. Each configured server registers as one
+resource whose operations are that server's tools, so an agent reaches MCP through the same
+resource path it uses for every other capability.
+
+MCP resources carry no platform event stream, so this node has no push ring, no render ring, no
+event log, and no handler binding.
+
+## Run
+
+```sh
+bunx onlyne-mcp-gateway ./gateway.json
+```
+
+```json
+{
+  "node": { "id": "urn:onlyne:gateway:mcp" },
+  "server": { "bind": "127.0.0.1", "port": 3992 },
+  "storage": { "path": "./var/mcp/store.json" },
+  "servers": [
+    {
+      "name": "hindsight",
+      "url": "http://localhost:8888/mcp/example-bank/",
+      "timeout_ms": 60000,
+      "controllers": ["urn:onlyne:agent:main"]
+    }
+  ]
+}
+```
+
+`headers` adds per-request headers such as an API key and is never logged. `controllers` lists
+the nodes allowed to call a server's tools; an empty list leaves the node owner alone.
+`language` accepts `en` or `zh-CN` and otherwise follows `ONLYNE_LANG`, `LC_ALL`, or `LANG`.
+
+## Library use
+
+```ts
+import { createMcpGateway } from '@onlyne/mcp-gateway';
+```
+
+The result carries the node, the connections, and a `fetch` handler.
+
+## License
+
+MIT.

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@onlyne/mcp-gateway",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "3.0.0",
+  "description": "Onlyne MCP gateway: one node that hosts MCP servers as resources and exposes their tools as operations",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dbydd/onlyne.git",
+    "directory": "packages/mcp-gateway"
+  },
+  "homepage": "https://github.com/dbydd/onlyne#readme",
+  "bugs": "https://github.com/dbydd/onlyne/issues",
+  "keywords": ["onlyne", "mcp", "gateway", "cli"],
+  "publishConfig": { "access": "public" },
+  "engines": { "bun": ">=1.4.3" },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "bin": { "onlyne-mcp-gateway": "./src/main.ts" },
+  "files": ["src", "README.md", "LICENSE"],
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "bun tests/verify.ts"
+  },
+  "dependencies": {
+    "@onlyne/im-gateway": "^3.0.0",
+    "@onlyne/lib": "^3.0.0",
+    "@onlyne/mcp-core": "^3.0.0",
+    "@onlyne/node-host": "^3.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.0",
+    "typescript": "^5.9.0"
+  }
+}

package/src/config.ts

@@ -0,0 +1,98 @@
+import { OnlyneError, type Json, type NodeId } from '@onlyne/lib';
+import type { Locale } from '@onlyne/node-host/i18n';
+import { t } from './gateway-text.js';
+
+/** One configured MCP server: its resource name, URL and per-call settings. */
+export interface ServerConfig {
+  name: string;
+  url: string;
+  /** Extra request headers (an API key, a bank header); never logged. */
+  headers?: Record<string, string>;
+  timeout_ms?: number;
+  /** Who may call this server's tools. Empty means the node owner only. */
+  controllers?: NodeId[];
+}
+
+export interface GatewayConfig {
+  node: { id: NodeId };
+  server: { bind: string; port: number };
+  storage_path: string;
+  servers: ServerConfig[];
+  /** The language of the gateway's own console text; unset follows `ONLYNE_LANG`. */
+  language?: Locale;
+}
+
+const requireObject = (value: Json | undefined, field: string): Record<string, Json> => {
+  if (value === undefined || value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new OnlyneError('invalid_request', t('config.object', { field }));
+  }
+  return value as Record<string, Json>;
+};
+
+const requireString = (container: Record<string, unknown>, field: string): string => {
+  const value = container[field];
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new OnlyneError('invalid_request', t('config.string', { field }));
+  }
+  return value;
+};
+
+/** `language` is exactly `en` or `zh-CN`: a near miss would silently pick a different console language. */
+const parseLanguage = (value: Json | undefined): Locale | undefined => {
+  if (value === undefined) return undefined;
+  if (value === 'en' || value === 'zh-CN') return value;
+  throw new OnlyneError('invalid_request', t('config.language', { value: JSON.stringify(value) }));
+};
+
+/** Loads the gateway configuration from one JSON file; environment retuning comes later. */
+export async function loadConfig(path: string): Promise<GatewayConfig> {
+  let file: Json | undefined;
+  try {
+    file = JSON.parse(await Bun.file(path).text()) as Json;
+  } catch {
+    throw new OnlyneError('invalid_request', t('config.unreadable', { path }));
+  }
+  const raw = requireObject(file, 'the configuration root');
+  const node = requireObject(raw.node, 'node');
+  const server = requireObject(raw.server, 'server');
+  const storage = requireObject(raw.storage, 'storage');
+  const language = parseLanguage(raw.language);
+  const owner = requireString(node, 'id') as NodeId;
+  const rawServers = raw.servers === undefined ? [] : raw.servers;
+  if (!Array.isArray(rawServers)) {
+    throw new OnlyneError('invalid_request', t('config.servers'));
+  }
+  const servers = rawServers.map((entry, index): ServerConfig => {
+    const item = requireObject(entry, `servers[${index}]`);
+    const rawHeaders = item.headers === undefined ? undefined : requireObject(item.headers, `servers[${index}].headers`);
+    const headers = rawHeaders === undefined
+      ? undefined
+      : Object.fromEntries(Object.entries(rawHeaders).filter((pair): pair is [string, string] => typeof pair[1] === 'string'));
+    const timeout = item.timeout_ms;
+    const controllers = item.controllers;
+    return {
+      name: requireString(item, 'name'),
+      url: requireString(item, 'url'),
+      ...(headers === undefined || Object.keys(headers).length === 0 ? {} : { headers }),
+      ...(typeof timeout === 'number' ? { timeout_ms: timeout } : {}),
+      ...(Array.isArray(controllers)
+        ? { controllers: controllers.filter((value): value is NodeId => typeof value === 'string' && value.length > 0) }
+        : {}),
+    };
+  });
+  const names = new Set<string>();
+  for (const entry of servers) {
+    if (names.has(entry.name)) throw new OnlyneError('invalid_request', t('config.duplicateName', { name: entry.name }));
+    names.add(entry.name);
+  }
+  return {
+    node: { id: owner },
+    server: {
+      bind: typeof server.bind === 'string' && server.bind.length > 0 ? server.bind : '127.0.0.1',
+      port: typeof server.port === 'number' ? server.port : 0,
+    },
+    storage_path: requireString(storage, 'path'),
+    servers,
+    ...(language === undefined ? {} : { language }),
+  };
+}

package/src/gateway-text.ts

@@ -0,0 +1,33 @@
+import { createTranslator } from '@onlyne/node-host/i18n';
+
+const en = {
+  'cli.usage': 'usage: onlyne-mcp-gateway <config.json>',
+  'startup.pending': 'The gateway is starting.',
+  'config.unreadable': 'The configuration file is unreadable: {path}',
+  'config.object': 'The configuration needs {field} as an object.',
+  'config.string': 'The configuration field {field} is a non-empty string.',
+  'config.servers': 'The configuration needs servers as an array.',
+  'config.duplicateName': 'Two servers share the name {name}.',
+  'config.language': 'The configuration language is en or zh-CN, not {value}.',
+  'error.claimIdentity': 'HTTP callers cannot claim the gateway identity.',
+  'error.decide': 'The gateway forwards tool calls; it decides nothing.',
+  'error.noContext': 'The gateway consumes no model context.',
+} as const;
+
+const zh: Record<keyof typeof en, string> = {
+  'cli.usage': '用法：onlyne-mcp-gateway <config.json>',
+  'startup.pending': '网关正在启动。',
+  'config.unreadable': '配置文件无法读取：{path}',
+  'config.object': '配置项 {field} 需要是一个对象。',
+  'config.string': '配置项 {field} 需要是非空字符串。',
+  'config.servers': '配置项 servers 需要是一个数组。',
+  'config.duplicateName': '有两个服务器共用了名称 {name}。',
+  'config.language': '配置项 language 只能是 en 或 zh-CN，而不是 {value}。',
+  'error.claimIdentity': 'HTTP 调用方不能冒用网关身份。',
+  'error.decide': '网关只转发工具调用，不做任何决策。',
+  'error.noContext': '网关不消费模型上下文。',
+};
+
+export type GatewayTextKey = keyof typeof en;
+
+export const t = createTranslator({ en, 'zh-CN': zh });

package/src/index.ts

@@ -0,0 +1,151 @@
+import {
+  OnlyneNode, OnlyneError, type Auth, type KeyHook, type MaintenanceClock, type NodeId, type Plugins, type Resource,
+} from '@onlyne/lib';
+import { createMcpBridge, resourceOf, McpConnection, type McpServerOptions } from '@onlyne/mcp-core';
+import type { GatewayConfig, ServerConfig } from './config.js';
+import { FileStorage } from '@onlyne/im-gateway/storage';
+import { t } from './gateway-text.js';
+
+export type { GatewayConfig, ServerConfig } from './config.js';
+
+export interface McpGateway {
+  readonly node: OnlyneNode;
+  readonly config: GatewayConfig;
+  /** The MCP connections, one per configured server, keyed by resource id. */
+  readonly connections: Map<string, McpConnection>;
+  stop(): Promise<void>;
+}
+
+/** The Node-timer MaintenanceClock: one-shot timers, the lib's loop re-arms them. */
+export function nodeClock(): MaintenanceClock {
+  return {
+    setTimer: (ms, run) => setTimeout(run, ms),
+    clearTimer: handle => clearTimeout(handle as ReturnType<typeof setTimeout>),
+  };
+}
+
+/**
+ * Assembles the gateway: one session per configured MCP server, one Onlyne resource per server.
+ * A server that cannot be reached at startup still registers (with its last known tools if the
+ * store has them, an empty list otherwise): the node stays up, and the session re-initializes
+ * on the first call (RFC 0015 §5).
+ */
+export interface McpGatewayOptions {
+  log?: (message: string, fields?: Record<string, unknown>) => void;
+  /**
+   * RFC 0017 identity key. The CLI always supplies one; a programmatic caller may omit it and
+   * keep the keyless loopback binding the tests use.
+   */
+  keys?: KeyHook;
+}
+
+export async function createMcpGateway(config: GatewayConfig, options: McpGatewayOptions = {}): Promise<McpGateway> {
+  const owner: NodeId = config.node.id;
+  const storage = new FileStorage(config.storage_path);
+  const connections = new Map<string, McpConnection>();
+  const serverEntries: Array<{ server: McpServerOptions; connection: McpConnection }> = [];
+
+  for (const entry of config.servers) {
+    const server: McpServerOptions = {
+      name: entry.name,
+      url: entry.url,
+      ...(entry.headers === undefined ? {} : { headers: entry.headers }),
+      ...(entry.timeout_ms === undefined ? {} : { timeoutMs: entry.timeout_ms }),
+    };
+    const connection = new McpConnection(server);
+    let tools: Awaited<ReturnType<McpConnection['refreshTools']>> = [];
+    // The last known tool list rides in the store, so a temporarily unreachable server still
+    // presents its operations instead of an empty resource.
+    const cached = await storage.transaction(async tx => tx.get<{ tools: typeof tools }>(`mcp/tools/${encodeURIComponent(entry.name)}`));
+    try {
+      await connection.start();
+      tools = connection.tools;
+      await storage.transaction(async tx => { await tx.put(`mcp/tools/${encodeURIComponent(entry.name)}`, { tools }); });
+    } catch (err) {
+      // Registration proceeds with the cache; the connection retries on first call.
+      options.log?.('mcp.server.start.failed', { server: entry.name, error: String(err) });
+      tools = cached?.tools ?? [];
+    }
+    connections.set(entry.name, connection);
+    serverEntries.push({ server, connection });
+  }
+
+  const bridge = createMcpBridge(serverEntries);
+  const base_url = `http://${config.server.bind}:${config.server.port}/onlyne/v3`;
+  const keys = options.keys;
+  const authenticate = async (request: Request): Promise<Auth | null> => {
+    const actor = request.headers.get('Onlyne-Actor');
+    if (actor === null || actor.length === 0) return null;
+    if (actor === owner) throw new OnlyneError('forbidden', t('error.claimIdentity'));
+    return { actor };
+  };
+  const plugins: Omit<Plugins, 'storage' | 'resources'> = {
+    authenticate,
+    maintenanceClock: nodeClock(),
+    resolve: async id => {
+      // A peer's address is whatever discovery last verified; the actor header is what names
+      // this node on the wire, and the signing transport adds the signature over it.
+      const target = id === owner ? { node_id: id, base_url } : await node.discovery.resolve(id);
+      return { ...target, headers: { 'Onlyne-Actor': owner } };
+    },
+    decide: () => { throw new OnlyneError('decision_unavailable', t('error.decide')); },
+    runtime: {
+      // The terminal log is the gateway's only console, so every exchange stage lands in it
+      // with the fingerprint the operator has to repeat on `confirm`.
+      notify: event => {
+        if (event.event !== 'trust') return;
+        options.log?.('onlyne.trust', {
+          node: event.entry.node_id, phase: event.phase, fingerprint: event.entry.fingerprint, cause: event.cause,
+        });
+      },
+      supports: async () => false,
+      inject: async () => { throw new OnlyneError('unsupported_delivery', t('error.noContext')); },
+    },
+    domainCandidates: async domain_id => node.discovery.candidates(domain_id),
+    ...(keys === undefined ? {} : { keys }),
+  };
+  let node: OnlyneNode;
+  node = new OnlyneNode({
+    node_id: owner,
+    base_url,
+    // RFC 0017 §1: a keyed node advertises the scheme it authenticates with. The keyless
+    // binding stays for programmatic callers on loopback.
+    authentication: keys === undefined ? ['none'] : ['signature'],
+    plugins: { ...plugins, storage, resources: bridge },
+    now: () => Date.now(),
+    id: () => crypto.randomUUID(),
+  });
+
+  const gatewayAuth: Auth = { actor: owner };
+  for (const [index, entry] of config.servers.entries()) {
+    const controllers = Array.from(new Set([owner, ...(entry.controllers ?? [])]));
+    const definition = resourceOf(owner, serverEntries[index]!.server, serverEntries[index]!.connection.tools, controllers);
+    // RFC 0006 §3: one handler operates a resource, so the first configured controller holds
+    // the control right; every other controller keeps read access through the log reader list.
+    const resource: Resource = {
+      resource_ref: definition.resource_ref,
+      kind: 'mcp',
+      operations: definition.operations,
+      binding: { handler: entry.controllers?.[0] ?? owner, cursor: '0' },
+      log_readers: definition.log_readers,
+      revision: 'rev-1',
+      event_seq: '0',
+      retention_ms: 0,
+      data: definition.data,
+    };
+    try {
+      await node.resources.describe(gatewayAuth, definition.resource_ref);
+    } catch (error) {
+      if (!(error instanceof OnlyneError) || error.error.code !== 'not_found') throw error;
+      await node.resources.register(gatewayAuth, resource);
+    }
+  }
+
+  return {
+    node, config, connections,
+    async stop(): Promise<void> {
+      node.client.stopMaintenance();
+      for (const connection of connections.values()) await connection.close();
+    },
+  };
+}

package/src/main.ts

@@ -0,0 +1,56 @@
+#!/usr/bin/env bun
+import { createLogger, createNodeKey, startNodeHost } from '@onlyne/node-host';
+import { resolveLocale, setLocale } from '@onlyne/node-host/i18n';
+import { dirname, join } from 'node:path';
+import { loadConfig } from './config.js';
+import { createMcpGateway, type McpGateway } from './index.js';
+import { t } from './gateway-text.js';
+
+const path = process.argv[2];
+if (path === undefined) {
+  console.error(t('cli.usage'));
+  process.exit(2);
+}
+
+const config = await loadConfig(path);
+// The configured language wins over the environment for everything this process prints; the
+// logger and the node host below are built after this point so their text follows it too.
+setLocale(resolveLocale(config.language));
+// On a terminal the TUI owns the screen, so log lines go to the ring it renders and to a file
+// beside the store; the ring alone would vanish with the process.
+const { log, ring } = createLogger(
+  !(process.stdin.isTTY && process.stdout.isTTY), 200, join(dirname(config.storage_path), 'gateway.log'),
+);
+// RFC 0017 §2: the CLI is always keyed, and a missing key is generated and saved under
+// ~/.config/onlyne/keys/<node-id>/ instead of being a hand-written prerequisite.
+const keys = await createNodeKey(config.node.id);
+// The advertised endpoint must carry the port the process actually bound, which is only
+// known after `Bun.serve` when the configuration asks for port 0.
+let handler: (request: Request) => Promise<Response> = async () =>
+  new Response(t('startup.pending'), { status: 503 });
+const server = Bun.serve({ hostname: config.server.bind, port: config.server.port, fetch: request => handler(request) });
+config.server.port = server.port ?? config.server.port;
+const endpoint = `http://${config.server.bind}:${config.server.port}/onlyne/v3`;
+
+const gateway: McpGateway = await createMcpGateway(config, { keys, log });
+handler = request => gateway.node.fetch(request);
+gateway.node.client.runMaintenance();
+// Discovery starts only once the real handler is served: a candidate probe aimed at this
+// node must reach the gateway instead of the starting stub.
+const host = await startNodeHost({ node: gateway.node, endpoint, bind: config.server.bind, ring, log });
+
+const shutdown = async (): Promise<void> => {
+  await host.close();
+  await gateway.stop();
+  server.stop(true);
+  log('mcp.gateway.stopped', { node: config.node.id });
+  process.exit(0);
+};
+process.on('SIGINT', () => { void shutdown(); });
+process.on('SIGTERM', () => { void shutdown(); });
+
+log('mcp.gateway.listening', {
+  node: config.node.id,
+  endpoint,
+  servers: config.servers.map(entry => entry.name),
+});