@empyria/mcp 0.1.0

package/.oxfmtrc.json

@@ -0,0 +1,9 @@
+{
+	"$schema": "./node_modules/oxfmt/configuration_schema.json",
+	"ignorePatterns": [],
+	"useTabs": true,
+	"tabWidth": 4,
+	"singleQuote": true,
+	"trailingComma": "all",
+	"semi": false
+}

package/AGENTS.md

@@ -0,0 +1,126 @@
+# AGENTS.md
+
+MCP (Model Context Protocol) helpers for **Principia**, a nanoservice framework built
+primarily on Bun: publishes Moleculer-shaped `{ name, actions }` service objects as MCP tools.
+
+## The package split that matters here
+
+There are **two different, unrelated npm package families** claiming the MCP name:
+
+- `@modelcontextprotocol/sdk` (currently `1.30.0`) — the original, unified SDK. Its `McpServer`
+  convenience API (`tool()`/`registerTool()`) only accepts Zod schemas for tool input, with no
+  JSON-Schema escape hatch found in it.
+- `@modelcontextprotocol/server` + `@modelcontextprotocol/core` + `@modelcontextprotocol/client`
+  (currently `2.0.0`) — the newer split packages. **This is what this repo uses.** Its
+  `registerTool()` still wants a "Standard Schema" too, but it ships `fromJsonSchema(schema,
+validatorProvider)`, a first-class adapter that wraps a plain JSON Schema object into one,
+  given a pluggable `{ getValidator(schema) => (input) => {valid, data, errorMessage} }`
+  provider — the exact same extension point its own `./validators/ajv` and
+  `./validators/cf-worker` subpath exports implement. `lib/Validator.js` is that same interface,
+  backed by `@empyria/common`'s `createValidator` instead.
+
+Don't add `zod` as a dependency of this repo's own code — we never import it. It's still an
+unavoidable transitive dependency of `@modelcontextprotocol/server` (used internally for the
+SDK's own request/notification envelope schemas), so it'll be in `node_modules`, but nothing
+here should ever construct or reference a Zod schema directly.
+
+## HTTP transport
+
+`lib/Http.js`'s `createMcpHttpHandler()` wraps `createMcpHandler(factory)` from
+`@modelcontextprotocol/server` — it wants a **factory** (`() => McpServer`), not an
+already-built server, because HTTP serving defaults to stateless: a fresh server instance per
+request. `createMcpServer()` is cheap (pure registration, no I/O) so `() => createMcpServer(options)`
+is the whole adapter.
+
+The resulting handler is `{ fetch: (Request) => Promise<Response>, close }` — plain Web
+Standard, no framework required. `serveMcpHttp()` wires that straight into `Bun.serve` (uses
+the global `Bun`, so it only works under Bun — `createMcpHttpHandler` itself stays
+runtime-agnostic and works under Node too, since nothing in it touches `Bun` unless
+`serveMcpHttp` is actually called). Don't add `@modelcontextprotocol/hono` or another web
+framework as a dependency for this — it's one optional adapter among several, not a
+requirement, and would be an unnecessary dependency here.
+
+## `extra` is only populated when `inputSchema` is set — always declare one
+
+`registerTool(name, config, cb)`'s runtime dispatch (`createToolExecutor` in the SDK) checks
+`config.inputSchema` at _call_ time, not just at registration: if it's set, `cb` is invoked as
+`(args, extra)`; if it's unset, `cb` collapses to a **single-argument** `(extra)` call — the
+would-be `args` position silently receives `extra`'s value instead, and the real `extra`
+argument is `undefined`. `lib/Server.js` always builds an `inputSchema` (an empty-object one via
+`defineSchema(params ?? {})` when an action declares no `params`) specifically to avoid this —
+don't special-case the "no params" path back to an omitted `inputSchema`, it silently breaks
+`extra` (and therefore `lib/Guard.js`, which reads `extra.http.req` for every action regardless
+of whether it takes params). See the regression test in `test/Server.test.js` ("still receives a
+real extra context, not undefined").
+
+## Auth (`lib/Guard.js`)
+
+`extra.http.req` (the raw `Request`, with real header access via `.headers.get(name)`) is
+only ever populated over HTTP — confirmed empirically, not from docs alone: `extra.http` is
+absent entirely over `InMemoryTransport`/stdio. `withMetaGuard`-protected services will reject
+_every_ call made over a non-HTTP transport, by design (there's nowhere for a token to live).
+Don't try to thread a token through `extra` for stdio — there isn't a protocol-level place to
+put it short of smuggling it into every action's own `params`, which was deliberately not done
+here (it would leak into every tool's public schema).
+
+`resolveToken(tokenKey, { service, action, extra })`'s signature intentionally mirrors
+`empyria-guard-moleculer`'s `getUser(ctx, action)` — passing the service/action a guarded call
+is targeting, the same way that file's `action.service.meta` does, for callers whose token
+resolution needs to vary per action.
+
+## Gateway (`lib/Gateway.js`)
+
+`createMcpGateway` does **not** re-validate arguments for proxied tools — `lib/Guard.js`'s
+`passthroughValidator` in `Gateway.js` always reports `{valid: true}`. This is deliberate, not a
+shortcut: the upstream server already validates the same arguments when the call is forwarded
+to it via `client.callTool()`. Running a second, independent JSON Schema implementation
+(ata-validator) over an already-upstream-validated payload would risk rejecting input the
+upstream itself accepts (dialect/keyword coverage differences) for zero real benefit. If you
+ever need the gateway to enforce something upstream doesn't, that's a deliberate new feature,
+not "fixing" a missing validation step.
+
+An `inputSchema` is still always declared per proxied tool (even a bare passthrough one for a
+schema-less upstream tool) — same reason as `lib/Server.js`'s own rule: omitting it collapses
+`registerTool`'s callback to a single-argument `(extra)` call instead of `(args, extra)`.
+
+A gateway is expensive to build (one `listTools()` round trip per upstream) — it's meant to be
+built once and reused, not rebuilt per request. Confirmed empirically: a `createMcpHandler`
+factory can safely return the _same_ already-built `McpServer` on every call (no "already
+connected" error, no per-request rebuild needed) — see the HTTP test in `test/Gateway.test.js`.
+
+`createMcpGateway` takes already-connected `Client` instances, not transport configs — it
+doesn't manage upstream connection lifecycle (that's `lib/Client.js`'s job, and the caller's to
+close). Keep it that way; don't fold stdio/HTTP connection logic into `Gateway.js` a third time.
+
+## Runtime
+
+- Requires Bun `>=1.4.0` or Node.js `>=26`, inherited from `@empyria/classification`'s use
+  of native `Temporal`. Both `@empyria/classification` and `@empyria/common` are **git
+  dependencies** — this package only sees their pushed commits, not local working-tree changes
+  in sibling repos.
+- Plain ESM, no TypeScript, no build step.
+- Relative imports must include explicit `.js` extensions — Bun tolerates missing ones, Node's
+  ESM resolver doesn't.
+
+## Tool errors vs. protocol errors
+
+A tool call that fails validation, or whose handler throws, does **not** reject the client's
+`callTool()` promise — `McpServer` catches it and resolves with `{ content: [...], isError:
+true }` (the SDK's own `createToolError`), per MCP's own tool-error convention. Only genuine
+protocol errors (e.g. calling a tool name that was never registered) actually reject. Write
+tests accordingly — `await expect(client.callTool(...)).rejects.toThrow()` is wrong for a
+validation-failure or handler-throw test; check `result.isError` instead. See `test/Server.test.js`.
+
+## Testing
+
+Tests drive a real `@modelcontextprotocol/client` `Client` against the server — over
+`InMemoryTransport.createLinkedPair()` for transport-agnostic behavior, a real `Bun.serve` HTTP
+server for anything header/auth-related (`test/Guard.test.js`, `test/Http.test.js`), and a real
+spawned child process (`test/fixtures/stdio-server.js`) for `connectStdioClient`
+(`test/Client.test.js`) — rather than mocking the protocol. `@modelcontextprotocol/client` is a
+real dependency (not devDependency-only): `lib/Client.js` needs it at runtime, not just tests.
+
+## Style
+
+- Formatting is enforced by oxfmt ([.oxfmtrc.json](./.oxfmtrc.json)): tabs, single quotes, no
+  semicolons, trailing commas. Run `bun run format:fix` before committing.

package/README.md

@@ -0,0 +1,215 @@
+# @empyria/mcp
+
+[MCP (Model Context Protocol)](https://modelcontextprotocol.io) helpers for **Principia**, a
+nanoservice framework built primarily on Bun: publish a list of Moleculer-shaped services as
+MCP tools, with JSON Schema input validation via `@empyria/common`'s `createValidator` —
+no Zod, no Ajv, in our own code.
+
+## Requirements
+
+- Bun `>=1.4.0` or Node.js `>=26`
+- Plain ESM, no build step, no TypeScript
+
+Both requirements come from [@empyria/classification](https://github.com/imrefazekas/empyria-classification)
+and [@empyria/common](https://github.com/imrefazekas/empyria-common), which this package
+depends on and which use the native `Temporal` global for all date/time handling.
+
+## Install
+
+```bash
+bun add @empyria/mcp
+```
+
+## Usage
+
+```js
+import { createMcpServer } from '@empyria/mcp'
+import { string, number } from '@empyria/common'
+import { StdioServerTransport } from '@modelcontextprotocol/server/stdio'
+
+const WeatherService = {
+	name: 'Weather',
+	actions: {
+		getForecast: {
+			description: 'Get the weather forecast for a city',
+			params: { city: string(), days: number(3) },
+			handler: async ({ city, days }) => ({ city, days, forecast: 'sunny' }),
+		},
+		// bare functions work too — no params schema, no description
+		ping: async () => 'pong',
+	},
+}
+
+const server = createMcpServer({
+	name: 'my-mcp-server',
+	version: '1.0.0',
+	services: [WeatherService],
+})
+
+await server.connect(new StdioServerTransport())
+```
+
+Each action becomes an MCP tool named `"<service.name>.<actionName>"` — `Weather.getForecast`,
+`Weather.ping` above — mirroring Moleculer's own `service.action` naming. `params` are JSON
+schema property definitions built with `@empyria/common`'s schema helpers (`string()`,
+`number()`, `bool()`, `enumType()`, ...); incoming tool calls are validated against them before
+your handler runs, and validation failures are reported back to the MCP client as a normal
+tool-call error (`isError: true`) — your handler never sees invalid input. A handler's return
+value can be a string, any JSON-serializable value, or an already MCP-shaped
+`{ content: [...] }` result; thrown errors are also reported back as tool-call errors
+automatically.
+
+`createMcpServer` only builds and registers — connecting to a transport (stdio, HTTP, ...) is
+up to you. For stdio, see `@modelcontextprotocol/server/stdio`'s `StdioServerTransport`/
+`serveStdio`. For HTTP, this package has its own helper:
+
+```js
+import { serveMcpHttp } from '@empyria/mcp'
+
+serveMcpHttp(
+	{ name: 'my-mcp-server', version: '1.0.0', services: [WeatherService] },
+	{ port: 3000 },
+)
+```
+
+`serveMcpHttp` serves MCP over `Bun.serve` directly — no web framework needed. MCP's official
+`createMcpHandler` produces a plain Web-standard `{ fetch: (Request) => Promise<Response>,
+close }` handler (usable with any Fetch-API server, Bun's included); `@modelcontextprotocol/hono`
+is only one optional adapter among several for wiring that handler into Hono specifically, not
+a requirement. If you need the bare `{fetch, close}` handler instead of an already-running Bun
+server (e.g. to mount inside your own `Bun.serve`, or another Fetch-based runtime), use
+`createMcpHttpHandler(options)` instead.
+
+### Protecting services with a token
+
+A service can require a token by adding a `resolveToken` function — the MCP-side equivalent of
+`empyria-guard-moleculer`'s `MetaGuard.middleware.js`, reusing the same shape as its
+`getUser(ctx, action)`:
+
+```js
+const SecretsService = {
+	name: 'Secrets',
+	async resolveToken(tokenKey, { service, action }) {
+		// look the token up however you like — call another service, hit a DB, etc.
+		// return the resolved user/session, or a falsy value to reject the call
+		return lookupUser(tokenKey)
+	},
+	actions: {
+		reveal: {
+			params: { id: string() },
+			handler: async ({ id }, extra) => `secret for ${extra.user.name}`,
+		},
+	},
+}
+```
+
+The token is read from the `Authorization` header (an optional `Bearer ` prefix is stripped),
+or a custom header via `guard: { tokenHeader: 'x-token-key' }` passed to `createMcpServer`/
+`serveMcpHttp`. Calls with a missing or unresolved token are rejected as a normal tool-call
+error, and the resolved value is attached to the handler's `extra.user`, mirroring Moleculer's
+`ctx.meta.user`. **This only works over HTTP** — tokens travel as request headers, and stdio has
+none; a `resolveToken`-protected service called over stdio always rejects. Services without
+`resolveToken` are unaffected (public) — it's entirely opt-in, per service.
+
+### Connecting as a client
+
+```js
+import { connectStdioClient, connectHttpClient } from '@empyria/mcp'
+
+const stdioClient = await connectStdioClient({
+	name: 'my-client',
+	version: '1.0.0',
+	command: 'node',
+	args: ['./my-server.js'],
+})
+
+const httpClient = await connectHttpClient({
+	name: 'my-client',
+	version: '1.0.0',
+	url: 'http://localhost:3000',
+	token: 'my-token', // sends Authorization: Bearer my-token
+})
+
+const { tools } = await httpClient.listTools()
+await httpClient.callTool({ name: 'Weather.getForecast', arguments: { city: 'Zurich' } })
+```
+
+### Aggregating many MCP servers into one (a gateway)
+
+If you have several MCP servers and want to expose them to one agentic host as a single
+connection — fewer config entries, one place to apply `lib/Guard.js`, etc. — connect to each as
+a client and hand them to `createMcpGateway`:
+
+```js
+import { connectStdioClient, connectHttpClient, createMcpGateway } from '@empyria/mcp'
+import { StdioServerTransport } from '@modelcontextprotocol/server/stdio'
+
+const weather = await connectStdioClient({
+	name: 'gw',
+	version: '1.0.0',
+	command: 'node',
+	args: ['./weather-server.js'],
+})
+const search = await connectHttpClient({
+	name: 'gw',
+	version: '1.0.0',
+	url: 'http://localhost:4000',
+})
+
+const gateway = await createMcpGateway({
+	name: 'my-gateway',
+	version: '1.0.0',
+	upstreams: [
+		{ name: 'Weather', client: weather },
+		{ name: 'Search', client: search },
+	],
+})
+
+await gateway.connect(new StdioServerTransport())
+```
+
+Each upstream's tools are listed once, up front, and re-exposed as
+`"<upstream.name>.<toolName>"`; calls are forwarded to the owning upstream and its result
+passed straight through, unvalidated a second time — the upstream already validated it.
+Building a gateway does real work (one `listTools()` per upstream), so build it once and reuse
+that same instance — including as `createMcpHandler`'s per-request factory for HTTP, e.g. inside
+`serveMcpHttp`'s `bunOptions.fetch` — rather than reconnecting upstreams on every request.
+
+## Modules
+
+| Module                                 | Purpose                                                                                                                                                                                                     |
+| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [lib/Server.js](./lib/Server.js)       | `createMcpServer` — publishes a list of Moleculer-shaped `{ name, actions }` services as MCP tools.                                                                                                         |
+| [lib/Http.js](./lib/Http.js)           | `createMcpHttpHandler` (runtime-agnostic Web-standard handler) and `serveMcpHttp` (Bun-only convenience, wraps `Bun.serve`).                                                                                |
+| [lib/Guard.js](./lib/Guard.js)         | `withMetaGuard` — optional per-service token protection; see above.                                                                                                                                         |
+| [lib/Client.js](./lib/Client.js)       | `createMcpClient`, `connectStdioClient`, `connectHttpClient` — client-side helpers.                                                                                                                         |
+| [lib/Gateway.js](./lib/Gateway.js)     | `createMcpGateway` — aggregates several already-connected upstream MCP clients into one server.                                                                                                             |
+| [lib/Validator.js](./lib/Validator.js) | `principiaJsonSchemaValidator` — adapts `@empyria/common`'s `createValidator` to the MCP SDK's pluggable JSON Schema validator interface, the same extension point its own `ajv`/`cf-worker` providers use. |
+
+There is no official JSON-Schema-only convenience API in `@modelcontextprotocol/server` — its
+`registerTool()` still needs a "Standard Schema" (what Zod produces). What _is_ official and
+Zod-free is `fromJsonSchema(schema, validatorProvider)`, which wraps a plain JSON Schema object
+into a Standard Schema given a validator provider — that's what `lib/Server.js` uses, backed by
+`lib/Validator.js` instead of the SDK's own `ajv`/`cf-worker` providers.
+
+Every exported function is documented with JSDoc directly in its source file — hovering
+a function in VSCode or Zed shows its parameters and return type without any extra
+tooling, since both editors read JSDoc from plain `.js` files automatically.
+
+Tests live under [test/](./test/), one file per module. They drive a real
+`@modelcontextprotocol/client` `Client` against the server over `InMemoryTransport` rather than
+mocking the protocol.
+
+## Scripts
+
+```bash
+bun run format       # check formatting (oxfmt)
+bun run format:fix   # apply formatting
+bun run lint         # lint (oxlint)
+bun run lint:fix     # lint and fix
+bun run test         # run tests with coverage
+```
+
+## License
+
+MIT © Imre Fazekas

package/index.js

@@ -0,0 +1,11 @@
+export * from './lib/Server.js'
+
+export * from './lib/Validator.js'
+
+export * from './lib/Http.js'
+
+export * from './lib/Guard.js'
+
+export * from './lib/Client.js'
+
+export * from './lib/Gateway.js'

package/lib/Client.js

@@ -0,0 +1,56 @@
+import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client'
+import { StdioClientTransport } from '@modelcontextprotocol/client/stdio'
+
+/**
+ * Builds a bare (unconnected) MCP client. See {@link connectStdioClient}/{@link connectHttpClient}
+ * for the common case of building and connecting in one call.
+ * @param {Object} options
+ * @param {string} options.name - Client name, shown to the server.
+ * @param {string} options.version - Client version, shown to the server.
+ * @returns {Client}
+ */
+export function createMcpClient({ name, version }) {
+	return new Client({ name, version })
+}
+
+/**
+ * Builds an MCP client and connects it to a server over stdio, spawning the server as a
+ * child process.
+ * @param {Object} options
+ * @param {string} options.name - Client name, shown to the server.
+ * @param {string} options.version - Client version, shown to the server.
+ * @param {string} options.command - Executable to run to start the server.
+ * @param {string[]} [options.args] - Command-line arguments.
+ * @param {Record<string, string>} [options.env] - Environment for the spawned process; inherits
+ *   a safe default subset of the current process's environment if omitted.
+ * @returns {Promise<Client>} The connected client.
+ */
+export async function connectStdioClient({ name, version, command, args, env }) {
+	const client = createMcpClient({ name, version })
+	await client.connect(new StdioClientTransport({ command, args, env }))
+	return client
+}
+
+/**
+ * Builds an MCP client and connects it to a server over streamable HTTP.
+ * @param {Object} options
+ * @param {string} options.name - Client name, shown to the server.
+ * @param {string} options.version - Client version, shown to the server.
+ * @param {string} options.url - The server's HTTP endpoint (e.g. what {@link import('./Http.js').serveMcpHttp} serves).
+ * @param {string} [options.token] - Shorthand for an `Authorization: Bearer <token>` header —
+ *   matches `lib/Guard.js`'s default `tokenHeader` convention for a `withMetaGuard`-protected
+ *   server. Ignored if `headers` already sets `Authorization`.
+ * @param {Record<string, string>} [options.headers] - Additional request headers (e.g. for a
+ *   `withMetaGuard` server configured with a custom `tokenHeader`).
+ * @returns {Promise<Client>} The connected client.
+ */
+export async function connectHttpClient({ name, version, url, token, headers = {} }) {
+	const client = createMcpClient({ name, version })
+	const requestHeaders = token ? { Authorization: `Bearer ${token}`, ...headers } : headers
+	await client.connect(
+		new StreamableHTTPClientTransport(new URL(url), {
+			requestInit: { headers: requestHeaders },
+		}),
+	)
+	return client
+}

package/lib/Gateway.js

@@ -0,0 +1,76 @@
+import { McpServer, fromJsonSchema } from '@modelcontextprotocol/server'
+
+/**
+ * A validator provider that never actually validates — used for gateway-proxied tools, whose
+ * arguments are already validated by the upstream server when the call is forwarded. Re-running
+ * a second, independent JSON Schema implementation over the same input here would risk rejecting
+ * (or silently reshaping) input the upstream itself considers valid, for zero benefit.
+ * @type {import('./Validator.js').principiaJsonSchemaValidator}
+ */
+const passthroughValidator = {
+	getValidator: () => (input) => ({ valid: true, data: input }),
+}
+
+/**
+ * @typedef {Object} UpstreamDef
+ * @property {string} name - Namespace prefix for this upstream's tools in the gateway
+ *   (`"<name>.<toolName>"`) — must be unique among the gateway's upstreams.
+ * @property {import('@modelcontextprotocol/client').Client} client - An already-connected
+ *   client (see `lib/Client.js`'s `connectStdioClient`/`connectHttpClient`). The gateway reads
+ *   its tool list and forwards calls to it, but does not own its lifecycle — closing it is the
+ *   caller's responsibility.
+ */
+
+/**
+ * Builds an MCP server that aggregates a list of already-connected upstream MCP clients into
+ * one: every upstream's tools are listed once, up front, and re-exposed as
+ * `"<upstream.name>.<toolName>"`, with calls forwarded to the owning upstream and its result
+ * passed straight through. Tool arguments are validated once, by the upstream itself — the
+ * gateway does not re-validate.
+ *
+ * Building a gateway does real work (one `listTools()` round trip per upstream) — build it
+ * once and reuse the same instance for every connection, rather than rebuilding per request;
+ * `createMcpHandler`'s per-request factory can safely return the same instance every time.
+ * @param {Object} options
+ * @param {string} options.name - MCP server name, shown to clients.
+ * @param {string} options.version - MCP server version, shown to clients.
+ * @param {UpstreamDef[]} options.upstreams - Already-connected upstream clients to aggregate.
+ * @param {import('@modelcontextprotocol/server').ServerCapabilities} [options.capabilities] -
+ *   Defaults to `{ tools: {} }`.
+ * @returns {Promise<McpServer>}
+ * @throws {Error} If two upstreams share a `name`.
+ */
+export async function createMcpGateway({ name, version, upstreams, capabilities = { tools: {} } }) {
+	const seen = new Set()
+	for (const upstream of upstreams) {
+		if (seen.has(upstream.name)) {
+			throw new Error(`Duplicate upstream name '${upstream.name}'`)
+		}
+		seen.add(upstream.name)
+	}
+
+	const server = new McpServer({ name, version }, { capabilities })
+
+	for (const upstream of upstreams) {
+		const { tools } = await upstream.client.listTools()
+
+		for (const tool of tools) {
+			const config = {
+				description: tool.description,
+				// Always declared, even as an empty passthrough — matches lib/Server.js's own
+				// rule: registerTool only calls the callback as (args, extra) when inputSchema
+				// is set, collapsing to a single (extra) argument otherwise.
+				inputSchema: fromJsonSchema(
+					tool.inputSchema ?? { type: 'object', properties: {} },
+					passthroughValidator,
+				),
+			}
+
+			server.registerTool(`${upstream.name}.${tool.name}`, config, async (args) => {
+				return upstream.client.callTool({ name: tool.name, arguments: args })
+			})
+		}
+	}
+
+	return server
+}

package/lib/Guard.js

@@ -0,0 +1,67 @@
+/** Header a token is read from by default; a `"Bearer "` prefix, if present, is stripped. */
+export const DEFAULT_TOKEN_HEADER = 'authorization'
+
+/**
+ * Reads a token from the incoming HTTP request's headers, via the raw `Request` MCP's HTTP
+ * transport exposes at `extra.http.req` — `undefined` over stdio (or any non-HTTP transport),
+ * which has no headers at all; see the `MetaGuard`-equivalent design note in AGENTS.md.
+ * @param {Object} extra - The MCP tool callback's context argument.
+ * @param {string} headerName
+ * @returns {string|undefined}
+ */
+function extractToken(extra, headerName) {
+	const raw = extra?.http?.req?.headers?.get?.(headerName)
+	if (!raw) return undefined
+	return raw.replace(/^Bearer\s+/i, '')
+}
+
+/**
+ * Wraps a {@link import('./Server.js').ServiceDef} so every action requires a resolved token
+ * before its handler runs — the MCP-side equivalent of `empyria-guard-moleculer`'s
+ * `MetaGuard.middleware.js`. Optional and per-service: a service without a `resolveToken`
+ * function is returned unchanged (public, unguarded).
+ *
+ * The resolved value `resolveToken` returns is attached to the handler's `extra.user`,
+ * mirroring Moleculer's `ctx.meta.user`.
+ * @param {import('./Server.js').ServiceDef & {resolveToken?: (tokenKey: string, context: {service: string, action: string, extra: Object}) => Promise<*>}} service
+ * @param {Object} [options]
+ * @param {string} [options.tokenHeader] - Header to read the token from. Defaults to
+ *   {@link DEFAULT_TOKEN_HEADER} (`"authorization"`, with an optional `"Bearer "` prefix stripped).
+ * @returns {import('./Server.js').ServiceDef}
+ */
+export function withMetaGuard(service, options = {}) {
+	const { resolveToken } = service
+	if (typeof resolveToken !== 'function') return service
+
+	const tokenHeader = options.tokenHeader ?? DEFAULT_TOKEN_HEADER
+	const guardedActions = {}
+
+	for (const [actionName, action] of Object.entries(service.actions ?? {})) {
+		const isBareHandler = typeof action === 'function'
+		const handler = isBareHandler ? action : action.handler
+
+		const guardedHandler = async (params, extra) => {
+			const tokenKey = extractToken(extra, tokenHeader)
+			if (!tokenKey) {
+				throw new Error(`${service.name}.${actionName}: missing auth token`)
+			}
+
+			const user = await resolveToken(tokenKey, {
+				service: service.name,
+				action: actionName,
+				extra,
+			})
+			if (!user) {
+				throw new Error(`${service.name}.${actionName}: invalid auth token`)
+			}
+
+			return handler(params, { ...extra, user })
+		}
+
+		guardedActions[actionName] = isBareHandler
+			? guardedHandler
+			: { ...action, handler: guardedHandler }
+	}
+
+	return { ...service, actions: guardedActions }
+}

package/lib/Http.js

@@ -0,0 +1,37 @@
+import { createMcpHandler } from '@modelcontextprotocol/server'
+
+import { createMcpServer } from './Server.js'
+
+/**
+ * Builds a Web-standard (`fetch`) MCP HTTP handler for a list of Moleculer-shaped services —
+ * runtime-agnostic; works with `Bun.serve`, Deno, Cloudflare Workers, Hono, or anything else
+ * that speaks the Fetch API. A fresh {@link createMcpServer} instance is built per request
+ * (this repo's `Server.js` builder is cheap — pure registration, no I/O), matching the MCP
+ * HTTP transport's default stateless serving idiom.
+ * @param {Parameters<typeof createMcpServer>[0]} options - Same shape as {@link createMcpServer}'s options.
+ * @returns {{fetch: (request: Request) => Promise<Response>, close: () => Promise<void>}}
+ */
+export function createMcpHttpHandler(options) {
+	return createMcpHandler(() => createMcpServer(options))
+}
+
+/**
+ * Bun-only convenience: builds an MCP HTTP handler (see {@link createMcpHttpHandler}) and
+ * serves it with `Bun.serve`.
+ * @param {Parameters<typeof createMcpServer>[0]} options - Same shape as {@link createMcpServer}'s options.
+ * @param {Object} [bunOptions] - Passed through to `Bun.serve` (e.g. `port`, `hostname`, `tls`).
+ *   `fetch` is always taken from the built MCP handler and cannot be overridden here.
+ * @returns {ReturnType<typeof Bun.serve> & {close: () => Promise<void>}} The running Bun
+ *   server, with an added `close()` that stops both the MCP handler and the Bun server.
+ */
+export function serveMcpHttp(options, bunOptions = {}) {
+	const handler = createMcpHttpHandler(options)
+	const server = Bun.serve({ ...bunOptions, fetch: handler.fetch })
+
+	return Object.assign(server, {
+		close: async () => {
+			await handler.close()
+			server.stop()
+		},
+	})
+}