@sezzlee/openapi-mcp 0.0.0-stage → 0.1.0

package/dist/platform/files.d.ts

@@ -0,0 +1,9 @@
+export declare const directoryOf: (path: string) => string;
+export declare function readText(path: string): Promise<string>;
+/**
+ * Reads a file an external `$ref` names.
+ *
+ * Guard: the path is checked against the root on its realpath, not on the string, so neither
+ * `../` nor a symbolic link can make a document read a file outside the directory it came from.
+ */
+export declare function readWithin(root: string, path: string): Promise<string>;

package/dist/platform/files.js

@@ -0,0 +1,21 @@
+import { readFile, realpath } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+export const directoryOf = (path) => dirname(resolve(path));
+export function readText(path) {
+    return readFile(path, "utf8");
+}
+/**
+ * Reads a file an external `$ref` names.
+ *
+ * Guard: the path is checked against the root on its realpath, not on the string, so neither
+ * `../` nor a symbolic link can make a document read a file outside the directory it came from.
+ */
+export async function readWithin(root, path) {
+    const base = await realpath(root);
+    const target = await realpath(resolve(base, path));
+    const offset = relative(base, target);
+    if (offset.startsWith("..") || isAbsolute(offset)) {
+        throw new Error(`sezzlee-openapi: '${path}' is outside the document's directory.`);
+    }
+    return readFile(target, "utf8");
+}

package/dist/server.d.ts

@@ -0,0 +1,14 @@
+import { McpServer } from "@modelcontextprotocol/server";
+import { type SearchRankerOptions } from "@sezzlee/core";
+import type { GatewayCatalog } from "./catalog/build.js";
+import { type InvokeLimits } from "./invoke/invoke.js";
+import type { BoundedFetch } from "./net/fetch.js";
+/** Where the http transport's auth gate leaves the token the caller's own was exchanged for. */
+export declare const exchangedTokenKey = "sezzleeExchangedToken";
+/**
+ * @param options.ranker a host ranker for `search_tools`, for an embedder; the CLI binds none
+ */
+export interface OpenApiMcpServerOptions {
+    readonly ranker?: SearchRankerOptions;
+}
+export declare function createOpenApiMcpServer(gateway: GatewayCatalog, fetcher: BoundedFetch, limits: InvokeLimits, options?: OpenApiMcpServerOptions): McpServer;

package/dist/server.js

@@ -0,0 +1,112 @@
+import { createRequire } from "node:module";
+import { McpServer } from "@modelcontextprotocol/server";
+import { assertCatalogValid, createDetail, defaultSearchLimit, emitGuarded, evaluateVisibility, invokeArgumentsDescription, invokeDescription, loadDescription, missingArgument, operationNameDescription, searchCatalog, searchDescription, searchDetailDescription, searchLimitDescription, searchQueryDescription, searchTagsDescription, textResult, unknownTool, wrongArgumentType, } from "@sezzlee/core";
+import { z } from "zod";
+import { invokeEntry } from "./invoke/invoke.js";
+const { version } = createRequire(import.meta.url)("../package.json");
+/** Where the http transport's auth gate leaves the token the caller's own was exchanged for. */
+export const exchangedTokenKey = "sezzleeExchangedToken";
+/**
+ * Guard: `name` binds as `unknown` so a call that misspells the argument reaches the handler and
+ * leaves as an sezzlee envelope; a `z.string()` would be rejected by the framework's validator with
+ * a bare text error the agent cannot parse. The published schema is byte-identical to the SDKs'.
+ */
+function namedArgument(description) {
+    return z.unknown().optional().meta({ type: "string", description });
+}
+/**
+ * A document says which credential a call needs, never which caller may make it, so a caller is
+ * always of unknown identity here and only an explicitly anonymous operation is certain.
+ */
+function decide(entry) {
+    return evaluateVisibility(entry.descriptor.auth, { identity: "unknown" });
+}
+const visible = (decision) => decision !== "deny";
+export function createOpenApiMcpServer(gateway, fetcher, limits, options = {}) {
+    const { catalog } = gateway;
+    const budget = () => limits.maxResponseBytes;
+    const server = new McpServer({ name: "sezzlee-openapi", version });
+    server.registerTool("search_tools", {
+        description: searchDescription,
+        inputSchema: z.object({
+            query: z.string().default("").describe(searchQueryDescription),
+            limit: z
+                .number()
+                .int()
+                .default(defaultSearchLimit)
+                .describe(searchLimitDescription),
+            detail: z
+                .enum(["card", "schema"])
+                .catch("card")
+                .default("card")
+                .describe(searchDetailDescription),
+            tags: z
+                .array(z.string())
+                .describe(searchTagsDescription)
+                .optional()
+                .meta({ default: null }),
+        }),
+    }, async ({ query, limit, detail, tags }, ctx) => emitGuarded(budget, async () => {
+        assertCatalogValid(catalog.fatal);
+        const signal = ctx?.mcpReq?.signal;
+        return searchCatalog({
+            catalog,
+            query,
+            limit,
+            detail,
+            tags,
+            decide,
+            visible,
+            ...(options.ranker === undefined ? {} : { ranker: options.ranker }),
+            ...(signal === undefined ? {} : { signal }),
+        });
+    }));
+    server.registerTool("load_tool", {
+        description: loadDescription,
+        inputSchema: z
+            .object({ name: namedArgument(operationNameDescription) })
+            .meta({ required: ["name"] }),
+    }, async ({ name }) => emitGuarded(budget, async () => {
+        if (name === undefined) {
+            return missingArgument("load_tool", "name");
+        }
+        if (typeof name !== "string") {
+            return wrongArgumentType("load_tool", "name", name);
+        }
+        assertCatalogValid(catalog.fatal);
+        const entry = catalog.byName.get(name);
+        const decision = entry === undefined ? "deny" : decide(entry);
+        if (entry === undefined || !visible(decision)) {
+            return unknownTool(name);
+        }
+        return textResult(createDetail(entry.tool, decision), false);
+    }));
+    server.registerTool("invoke_tool", {
+        description: invokeDescription,
+        inputSchema: z
+            .object({
+            name: namedArgument(operationNameDescription),
+            arguments: z
+                .unknown()
+                .optional()
+                .meta({ description: invokeArgumentsDescription }),
+        })
+            .meta({ required: ["name", "arguments"] }),
+    }, async ({ name, arguments: args }, ctx) => emitGuarded(budget, async () => {
+        if (name === undefined) {
+            return missingArgument("invoke_tool", "name");
+        }
+        if (typeof name !== "string") {
+            return wrongArgumentType("invoke_tool", "name", name);
+        }
+        assertCatalogValid(catalog.fatal);
+        const entry = catalog.byName.get(name);
+        if (entry === undefined) {
+            return unknownTool(name);
+        }
+        const context = ctx;
+        const exchanged = context?.http?.authInfo?.extra?.[exchangedTokenKey];
+        return invokeEntry(entry, args, fetcher, limits, context?.mcpReq?.signal, typeof exchanged === "string" ? exchanged : undefined);
+    }));
+    return server;
+}

package/dist/transport/http.d.ts

@@ -0,0 +1,23 @@
+import { type Server } from "node:http";
+import { type McpServer } from "@modelcontextprotocol/server";
+import { type TokenExchange } from "../credentials/token-exchange.js";
+export interface HttpTransportOptions {
+    readonly host: string;
+    readonly port: number;
+    readonly path: string;
+    readonly resource: string;
+    readonly authorizationServers: readonly string[];
+    readonly allowedHostnames: readonly string[];
+}
+/**
+ * Serves the gateway over streamable HTTP, behind a bearer gate when token exchange is configured.
+ * Without it the server has no caller to authenticate; the config then only accepts a loopback
+ * host, so the operator's credentials are not offered to the network.
+ *
+ * Guard: the gate's verifier is the token exchange itself. The gateway cannot check a token it
+ * holds no key for, and the authorization server that can — it issued the token — does so while
+ * exchanging it; a refused exchange is `invalid_token`, so the client is told to re-authorize
+ * rather than handed a tool error it cannot act on. The caller's token never leaves this process
+ * except to that authorization server.
+ */
+export declare function serveHttp(factory: () => McpServer, exchange: TokenExchange | undefined, options: HttpTransportOptions): Promise<Server>;

package/dist/transport/http.js

@@ -0,0 +1,88 @@
+import { createServer } from "node:http";
+import { toNodeHandler } from "@modelcontextprotocol/node";
+import { createMcpHandler, getOAuthProtectedResourceMetadataUrl, hostHeaderValidationResponse, localhostAllowedHostnames, OAuthError, OAuthErrorCode, requireBearerAuth, } from "@modelcontextprotocol/server";
+import { TokenExchangeFailed, } from "../credentials/token-exchange.js";
+import { exchangedTokenKey } from "../server.js";
+/**
+ * Serves the gateway over streamable HTTP, behind a bearer gate when token exchange is configured.
+ * Without it the server has no caller to authenticate; the config then only accepts a loopback
+ * host, so the operator's credentials are not offered to the network.
+ *
+ * Guard: the gate's verifier is the token exchange itself. The gateway cannot check a token it
+ * holds no key for, and the authorization server that can — it issued the token — does so while
+ * exchanging it; a refused exchange is `invalid_token`, so the client is told to re-authorize
+ * rather than handed a tool error it cannot act on. The caller's token never leaves this process
+ * except to that authorization server.
+ */
+export function serveHttp(factory, exchange, options) {
+    const resource = new URL(options.resource);
+    const metadataUrl = getOAuthProtectedResourceMetadataUrl(resource);
+    const metadataPath = new URL(metadataUrl).pathname;
+    const metadata = JSON.stringify({
+        resource: resource.href,
+        authorization_servers: options.authorizationServers,
+        bearer_methods_supported: ["header"],
+    });
+    const handler = createMcpHandler(factory);
+    const gate = exchange === undefined
+        ? undefined
+        : requireBearerAuth({
+            resourceMetadataUrl: metadataUrl,
+            verifier: {
+                async verifyAccessToken(token) {
+                    try {
+                        const exchanged = await exchange.exchange(token);
+                        return {
+                            token,
+                            clientId: "",
+                            scopes: [],
+                            expiresAt: exchanged.expiresAt,
+                            resource,
+                            extra: { [exchangedTokenKey]: exchanged.token },
+                        };
+                    }
+                    catch (error) {
+                        if (error instanceof TokenExchangeFailed && error.rejected) {
+                            throw new OAuthError(OAuthErrorCode.InvalidToken, "token rejected");
+                        }
+                        throw new OAuthError(OAuthErrorCode.ServerError, "the authorization server is unavailable");
+                    }
+                },
+            },
+        });
+    const hostnames = [
+        ...localhostAllowedHostnames(),
+        ...options.allowedHostnames,
+    ];
+    const node = toNodeHandler({
+        async fetch(request) {
+            const rejected = hostHeaderValidationResponse(request, hostnames);
+            if (rejected !== undefined) {
+                return rejected;
+            }
+            const { pathname } = new URL(request.url);
+            if (pathname === metadataPath) {
+                return new Response(metadata, {
+                    headers: { "content-type": "application/json" },
+                });
+            }
+            if (pathname !== options.path) {
+                return new Response(null, { status: 404 });
+            }
+            if (gate === undefined) {
+                return handler.fetch(request);
+            }
+            const auth = await gate(request);
+            if (auth instanceof Response) {
+                return auth;
+            }
+            return handler.fetch(request, { authInfo: auth });
+        },
+    });
+    const server = createServer((req, res) => {
+        void node(req, res);
+    });
+    return new Promise((resolve) => {
+        server.listen(options.port, options.host, () => resolve(server));
+    });
+}

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "@sezzlee/openapi-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "MCP server that exposes an OpenAPI document as a search-first sezzlee catalog over a remote backend.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "mcp-server",
+    "sezzlee",
+    "openapi",
+    "swagger",
+    "api-gateway",
+    "agents"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sezzlee/mcp.git",
+    "directory": "packages/servers/openapi-mcp"
+  },
+  "homepage": "https://github.com/sezzlee/mcp/tree/main/packages/servers/openapi-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/sezzlee/mcp/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "sezzlee-openapi": "./dist/cli.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/node": "^2.0.0",
+    "@modelcontextprotocol/server": "^2.0.0",
+    "@sezzlee/core": "^0.1.0",
+    "@sezzlee/openapi": "^0.1.0",
+    "zod": "^4.5.4"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/client": "^2.0.0",
+    "@sezzlee/oxlint-config": "0.0.0",
+    "@sezzlee/typescript-config": "0.0.0",
+    "@types/node": "^24.3.0",
+    "oxlint": "1.85.0",
+    "typescript": "7.0.2",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc",
+    "dev": "tsc --watch",
+    "lint": "oxlint --deny-warnings",
+    "check-types": "tsc -p tsconfig.test.json",
+    "test": "vitest run"
+  }
 }