@better-forge/mcp 0.1.0 → 0.1.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 BetterStatusPage contributors
-
-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.
+MIT License
+
+Copyright (c) 2026 BetterStatusPage contributors
+
+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,14 +1,14 @@
-# @better-forge/mcp
-
-A Model Context Protocol endpoint for a Fastify app (Streamable HTTP, stateless).
-
-- **Bearer only.** Cookies are never read, so a web page cannot use the endpoint; a request with a foreign `Origin`, or
-  a `Host` that is not the public URL, is refused.
-- **Scoped tools.** Each tool names the permission it needs and whether it only reads, writes, or is destructive (announced to the client as annotations); a tool can only GET, POST, PATCH or PUT, never DELETE; `tools/list` shows a caller only the tools its token may use.
-- **The host's own API does the work.** A tool reads through `ctx.get(path)`, a request to the same app with the caller's
-  `Authorization` header, so validation, permissions, rate limits and audit stay where they are.
-- **Bounded, plain-data output.** Strings are stripped of control, bidi and zero-width characters and cut to 2000
-  characters; a result is cut to 64 KB (a list under `items` is shortened first).
-
-The package knows nothing about what the tools are about; the product supplies them with `defineTool` and the
-authentication with `authenticate`. Depends on: `@better-forge/contracts`.
+# @better-forge/mcp
+
+A Model Context Protocol endpoint for a Fastify app (Streamable HTTP, stateless).
+
+- **Bearer only.** Cookies are never read, so a web page cannot use the endpoint; a request with a foreign `Origin`, or
+  a `Host` that is not the public URL, is refused.
+- **Scoped tools.** Each tool names the permission it needs and whether it only reads, writes, or is destructive (announced to the client as annotations); a tool can only GET, POST, PATCH or PUT, never DELETE; `tools/list` shows a caller only the tools its token may use.
+- **The host's own API does the work.** A tool reads through `ctx.get(path)`, a request to the same app with the caller's
+  `Authorization` header, so validation, permissions, rate limits and audit stay where they are.
+- **Bounded, plain-data output.** Strings are stripped of control, bidi and zero-width characters and cut to 2000
+  characters; a result is cut to 64 KB (a list under `items` is shortened first).
+
+The package knows nothing about what the tools are about; the product supplies them with `defineTool` and the
+authentication with `authenticate`. Depends on: `@better-forge/contracts`.

package/package.json

@@ -1,54 +1,54 @@
-{
-  "name": "@better-forge/mcp",
-  "version": "0.1.0",
-  "description": "Model Context Protocol endpoint for a Fastify app: Bearer-only access, scoped tools, bounded and sanitised output.",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/BElluu/Better-Forge.git",
-    "directory": "packages/mcp"
-  },
-  "homepage": "https://github.com/BElluu/Better-Forge/tree/main/packages/mcp#readme",
-  "bugs": {
-    "url": "https://github.com/BElluu/Better-Forge/issues"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "dist",
-    "src",
-    "!src/**/*.test.*"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "dev": "tsc -p tsconfig.json --watch --preserveWatchOutput"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "1.32.1",
-    "@better-forge/contracts": "0.1.0"
-  },
-  "peerDependencies": {
-    "fastify": "^5.3.2",
-    "zod": "^4.4.3"
-  },
-  "devDependencies": {
-    "@types/node": "^26.6.2",
-    "fastify": "^5.3.2",
-    "typescript": "^5.7.3",
-    "zod": "^4.4.3"
-  },
-  "engines": {
-    "node": ">=26.10.0"
-  }
-}
+{
+  "name": "@better-forge/mcp",
+  "version": "0.1.1",
+  "description": "Model Context Protocol endpoint for a Fastify app: Bearer-only access, scoped tools, bounded and sanitised output.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BElluu/Better-Forge.git",
+    "directory": "packages/mcp"
+  },
+  "homepage": "https://github.com/BElluu/Better-Forge/tree/main/packages/mcp#readme",
+  "bugs": {
+    "url": "https://github.com/BElluu/Better-Forge/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.*"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch --preserveWatchOutput"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.32.1",
+    "@better-forge/contracts": "0.1.1"
+  },
+  "peerDependencies": {
+    "fastify": "^5.3.2",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.2",
+    "fastify": "^5.3.2",
+    "typescript": "^5.7.3",
+    "zod": "^4.4.3"
+  },
+  "engines": {
+    "node": ">=26.10.0"
+  }
+}

package/src/endpoint.ts

@@ -1,163 +1,163 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
-import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'
-import { tokenAllows } from '@better-forge/contracts'
-import { z } from 'zod'
-import type { FastifyInstance, FastifyRequest, onRequestAsyncHookHandler } from 'fastify'
-import { crossSiteProblem } from './guard.js'
-import { boundedJson, cleanDeep, McpToolError, cleanText } from './output.js'
-import { SAFE_PATH, type McpTool, type McpToolContext } from './tools.js'
-
-/** Who is calling: the permissions of the token and the header to hand on to the host's own API. */
-export interface McpCaller {
-  authorization: string
-  scopes: readonly string[]
-}
-
-export interface McpEndpointOptions {
-  /** Path of the endpoint. */
-  path: string
-  name: string
-  version: string
-  /** Shown to the agent once, when it connects. Static text; nothing that came from the data belongs here. */
-  instructions: string
-  tools: readonly McpTool[]
-  /** The caller behind a `Bearer` token, or null. Cookies are never looked at: a browser must not be able to use this endpoint. */
-  authenticate(req: FastifyRequest): Promise<McpCaller | null>
-  /** Whether the endpoint answers at all. Asked first on every request: when false it is indistinguishable from a path that does not exist. */
-  enabled(): boolean | Promise<boolean>
-  /** Whether tools that change data are offered. When false a caller sees only the read-only ones, whatever its token may do. */
-  allowChanges(): boolean | Promise<boolean>
-  /** The address visitors use; known only when configured. */
-  publicUrl(): string | undefined
-  /** Options of @fastify/rate-limit for the route. */
-  rateLimit?: Record<string, unknown>
-}
-
-const MAX_BODY_BYTES = 256 * 1024
-
-/** The caller's view of the host's API: each call is a request to the same app, so its checks, limits and audit apply unchanged. */
-function contextFor(app: FastifyInstance, caller: McpCaller): McpToolContext {
-  return {
-    can: (scope) => tokenAllows(caller.scopes, scope),
-    get: (path) => request('GET', path),
-    send: (method, path, body, contentType) => {
-      // The types already say so; this holds when a tool is written loosely.
-      if (!['POST', 'PATCH', 'PUT'].includes(method)) throw new McpToolError('A tool tried to send a request that is not allowed')
-      return request(method, path, body, contentType)
-    },
-  }
-
-  async function request(method: 'GET' | 'POST' | 'PATCH' | 'PUT', url: string, body?: unknown, bodyType?: string): Promise<unknown> {
-    const [path = '', ...query] = url.split('?')
-    // A request that changes data has no query: a tool must not be able to reach, say, an apply with a flag that deletes.
-    const allowed = ['GET', 'POST', 'PATCH', 'PUT'].includes(method) && SAFE_PATH.test(path) && !path.includes('..') && (method === 'GET' || query.length === 0)
-    if (!allowed) throw new McpToolError('A tool tried to send a request that is not allowed')
-    const headers: Record<string, string> = { authorization: caller.authorization }
-    if (bodyType) headers['content-type'] = bodyType
-    const response = await app.inject({
-      method, url, headers,
-      ...(method === 'GET' ? {} : { payload: bodyType ? String(body) : (body as object | undefined) ?? {} }),
-    })
-    const contentType = String(response.headers['content-type'] ?? '')
-    if (response.statusCode >= 400) {
-      const failure = contentType.includes('json') ? (response.json() as { error?: unknown; problems?: unknown }) : {}
-      const problems = Array.isArray(failure.problems) ? ` ${JSON.stringify(failure.problems).slice(0, 1500)}` : ''
-      throw new McpToolError(`${response.statusCode}: ${typeof failure.error === 'string' ? cleanText(failure.error) : 'The request failed'}${cleanText(problems)}`)
-    }
-    if (response.statusCode === 204) return { ok: true }
-    return contentType.includes('json') ? response.json() : response.body
-  }
-}
-
-function annotationsFor(access: McpTool['access']) {
-  return access === 'read'
-    ? { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
-    : { readOnlyHint: false, destructiveHint: access === 'destructive', idempotentHint: false, openWorldHint: false }
-}
-
-function serverFor(app: FastifyInstance, options: McpEndpointOptions, caller: McpCaller, allowChanges: boolean): McpServer {
-  const server = new McpServer({ name: options.name, version: options.version }, { instructions: options.instructions })
-  const context = contextFor(app, caller)
-  for (const tool of options.tools) {
-    if (!tokenAllows(caller.scopes, tool.scope)) continue
-    if (tool.access !== 'read' && !allowChanges) continue
-    server.registerTool(
-      tool.name,
-      {
-        title: tool.title,
-        description: tool.description,
-        // Strict: an argument that does not exist is an error the agent sees, not a change that silently did not happen.
-        inputSchema: z.strictObject(tool.input),
-        annotations: annotationsFor(tool.access),
-      },
-      async (args: unknown) => {
-        try {
-          const data = await (tool.handler as (args: unknown, ctx: McpToolContext) => Promise<unknown>)(args, context)
-          return { content: [{ type: 'text' as const, text: boundedJson(cleanDeep(data)) }] }
-        } catch (error) {
-          // A refused or failed request is the tool's answer; anything unexpected is reported without its details.
-          const text = error instanceof McpToolError ? error.message : 'The tool failed'
-          return { isError: true, content: [{ type: 'text' as const, text }] }
-        }
-      },
-    )
-  }
-  return server
-}
-
-/**
- * Registers `POST <path>`: the MCP Streamable HTTP transport in its stateless form (a request carries everything, no
- * session is kept). The route accepts a `Bearer` token only and lists just the tools that token may use.
- */
-export function registerMcpEndpoint(app: FastifyInstance, options: McpEndpointOptions): void {
-  // First of everything, before authentication and before the body is read: an endpoint that is off leaks nothing.
-  const gate: onRequestAsyncHookHandler = async (_req, reply) => {
-    let on = false
-    try { on = await options.enabled() } catch { /* not ready: off */ }
-    if (!on) return reply.callNotFound()
-  }
-
-  app.route({
-    method: ['GET', 'DELETE'],
-    url: options.path,
-    onRequest: gate,
-    handler: (_req, reply) => reply.code(405).header('allow', 'POST').send({ error: 'Use POST' }),
-  })
-
-  app.post(options.path, { onRequest: gate, bodyLimit: MAX_BODY_BYTES, config: { rateLimit: options.rateLimit } }, async (req, reply) => {
-    const problem = crossSiteProblem(req.headers, options.publicUrl())
-    if (problem) return reply.code(403).send({ error: problem })
-
-    // One call per request: a batch would spend one rate-limit hit on up to a hundred calls.
-    if (Array.isArray(req.body)) return reply.code(400).send({ error: 'Batched requests are not accepted' })
-
-    let caller: McpCaller | null = null
-    try { caller = await options.authenticate(req) } catch { /* not signed in */ }
-    if (!caller) return reply.code(401).header('www-authenticate', 'Bearer realm="mcp"').send({ error: 'Unauthorized' })
-
-    // Not knowing is not allowing.
-    let allowChanges = false
-    try { allowChanges = await options.allowChanges() } catch { /* read-only */ }
-    const server = serverFor(app, options, caller, allowChanges)
-    // Without a session id generator the transport is stateless.
-    const transport = new StreamableHTTPServerTransport({ enableJsonResponse: true })
-    // The transport writes the response itself, so Fastify's own hooks no longer run: set what they would.
-    reply.hijack()
-    const res = reply.raw
-    res.setHeader('x-content-type-options', 'nosniff')
-    res.setHeader('cache-control', 'no-store')
-    res.on('close', () => { void transport.close(); void server.close() })
-    try {
-      // The SDK's own transport type does not satisfy exactOptionalPropertyTypes.
-      await server.connect(transport as unknown as Parameters<McpServer['connect']>[0])
-      await transport.handleRequest(req.raw, res, req.body)
-    } catch {
-      if (res.headersSent) res.destroy()
-      else {
-        res.statusCode = 500
-        res.setHeader('content-type', 'application/json')
-        res.end(JSON.stringify({ jsonrpc: '2.0', error: { code: -32603, message: 'Internal error' }, id: null }))
-      }
-    }
-  })
-}
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'
+import { tokenAllows } from '@better-forge/contracts'
+import { z } from 'zod'
+import type { FastifyInstance, FastifyRequest, onRequestAsyncHookHandler } from 'fastify'
+import { crossSiteProblem } from './guard.js'
+import { boundedJson, cleanDeep, McpToolError, cleanText } from './output.js'
+import { SAFE_PATH, type McpTool, type McpToolContext } from './tools.js'
+
+/** Who is calling: the permissions of the token and the header to hand on to the host's own API. */
+export interface McpCaller {
+  authorization: string
+  scopes: readonly string[]
+}
+
+export interface McpEndpointOptions {
+  /** Path of the endpoint. */
+  path: string
+  name: string
+  version: string
+  /** Shown to the agent once, when it connects. Static text; nothing that came from the data belongs here. */
+  instructions: string
+  tools: readonly McpTool[]
+  /** The caller behind a `Bearer` token, or null. Cookies are never looked at: a browser must not be able to use this endpoint. */
+  authenticate(req: FastifyRequest): Promise<McpCaller | null>
+  /** Whether the endpoint answers at all. Asked first on every request: when false it is indistinguishable from a path that does not exist. */
+  enabled(): boolean | Promise<boolean>
+  /** Whether tools that change data are offered. When false a caller sees only the read-only ones, whatever its token may do. */
+  allowChanges(): boolean | Promise<boolean>
+  /** The address visitors use; known only when configured. */
+  publicUrl(): string | undefined
+  /** Options of @fastify/rate-limit for the route. */
+  rateLimit?: Record<string, unknown>
+}
+
+const MAX_BODY_BYTES = 256 * 1024
+
+/** The caller's view of the host's API: each call is a request to the same app, so its checks, limits and audit apply unchanged. */
+function contextFor(app: FastifyInstance, caller: McpCaller): McpToolContext {
+  return {
+    can: (scope) => tokenAllows(caller.scopes, scope),
+    get: (path) => request('GET', path),
+    send: (method, path, body, contentType) => {
+      // The types already say so; this holds when a tool is written loosely.
+      if (!['POST', 'PATCH', 'PUT'].includes(method)) throw new McpToolError('A tool tried to send a request that is not allowed')
+      return request(method, path, body, contentType)
+    },
+  }
+
+  async function request(method: 'GET' | 'POST' | 'PATCH' | 'PUT', url: string, body?: unknown, bodyType?: string): Promise<unknown> {
+    const [path = '', ...query] = url.split('?')
+    // A request that changes data has no query: a tool must not be able to reach, say, an apply with a flag that deletes.
+    const allowed = ['GET', 'POST', 'PATCH', 'PUT'].includes(method) && SAFE_PATH.test(path) && !path.includes('..') && (method === 'GET' || query.length === 0)
+    if (!allowed) throw new McpToolError('A tool tried to send a request that is not allowed')
+    const headers: Record<string, string> = { authorization: caller.authorization }
+    if (bodyType) headers['content-type'] = bodyType
+    const response = await app.inject({
+      method, url, headers,
+      ...(method === 'GET' ? {} : { payload: bodyType ? String(body) : (body as object | undefined) ?? {} }),
+    })
+    const contentType = String(response.headers['content-type'] ?? '')
+    if (response.statusCode >= 400) {
+      const failure = contentType.includes('json') ? (response.json() as { error?: unknown; problems?: unknown }) : {}
+      const problems = Array.isArray(failure.problems) ? ` ${JSON.stringify(failure.problems).slice(0, 1500)}` : ''
+      throw new McpToolError(`${response.statusCode}: ${typeof failure.error === 'string' ? cleanText(failure.error) : 'The request failed'}${cleanText(problems)}`)
+    }
+    if (response.statusCode === 204) return { ok: true }
+    return contentType.includes('json') ? response.json() : response.body
+  }
+}
+
+function annotationsFor(access: McpTool['access']) {
+  return access === 'read'
+    ? { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+    : { readOnlyHint: false, destructiveHint: access === 'destructive', idempotentHint: false, openWorldHint: false }
+}
+
+function serverFor(app: FastifyInstance, options: McpEndpointOptions, caller: McpCaller, allowChanges: boolean): McpServer {
+  const server = new McpServer({ name: options.name, version: options.version }, { instructions: options.instructions })
+  const context = contextFor(app, caller)
+  for (const tool of options.tools) {
+    if (!tokenAllows(caller.scopes, tool.scope)) continue
+    if (tool.access !== 'read' && !allowChanges) continue
+    server.registerTool(
+      tool.name,
+      {
+        title: tool.title,
+        description: tool.description,
+        // Strict: an argument that does not exist is an error the agent sees, not a change that silently did not happen.
+        inputSchema: z.strictObject(tool.input),
+        annotations: annotationsFor(tool.access),
+      },
+      async (args: unknown) => {
+        try {
+          const data = await (tool.handler as (args: unknown, ctx: McpToolContext) => Promise<unknown>)(args, context)
+          return { content: [{ type: 'text' as const, text: boundedJson(cleanDeep(data)) }] }
+        } catch (error) {
+          // A refused or failed request is the tool's answer; anything unexpected is reported without its details.
+          const text = error instanceof McpToolError ? error.message : 'The tool failed'
+          return { isError: true, content: [{ type: 'text' as const, text }] }
+        }
+      },
+    )
+  }
+  return server
+}
+
+/**
+ * Registers `POST <path>`: the MCP Streamable HTTP transport in its stateless form (a request carries everything, no
+ * session is kept). The route accepts a `Bearer` token only and lists just the tools that token may use.
+ */
+export function registerMcpEndpoint(app: FastifyInstance, options: McpEndpointOptions): void {
+  // First of everything, before authentication and before the body is read: an endpoint that is off leaks nothing.
+  const gate: onRequestAsyncHookHandler = async (_req, reply) => {
+    let on = false
+    try { on = await options.enabled() } catch { /* not ready: off */ }
+    if (!on) return reply.callNotFound()
+  }
+
+  app.route({
+    method: ['GET', 'DELETE'],
+    url: options.path,
+    onRequest: gate,
+    handler: (_req, reply) => reply.code(405).header('allow', 'POST').send({ error: 'Use POST' }),
+  })
+
+  app.post(options.path, { onRequest: gate, bodyLimit: MAX_BODY_BYTES, config: { rateLimit: options.rateLimit } }, async (req, reply) => {
+    const problem = crossSiteProblem(req.headers, options.publicUrl())
+    if (problem) return reply.code(403).send({ error: problem })
+
+    // One call per request: a batch would spend one rate-limit hit on up to a hundred calls.
+    if (Array.isArray(req.body)) return reply.code(400).send({ error: 'Batched requests are not accepted' })
+
+    let caller: McpCaller | null = null
+    try { caller = await options.authenticate(req) } catch { /* not signed in */ }
+    if (!caller) return reply.code(401).header('www-authenticate', 'Bearer realm="mcp"').send({ error: 'Unauthorized' })
+
+    // Not knowing is not allowing.
+    let allowChanges = false
+    try { allowChanges = await options.allowChanges() } catch { /* read-only */ }
+    const server = serverFor(app, options, caller, allowChanges)
+    // Without a session id generator the transport is stateless.
+    const transport = new StreamableHTTPServerTransport({ enableJsonResponse: true })
+    // The transport writes the response itself, so Fastify's own hooks no longer run: set what they would.
+    reply.hijack()
+    const res = reply.raw
+    res.setHeader('x-content-type-options', 'nosniff')
+    res.setHeader('cache-control', 'no-store')
+    res.on('close', () => { void transport.close(); void server.close() })
+    try {
+      // The SDK's own transport type does not satisfy exactOptionalPropertyTypes.
+      await server.connect(transport as unknown as Parameters<McpServer['connect']>[0])
+      await transport.handleRequest(req.raw, res, req.body)
+    } catch {
+      if (res.headersSent) res.destroy()
+      else {
+        res.statusCode = 500
+        res.setHeader('content-type', 'application/json')
+        res.end(JSON.stringify({ jsonrpc: '2.0', error: { code: -32603, message: 'Internal error' }, id: null }))
+      }
+    }
+  })
+}

package/src/guard.ts

@@ -1,19 +1,19 @@
-import type { IncomingHttpHeaders } from 'node:http'
-
-function parse(publicUrl: string | undefined): URL | null {
-  if (!publicUrl) return null
-  try { return new URL(publicUrl) } catch { return null }
-}
-
-/**
- * Why a request must not reach the endpoint, or null. Clients of this endpoint (CLI tools, desktop apps) send no
- * `Origin`; a browser always does, so any foreign origin is refused whatever the method. With a public URL known the
- * `Host` header must be that host too, so a name that resolves to this server by DNS rebinding gets nothing.
- */
-export function crossSiteProblem(headers: IncomingHttpHeaders, publicUrl: string | undefined): string | null {
-  const own = parse(publicUrl)
-  const origin = headers.origin
-  if (origin !== undefined && origin !== own?.origin) return 'Requests from a web page are not accepted'
-  if (own && headers.host?.toLowerCase() !== own.host.toLowerCase()) return 'The Host header does not match the public URL'
-  return null
-}
+import type { IncomingHttpHeaders } from 'node:http'
+
+function parse(publicUrl: string | undefined): URL | null {
+  if (!publicUrl) return null
+  try { return new URL(publicUrl) } catch { return null }
+}
+
+/**
+ * Why a request must not reach the endpoint, or null. Clients of this endpoint (CLI tools, desktop apps) send no
+ * `Origin`; a browser always does, so any foreign origin is refused whatever the method. With a public URL known the
+ * `Host` header must be that host too, so a name that resolves to this server by DNS rebinding gets nothing.
+ */
+export function crossSiteProblem(headers: IncomingHttpHeaders, publicUrl: string | undefined): string | null {
+  const own = parse(publicUrl)
+  const origin = headers.origin
+  if (origin !== undefined && origin !== own?.origin) return 'Requests from a web page are not accepted'
+  if (own && headers.host?.toLowerCase() !== own.host.toLowerCase()) return 'The Host header does not match the public URL'
+  return null
+}

package/src/index.ts

@@ -1,6 +1,6 @@
-export { registerMcpEndpoint } from './endpoint.js'
-export type { McpCaller, McpEndpointOptions } from './endpoint.js'
-export { crossSiteProblem } from './guard.js'
-export { boundedJson, cleanDeep, cleanText, McpToolError } from './output.js'
-export { defineTool, query } from './tools.js'
-export type { McpTool, McpToolContext, McpToolDefinition } from './tools.js'
+export { registerMcpEndpoint } from './endpoint.js'
+export type { McpCaller, McpEndpointOptions } from './endpoint.js'
+export { crossSiteProblem } from './guard.js'
+export { boundedJson, cleanDeep, cleanText, McpToolError } from './output.js'
+export { defineTool, query } from './tools.js'
+export type { McpTool, McpToolContext, McpToolDefinition } from './tools.js'

package/src/output.ts

@@ -1,54 +1,54 @@
-/** Text that came from outside the instance (a monitored system, a visitor, an import) must reach an agent as plain data. */
-const MAX_TEXT_LENGTH = 2000
-const MAX_DEPTH = 12
-const MAX_OUTPUT_BYTES = 64 * 1024
-
-/** An escape sequence that sets colours or moves the cursor. */
-const ANSI = new RegExp(String.raw`${String.fromCharCode(27)}\[[0-9;?]*[ -/]*[@-~]`, 'g')
-
-/**
- * Control characters (tab and line breaks stay), bidi controls, zero-width characters, the byte order mark, variation
- * selectors, fillers and the Unicode tag characters, which people cannot see but a model reads.
- */
-const INVISIBLE: ReadonlyArray<readonly [number, number]> = [
-  [0x00, 0x08], [0x0b, 0x0c], [0x0e, 0x1f], [0x7f, 0x9f],
-  [0x00ad, 0x00ad], [0x061c, 0x061c], [0x115f, 0x1160], [0x180e, 0x180e],
-  [0x200b, 0x200f], [0x2028, 0x202e], [0x2060, 0x2064], [0x2066, 0x2069], [0x3164, 0x3164],
-  [0xfe00, 0xfe0f], [0xfeff, 0xfeff], [0xe0000, 0xe007f], [0xe0100, 0xe01ef],
-]
-
-const isInvisible = (code: number): boolean => INVISIBLE.some(([from, to]) => code >= from && code <= to)
-
-export function cleanText(value: string): string {
-  const clean = Array.from(value.replace(ANSI, '')).filter((char) => !isInvisible(char.codePointAt(0)!)).join('')
-  return clean.length > MAX_TEXT_LENGTH ? `${clean.slice(0, MAX_TEXT_LENGTH)}…` : clean
-}
-
-/** Every string in a result, cleaned. */
-export function cleanDeep(value: unknown, depth = 0): unknown {
-  if (typeof value === 'string') return cleanText(value)
-  if (value === null || typeof value !== 'object') return value
-  // Nothing below the limit is passed on unchecked.
-  if (depth >= MAX_DEPTH) return '[nested too deep]'
-  if (Array.isArray(value)) return value.map((each) => cleanDeep(each, depth + 1))
-  return Object.fromEntries(Object.entries(value).map(([key, each]) => [cleanText(key), cleanDeep(each, depth + 1)]))
-}
-
-/** A failure the agent should read as the tool's answer rather than as a crash. */
-export class McpToolError extends Error {}
-
-/** A tool result as text. A list under `items` is shortened until it fits; anything else that is too large is refused. */
-export function boundedJson(data: unknown): string {
-  const text = JSON.stringify(data)
-  if (Buffer.byteLength(text) <= MAX_OUTPUT_BYTES) return text
-  const holder = data as { items?: unknown[] } | null
-  if (holder && typeof holder === 'object' && Array.isArray(holder.items)) {
-    let keep = holder.items.length
-    while (keep > 0) {
-      keep = Math.floor(keep / 2)
-      const shortened = JSON.stringify({ ...holder, items: holder.items.slice(0, keep), truncated: true, returnedItems: keep })
-      if (Buffer.byteLength(shortened) <= MAX_OUTPUT_BYTES) return shortened
-    }
-  }
-  throw new McpToolError('The result is too large to return. Narrow the query (a shorter period, a smaller limit, a filter).')
-}
+/** Text that came from outside the instance (a monitored system, a visitor, an import) must reach an agent as plain data. */
+const MAX_TEXT_LENGTH = 2000
+const MAX_DEPTH = 12
+const MAX_OUTPUT_BYTES = 64 * 1024
+
+/** An escape sequence that sets colours or moves the cursor. */
+const ANSI = new RegExp(String.raw`${String.fromCharCode(27)}\[[0-9;?]*[ -/]*[@-~]`, 'g')
+
+/**
+ * Control characters (tab and line breaks stay), bidi controls, zero-width characters, the byte order mark, variation
+ * selectors, fillers and the Unicode tag characters, which people cannot see but a model reads.
+ */
+const INVISIBLE: ReadonlyArray<readonly [number, number]> = [
+  [0x00, 0x08], [0x0b, 0x0c], [0x0e, 0x1f], [0x7f, 0x9f],
+  [0x00ad, 0x00ad], [0x061c, 0x061c], [0x115f, 0x1160], [0x180e, 0x180e],
+  [0x200b, 0x200f], [0x2028, 0x202e], [0x2060, 0x2064], [0x2066, 0x2069], [0x3164, 0x3164],
+  [0xfe00, 0xfe0f], [0xfeff, 0xfeff], [0xe0000, 0xe007f], [0xe0100, 0xe01ef],
+]
+
+const isInvisible = (code: number): boolean => INVISIBLE.some(([from, to]) => code >= from && code <= to)
+
+export function cleanText(value: string): string {
+  const clean = Array.from(value.replace(ANSI, '')).filter((char) => !isInvisible(char.codePointAt(0)!)).join('')
+  return clean.length > MAX_TEXT_LENGTH ? `${clean.slice(0, MAX_TEXT_LENGTH)}…` : clean
+}
+
+/** Every string in a result, cleaned. */
+export function cleanDeep(value: unknown, depth = 0): unknown {
+  if (typeof value === 'string') return cleanText(value)
+  if (value === null || typeof value !== 'object') return value
+  // Nothing below the limit is passed on unchecked.
+  if (depth >= MAX_DEPTH) return '[nested too deep]'
+  if (Array.isArray(value)) return value.map((each) => cleanDeep(each, depth + 1))
+  return Object.fromEntries(Object.entries(value).map(([key, each]) => [cleanText(key), cleanDeep(each, depth + 1)]))
+}
+
+/** A failure the agent should read as the tool's answer rather than as a crash. */
+export class McpToolError extends Error {}
+
+/** A tool result as text. A list under `items` is shortened until it fits; anything else that is too large is refused. */
+export function boundedJson(data: unknown): string {
+  const text = JSON.stringify(data)
+  if (Buffer.byteLength(text) <= MAX_OUTPUT_BYTES) return text
+  const holder = data as { items?: unknown[] } | null
+  if (holder && typeof holder === 'object' && Array.isArray(holder.items)) {
+    let keep = holder.items.length
+    while (keep > 0) {
+      keep = Math.floor(keep / 2)
+      const shortened = JSON.stringify({ ...holder, items: holder.items.slice(0, keep), truncated: true, returnedItems: keep })
+      if (Buffer.byteLength(shortened) <= MAX_OUTPUT_BYTES) return shortened
+    }
+  }
+  throw new McpToolError('The result is too large to return. Narrow the query (a shorter period, a smaller limit, a filter).')
+}

package/src/tools.ts

@@ -1,54 +1,54 @@
-import type { z } from 'zod'
-
-/** What a tool may do with the host application: read its own API with the credentials of the caller. */
-export interface McpToolContext {
-  /** True when the caller's token holds the permission. */
-  can(scope: string): boolean
-  /** GET a path of the host application's API (`/api/v1/admin/monitors`); JSON comes back parsed, anything else as text. */
-  get(path: string): Promise<unknown>
-  /** POST, PATCH or PUT a body (JSON, or text when `contentType` is given) to a path of the host's API. Nothing else can be sent: no DELETE. */
-  send(method: 'POST' | 'PATCH' | 'PUT', path: string, body: unknown, contentType?: string): Promise<unknown>
-}
-
-/**
- * What a tool does to the data: `read` changes nothing; `write` changes something that can be changed back or that
- * nobody sees yet; `destructive` is visible to other people or cannot be undone (an agent client asks first).
- */
-export type McpAccess = 'read' | 'write' | 'destructive'
-
-/** Where a tool may send a request: a path of the host, nothing that could leave it or change its meaning. */
-export const SAFE_PATH = /^\/(?!\/)[A-Za-z0-9_\-./]*$/
-
-export interface McpTool {
-  name: string
-  title: string
-  description: string
-  /** The permission a token needs to see and call the tool. */
-  scope: string
-  access: McpAccess
-  input: z.ZodRawShape
-  handler(args: never, ctx: McpToolContext): Promise<unknown>
-}
-
-export interface McpToolDefinition<Shape extends z.ZodRawShape> {
-  name: string
-  title: string
-  description: string
-  scope: string
-  /** Defaults to `read`. */
-  access?: McpAccess
-  input: Shape
-  handler(args: z.infer<z.ZodObject<Shape>>, ctx: McpToolContext): Promise<unknown>
-}
-
-export function defineTool<Shape extends z.ZodRawShape>(definition: McpToolDefinition<Shape>): McpTool {
-  return { access: 'read', ...definition } as unknown as McpTool
-}
-
-/** Query string from the values that were given. */
-export function query(values: Record<string, string | number | boolean | undefined>): string {
-  const params = new URLSearchParams()
-  for (const [key, value] of Object.entries(values)) if (value !== undefined) params.set(key, String(value))
-  const text = params.toString()
-  return text ? `?${text}` : ''
-}
+import type { z } from 'zod'
+
+/** What a tool may do with the host application: read its own API with the credentials of the caller. */
+export interface McpToolContext {
+  /** True when the caller's token holds the permission. */
+  can(scope: string): boolean
+  /** GET a path of the host application's API (`/api/v1/admin/monitors`); JSON comes back parsed, anything else as text. */
+  get(path: string): Promise<unknown>
+  /** POST, PATCH or PUT a body (JSON, or text when `contentType` is given) to a path of the host's API. Nothing else can be sent: no DELETE. */
+  send(method: 'POST' | 'PATCH' | 'PUT', path: string, body: unknown, contentType?: string): Promise<unknown>
+}
+
+/**
+ * What a tool does to the data: `read` changes nothing; `write` changes something that can be changed back or that
+ * nobody sees yet; `destructive` is visible to other people or cannot be undone (an agent client asks first).
+ */
+export type McpAccess = 'read' | 'write' | 'destructive'
+
+/** Where a tool may send a request: a path of the host, nothing that could leave it or change its meaning. */
+export const SAFE_PATH = /^\/(?!\/)[A-Za-z0-9_\-./]*$/
+
+export interface McpTool {
+  name: string
+  title: string
+  description: string
+  /** The permission a token needs to see and call the tool. */
+  scope: string
+  access: McpAccess
+  input: z.ZodRawShape
+  handler(args: never, ctx: McpToolContext): Promise<unknown>
+}
+
+export interface McpToolDefinition<Shape extends z.ZodRawShape> {
+  name: string
+  title: string
+  description: string
+  scope: string
+  /** Defaults to `read`. */
+  access?: McpAccess
+  input: Shape
+  handler(args: z.infer<z.ZodObject<Shape>>, ctx: McpToolContext): Promise<unknown>
+}
+
+export function defineTool<Shape extends z.ZodRawShape>(definition: McpToolDefinition<Shape>): McpTool {
+  return { access: 'read', ...definition } as unknown as McpTool
+}
+
+/** Query string from the values that were given. */
+export function query(values: Record<string, string | number | boolean | undefined>): string {
+  const params = new URLSearchParams()
+  for (const [key, value] of Object.entries(values)) if (value !== undefined) params.set(key, String(value))
+  const text = params.toString()
+  return text ? `?${text}` : ''
+}