hono-mcp-server 0.0.1

package/LICENSE

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

@@ -0,0 +1,63 @@
+# MCP Server for Hono
+
+Expose your [Hono](https://hono.dev) API endpoints as [MCP](https://modelcontextprotocol.io) tools.
+
+## Usage
+
+```ts
+import { Hono } from "hono";
+import { mcp, describe } from "hono-mcp-server";
+
+const app = new Hono()
+  .get(
+    "/users",
+    describe("List all users", (c) => c.json([{ id: 1, name: "Alice" }])),
+  )
+  .get(
+    "/users/:id",
+    describe("Get user by ID", (c) => c.json({ id: c.req.param("id") })),
+  )
+  .post(
+    "/users",
+    describe("Create a user", async (c) => c.json(await c.req.json(), 201)),
+  );
+
+export default mcp(app, {
+  name: "Users API",
+  version: "1.0.0",
+});
+```
+
+This adds an `/mcp` endpoint that exposes your routes as MCP tools.
+
+## Options
+
+```ts
+mcp(app, {
+  name: "API Name", // required
+  version: "1.0.0", // required
+  description: "...", // optional
+  instructions: "...", // optional
+  mcpPath: "/mcp", // optional, default: "/mcp"
+  codemode: false, // optional, see below
+});
+```
+
+## Codemode
+
+Instead of exposing individual routes as tools, codemode exposes `search` and `execute` tools for dynamic API interaction. Requires [Cloudflare Worker Loader](https://developers.cloudflare.com/workers/runtime-apis/bindings/worker-loader/).
+
+```ts
+export default mcp(app, {
+  name: "API",
+  version: "1.0.0",
+  codemode: true,
+});
+```
+
+```jsonc
+// wrangler.jsonc
+{
+  "worker_loaders": [{ "binding": "LOADER" }],
+}
+```

package/dist/index.d.mts

@@ -0,0 +1,48 @@
+import { Env, Handler, Hono } from "hono";
+
+//#region src/mcp.d.ts
+/**
+ * Add a description to a route handler for MCP tool generation.
+ *
+ * @example
+ * ```ts
+ * app.get('/users', describe('List all users', (c) => c.json([])))
+ * ```
+ */
+declare function describe<H extends Handler>(description: string, handler: H): H;
+interface McpOptions {
+  name: string;
+  version: string;
+  title?: string;
+  description?: string;
+  instructions?: string;
+  mcpPath?: string;
+  /** Enable codemode - exposes search/execute tools instead of per-route tools. Requires LOADER binding. */
+  codemode?: boolean;
+  /** Binding name for Worker Loader (default: "LOADER"). Only used when codemode is true. */
+  loaderBinding?: string;
+}
+/**
+ * Wraps a Hono app to add an MCP endpoint that exposes routes as tools.
+ *
+ * @example
+ * ```ts
+ * import { mcp, describe } from 'hono-mcp'
+ *
+ * const app = new Hono()
+ *   .get('/users', describe('List all users', (c) => c.json([])))
+ *   .get('/users/:id', describe('Get user by ID', (c) => c.json({ id: c.req.param('id') })));
+ *
+ * export default mcp(app, { name: 'Users API', version: '1.0.0' });
+ * ```
+ *
+ * @example Codemode (requires Worker Loader binding)
+ * ```ts
+ * export default mcp(app, { name: 'API', version: '1.0.0', codemode: true });
+ * ```
+ *
+ */
+declare function mcp<E extends Env>(app: Hono<E>, options: McpOptions): Hono<E>;
+//#endregion
+export { type McpOptions, describe, mcp };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/mcp.ts"],"mappings":";;;;AAgBA;;;;;AAsBA;AA6DA;iBAnFgB,QAAA,WAAmB,OAAA,CAAA,CAAA,WAAA,UAAA,OAAA,EAAuC,CAAA,GAAI,CAAA;AAAA,UAsB7D,UAAA;EAAA,IAAA;EAAA,OAAA;EAAA,KAAA;EAAA,WAAA;EAAA,YAAA;EAAA,OAAA;EAAA;EAAA,QAAA;EAAA;EAAA,aAAA;AAAA;AAAA;AA6DjB;;;;;;;;;;;;;;;;;;;AA7DiB,iBA6DD,GAAA,WAAc,GAAA,CAAA,CAAA,GAAA,EAAU,IAAA,CAAK,CAAA,GAAA,OAAA,EAAa,UAAA,GAAa,IAAA,CAAK,CAAA"}

package/dist/index.mjs

@@ -0,0 +1,310 @@
+import { z } from "zod";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+
+//#region src/mcp.ts
+const MCP_DESCRIPTION = Symbol("mcp_description");
+/**
+* Add a description to a route handler for MCP tool generation.
+*
+* @example
+* ```ts
+* app.get('/users', describe('List all users', (c) => c.json([])))
+* ```
+*/
+function describe(description, handler) {
+	handler[MCP_DESCRIPTION] = description;
+	return handler;
+}
+function getDescription(handler) {
+	return handler?.[MCP_DESCRIPTION];
+}
+const CORS_HEADERS = {
+	"Access-Control-Allow-Origin": "*",
+	"Access-Control-Allow-Methods": "GET, POST, DELETE, OPTIONS",
+	"Access-Control-Allow-Headers": "Content-Type, Accept, mcp-session-id, mcp-protocol-version",
+	"Access-Control-Expose-Headers": "mcp-session-id",
+	"Access-Control-Max-Age": "86400"
+};
+function withCors(response) {
+	const newHeaders = new Headers(response.headers);
+	for (const [key, value] of Object.entries(CORS_HEADERS)) newHeaders.set(key, value);
+	return new Response(response.body, {
+		status: response.status,
+		statusText: response.statusText,
+		headers: newHeaders
+	});
+}
+/**
+* Wraps a Hono app to add an MCP endpoint that exposes routes as tools.
+*
+* @example
+* ```ts
+* import { mcp, describe } from 'hono-mcp'
+*
+* const app = new Hono()
+*   .get('/users', describe('List all users', (c) => c.json([])))
+*   .get('/users/:id', describe('Get user by ID', (c) => c.json({ id: c.req.param('id') })));
+*
+* export default mcp(app, { name: 'Users API', version: '1.0.0' });
+* ```
+*
+* @example Codemode (requires Worker Loader binding)
+* ```ts
+* export default mcp(app, { name: 'API', version: '1.0.0', codemode: true });
+* ```
+*
+*/
+function mcp(app, options) {
+	const { mcpPath = "/mcp", codemode = false, loaderBinding = "LOADER" } = options;
+	const routes = extractRoutes(app);
+	const serverInfo = {
+		name: options.name,
+		version: options.version,
+		...options.title && { title: options.title },
+		...options.description && { description: options.description }
+	};
+	const createServer = () => new McpServer(serverInfo, options.instructions ? { instructions: options.instructions } : codemode ? { instructions: "Use 'search' to find available endpoints, then 'execute' to run code against the API." } : void 0);
+	const handleMcp = codemode ? async (c) => {
+		if (c.req.method === "OPTIONS") return new Response(null, { headers: CORS_HEADERS });
+		const loader = c.env?.[loaderBinding];
+		if (!loader) return new Response(`Codemode requires ${loaderBinding} binding. Add worker_loaders to wrangler.jsonc.`, { status: 500 });
+		const server = createServer();
+		registerCodemodeTools(server, routes, app, loader);
+		const transport = new WebStandardStreamableHTTPServerTransport();
+		server.connect(transport);
+		return withCors(await transport.handleRequest(c.req.raw));
+	} : async (c) => {
+		if (c.req.method === "OPTIONS") return new Response(null, { headers: CORS_HEADERS });
+		const server = createServer();
+		for (const route of routes) registerTool(server, route, app);
+		const transport = new WebStandardStreamableHTTPServerTransport();
+		server.connect(transport);
+		return withCors(await transport.handleRequest(c.req.raw));
+	};
+	app.all(`${mcpPath}/*`, handleMcp);
+	app.all(mcpPath, handleMcp);
+	return app;
+}
+function extractRoutes(app) {
+	const routes = [];
+	const seen = /* @__PURE__ */ new Set();
+	const honoRoutes = app.routes;
+	if (!honoRoutes) return routes;
+	for (const route of honoRoutes) {
+		const method = route.method.toUpperCase();
+		if (![
+			"GET",
+			"POST",
+			"PUT",
+			"PATCH",
+			"DELETE"
+		].includes(method)) continue;
+		if (route.path.startsWith("/mcp")) continue;
+		const key = `${method} ${route.path}`;
+		if (seen.has(key)) continue;
+		seen.add(key);
+		const description = getDescription(route.handler) || generateDescription(method, route.path);
+		routes.push({
+			method,
+			path: route.path,
+			description
+		});
+	}
+	return routes;
+}
+function generateDescription(method, path) {
+	const resource = path.split("/").filter((p) => p && !p.startsWith(":")).pop() || "resource";
+	return `${{
+		GET: path.includes(":") ? "Get" : "List",
+		POST: "Create",
+		PUT: "Update",
+		PATCH: "Update",
+		DELETE: "Delete"
+	}[method] || method} ${resource}`;
+}
+function generateToolName(method, path) {
+	const cleanPath = path.replace(/^\//, "").replace(/\/:([^/]+)/g, "_by_$1").replace(/\//g, "_").replace(/[^a-zA-Z0-9_]/g, "");
+	return `${method.toLowerCase()}_${cleanPath || "root"}`;
+}
+function extractPathParams(path) {
+	const matches = path.match(/:([^/]+)/g);
+	return matches ? matches.map((m) => m.slice(1)) : [];
+}
+function registerTool(server, route, app) {
+	const toolName = generateToolName(route.method, route.path);
+	const pathParams = extractPathParams(route.path);
+	const inputShape = {};
+	for (const param of pathParams) inputShape[param] = z.string().describe(`Path parameter: ${param}`);
+	if ([
+		"POST",
+		"PUT",
+		"PATCH"
+	].includes(route.method)) inputShape["body"] = z.record(z.unknown()).optional().describe("Request body as JSON object");
+	if (["GET", "DELETE"].includes(route.method)) inputShape["query"] = z.record(z.string()).optional().describe("Query parameters");
+	server.registerTool(toolName, {
+		description: `${route.description}\n\n${route.method} ${route.path}`,
+		inputSchema: Object.keys(inputShape).length > 0 ? inputShape : void 0
+	}, async (params) => {
+		let url = route.path;
+		for (const param of pathParams) {
+			const value = params[param];
+			if (value !== void 0) url = url.replace(`:${param}`, encodeURIComponent(String(value)));
+		}
+		const query = params["query"];
+		if (query && Object.keys(query).length > 0) url = `${url}?${new URLSearchParams(query).toString()}`;
+		const body = params["body"];
+		const init = {
+			method: route.method,
+			headers: {
+				"Content-Type": "application/json",
+				Accept: "application/json"
+			}
+		};
+		if (body && [
+			"POST",
+			"PUT",
+			"PATCH"
+		].includes(route.method)) init.body = JSON.stringify(body);
+		try {
+			const response = await app.fetch(new Request(`http://internal${url}`, init));
+			return {
+				content: [{
+					type: "text",
+					text: (response.headers.get("content-type") || "").includes("application/json") ? JSON.stringify(await response.json(), null, 2) : await response.text()
+				}],
+				isError: !response.ok
+			};
+		} catch (error) {
+			return {
+				content: [{
+					type: "text",
+					text: `Error: ${error instanceof Error ? error.message : String(error)}`
+				}],
+				isError: true
+			};
+		}
+	});
+}
+function routesToApiSchema(routes) {
+	return routes.map((route) => {
+		const endpoint = {
+			method: route.method,
+			path: route.path,
+			description: route.description
+		};
+		if ([
+			"POST",
+			"PUT",
+			"PATCH"
+		].includes(route.method)) endpoint.body = "JSON object";
+		return endpoint;
+	});
+}
+async function executeSearch(loader, code, apiSchema) {
+	const workerId = `search-${crypto.randomUUID()}`;
+	return await loader.get(workerId, () => ({
+		compatibilityDate: "2026-01-14",
+		compatibilityFlags: ["nodejs_compat"],
+		mainModule: "worker.js",
+		modules: { "worker.js": `
+        import { WorkerEntrypoint } from "cloudflare:workers";
+        const endpoints = ${JSON.stringify(apiSchema)};
+        export default class SearchExecutor extends WorkerEntrypoint {
+          async evaluate() {
+            try {
+              const result = await (${code})();
+              return { result };
+            } catch (err) {
+              return { error: err.message };
+            }
+          }
+        }
+      ` }
+	})).getEntrypoint().evaluate();
+}
+async function executeCode(loader, code, app) {
+	const workerId = `execute-${crypto.randomUUID()}`;
+	const worker = loader.get(workerId, () => ({
+		compatibilityDate: "2026-01-14",
+		compatibilityFlags: ["nodejs_compat"],
+		mainModule: "worker.js",
+		modules: { "worker.js": `
+        import { WorkerEntrypoint } from "cloudflare:workers";
+
+        export default class ExecuteWorker extends WorkerEntrypoint {
+          async evaluate(fetch) {
+            try {
+              const result = await (${code})();
+              return { result };
+            } catch (err) {
+              return { error: err.message };
+            }
+          }
+        }
+      ` }
+	}));
+	const fetch = async (path, options = {}) => {
+		const response = await app.fetch(new Request(`http://internal${path}`, options));
+		return (response.headers.get("content-type") || "").includes("application/json") ? response.json() : response.text();
+	};
+	return await worker.getEntrypoint().evaluate(fetch);
+}
+function registerCodemodeTools(server, routes, app, loader) {
+	const apiSchema = routesToApiSchema(routes);
+	server.registerTool("search", {
+		description: `Search available API endpoints.
+
+Available in your code:
+  const endpoints = [...] // Array of { method, path, description, body? }
+
+Example:
+  async () => endpoints.filter(e => e.path.includes('users'))`,
+		inputSchema: { code: z.string().describe("JavaScript async arrow function to search endpoints") }
+	}, async ({ code }) => {
+		const result = await executeSearch(loader, code, apiSchema);
+		if (result.error) return {
+			content: [{
+				type: "text",
+				text: `Error: ${result.error}`
+			}],
+			isError: true
+		};
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result.result, null, 2)
+		}] };
+	});
+	server.registerTool("execute", {
+		description: `Execute code against the API.
+
+Types:
+  interface RequestInit {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+  }
+  declare function fetch(path: string, options?: RequestInit): Promise<unknown>;
+
+Example:
+  async () => await fetch('/users')`,
+		inputSchema: { code: z.string().describe("JavaScript async arrow function to execute") }
+	}, async ({ code }) => {
+		const result = await executeCode(loader, code, app);
+		if (result.error) return {
+			content: [{
+				type: "text",
+				text: `Error: ${result.error}`
+			}],
+			isError: true
+		};
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result.result, null, 2)
+		}] };
+	});
+}
+
+//#endregion
+export { describe, mcp };
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/mcp.ts"],"sourcesContent":["import { Hono } from \"hono\";\nimport type { Env, Handler } from \"hono\";\nimport { z } from \"zod\";\nimport { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport { WebStandardStreamableHTTPServerTransport } from \"@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js\";\n\nconst MCP_DESCRIPTION = Symbol(\"mcp_description\");\n\n/**\n * Add a description to a route handler for MCP tool generation.\n *\n * @example\n * ```ts\n * app.get('/users', describe('List all users', (c) => c.json([])))\n * ```\n */\nexport function describe<H extends Handler>(description: string, handler: H): H {\n  (handler as any)[MCP_DESCRIPTION] = description;\n  return handler;\n}\n\nfunction getDescription(handler: unknown): string | undefined {\n  return (handler as any)?.[MCP_DESCRIPTION];\n}\n\n// WorkerLoader interface (matches @cloudflare/workers-types)\ninterface WorkerLoader {\n  get(\n    id: string,\n    factory: () => {\n      compatibilityDate: string;\n      compatibilityFlags?: string[];\n      mainModule: string;\n      modules: Record<string, string>;\n    },\n  ): { getEntrypoint(): { evaluate: (...args: unknown[]) => Promise<unknown> } };\n}\n\nexport interface McpOptions {\n  name: string;\n  version: string;\n  title?: string;\n  description?: string;\n  instructions?: string;\n  mcpPath?: string;\n  /** Enable codemode - exposes search/execute tools instead of per-route tools. Requires LOADER binding. */\n  codemode?: boolean;\n  /** Binding name for Worker Loader (default: \"LOADER\"). Only used when codemode is true. */\n  loaderBinding?: string;\n}\n\ntype HttpMethod = \"GET\" | \"POST\" | \"PUT\" | \"PATCH\" | \"DELETE\";\n\ninterface Route {\n  method: HttpMethod;\n  path: string;\n  description: string;\n}\n\nconst CORS_HEADERS = {\n  \"Access-Control-Allow-Origin\": \"*\",\n  \"Access-Control-Allow-Methods\": \"GET, POST, DELETE, OPTIONS\",\n  \"Access-Control-Allow-Headers\": \"Content-Type, Accept, mcp-session-id, mcp-protocol-version\",\n  \"Access-Control-Expose-Headers\": \"mcp-session-id\",\n  \"Access-Control-Max-Age\": \"86400\",\n};\n\nfunction withCors(response: Response): Response {\n  const newHeaders = new Headers(response.headers);\n  for (const [key, value] of Object.entries(CORS_HEADERS)) {\n    newHeaders.set(key, value);\n  }\n  return new Response(response.body, {\n    status: response.status,\n    statusText: response.statusText,\n    headers: newHeaders,\n  });\n}\n\n/**\n * Wraps a Hono app to add an MCP endpoint that exposes routes as tools.\n *\n * @example\n * ```ts\n * import { mcp, describe } from 'hono-mcp'\n *\n * const app = new Hono()\n *   .get('/users', describe('List all users', (c) => c.json([])))\n *   .get('/users/:id', describe('Get user by ID', (c) => c.json({ id: c.req.param('id') })));\n *\n * export default mcp(app, { name: 'Users API', version: '1.0.0' });\n * ```\n *\n * @example Codemode (requires Worker Loader binding)\n * ```ts\n * export default mcp(app, { name: 'API', version: '1.0.0', codemode: true });\n * ```\n *\n */\nexport function mcp<E extends Env>(app: Hono<E>, options: McpOptions): Hono<E> {\n  const { mcpPath = \"/mcp\", codemode = false, loaderBinding = \"LOADER\" } = options;\n  const routes = extractRoutes(app);\n  const serverInfo = {\n    name: options.name,\n    version: options.version,\n    ...(options.title && { title: options.title }),\n    ...(options.description && { description: options.description }),\n  };\n\n  const createServer = () =>\n    new McpServer(\n      serverInfo,\n      options.instructions\n        ? { instructions: options.instructions }\n        : codemode\n          ? {\n              instructions:\n                \"Use 'search' to find available endpoints, then 'execute' to run code against the API.\",\n            }\n          : undefined,\n    );\n\n  const handleMcp = codemode\n    ? async (c: any) => {\n        if (c.req.method === \"OPTIONS\") return new Response(null, { headers: CORS_HEADERS });\n\n        const loader = c.env?.[loaderBinding] as WorkerLoader | undefined;\n        if (!loader) {\n          return new Response(\n            `Codemode requires ${loaderBinding} binding. Add worker_loaders to wrangler.jsonc.`,\n            { status: 500 },\n          );\n        }\n\n        const server = createServer();\n        registerCodemodeTools(server, routes, app, loader);\n\n        const transport = new WebStandardStreamableHTTPServerTransport();\n        server.connect(transport);\n        return withCors(await transport.handleRequest(c.req.raw));\n      }\n    : async (c: any) => {\n        if (c.req.method === \"OPTIONS\") return new Response(null, { headers: CORS_HEADERS });\n\n        const server = createServer();\n        for (const route of routes) registerTool(server, route, app);\n\n        const transport = new WebStandardStreamableHTTPServerTransport();\n        server.connect(transport);\n        return withCors(await transport.handleRequest(c.req.raw));\n      };\n\n  app.all(`${mcpPath}/*`, handleMcp);\n  app.all(mcpPath, handleMcp);\n\n  return app;\n}\n\nfunction extractRoutes(app: Hono<any>): Route[] {\n  const routes: Route[] = [];\n  const seen = new Set<string>();\n\n  const honoRoutes = (app as any).routes as Array<{\n    path: string;\n    method: string;\n    handler: Function;\n  }>;\n\n  if (!honoRoutes) return routes;\n\n  for (const route of honoRoutes) {\n    const method = route.method.toUpperCase();\n    if (![\"GET\", \"POST\", \"PUT\", \"PATCH\", \"DELETE\"].includes(method)) continue;\n    if (route.path.startsWith(\"/mcp\")) continue;\n\n    const key = `${method} ${route.path}`;\n    if (seen.has(key)) continue;\n    seen.add(key);\n\n    const description = getDescription(route.handler) || generateDescription(method, route.path);\n    routes.push({ method: method as HttpMethod, path: route.path, description });\n  }\n\n  return routes;\n}\n\nfunction generateDescription(method: string, path: string): string {\n  const resource =\n    path\n      .split(\"/\")\n      .filter((p) => p && !p.startsWith(\":\"))\n      .pop() || \"resource\";\n  const action =\n    {\n      GET: path.includes(\":\") ? \"Get\" : \"List\",\n      POST: \"Create\",\n      PUT: \"Update\",\n      PATCH: \"Update\",\n      DELETE: \"Delete\",\n    }[method] || method;\n  return `${action} ${resource}`;\n}\n\nfunction generateToolName(method: string, path: string): string {\n  const cleanPath = path\n    .replace(/^\\//, \"\")\n    .replace(/\\/:([^/]+)/g, \"_by_$1\")\n    .replace(/\\//g, \"_\")\n    .replace(/[^a-zA-Z0-9_]/g, \"\");\n  return `${method.toLowerCase()}_${cleanPath || \"root\"}`;\n}\n\nfunction extractPathParams(path: string): string[] {\n  const matches = path.match(/:([^/]+)/g);\n  return matches ? matches.map((m) => m.slice(1)) : [];\n}\n\nfunction registerTool(server: McpServer, route: Route, app: Hono<any>): void {\n  const toolName = generateToolName(route.method, route.path);\n  const pathParams = extractPathParams(route.path);\n\n  const inputShape: Record<string, z.ZodType> = {};\n  for (const param of pathParams) {\n    inputShape[param] = z.string().describe(`Path parameter: ${param}`);\n  }\n  if ([\"POST\", \"PUT\", \"PATCH\"].includes(route.method)) {\n    inputShape[\"body\"] = z.record(z.unknown()).optional().describe(\"Request body as JSON object\");\n  }\n  if ([\"GET\", \"DELETE\"].includes(route.method)) {\n    inputShape[\"query\"] = z.record(z.string()).optional().describe(\"Query parameters\");\n  }\n\n  server.registerTool(\n    toolName,\n    {\n      description: `${route.description}\\n\\n${route.method} ${route.path}`,\n      inputSchema: Object.keys(inputShape).length > 0 ? inputShape : undefined,\n    },\n    async (params: Record<string, unknown>) => {\n      let url = route.path;\n      for (const param of pathParams) {\n        const value = params[param];\n        if (value !== undefined) {\n          url = url.replace(`:${param}`, encodeURIComponent(String(value)));\n        }\n      }\n\n      const query = params[\"query\"] as Record<string, string> | undefined;\n      if (query && Object.keys(query).length > 0) {\n        url = `${url}?${new URLSearchParams(query).toString()}`;\n      }\n\n      const body = params[\"body\"] as Record<string, unknown> | undefined;\n      const init: RequestInit = {\n        method: route.method,\n        headers: { \"Content-Type\": \"application/json\", Accept: \"application/json\" },\n      };\n      if (body && [\"POST\", \"PUT\", \"PATCH\"].includes(route.method)) {\n        init.body = JSON.stringify(body);\n      }\n\n      try {\n        const response = await app.fetch(new Request(`http://internal${url}`, init));\n        const contentType = response.headers.get(\"content-type\") || \"\";\n        const text = contentType.includes(\"application/json\")\n          ? JSON.stringify(await response.json(), null, 2)\n          : await response.text();\n        return { content: [{ type: \"text\" as const, text }], isError: !response.ok };\n      } catch (error) {\n        return {\n          content: [\n            {\n              type: \"text\" as const,\n              text: `Error: ${error instanceof Error ? error.message : String(error)}`,\n            },\n          ],\n          isError: true,\n        };\n      }\n    },\n  );\n}\n\n// Codemode: search and execute tools\ninterface ApiEndpoint {\n  method: string;\n  path: string;\n  description: string;\n  body?: string;\n}\n\nfunction routesToApiSchema(routes: Route[]): ApiEndpoint[] {\n  return routes.map((route) => {\n    const endpoint: ApiEndpoint = {\n      method: route.method,\n      path: route.path,\n      description: route.description,\n    };\n    if ([\"POST\", \"PUT\", \"PATCH\"].includes(route.method)) {\n      endpoint.body = \"JSON object\";\n    }\n    return endpoint;\n  });\n}\n\nasync function executeSearch(\n  loader: WorkerLoader,\n  code: string,\n  apiSchema: ApiEndpoint[],\n): Promise<{ result?: unknown; error?: string }> {\n  const workerId = `search-${crypto.randomUUID()}`;\n\n  const worker = loader.get(workerId, () => ({\n    compatibilityDate: \"2026-01-14\",\n    compatibilityFlags: [\"nodejs_compat\"],\n    mainModule: \"worker.js\",\n    modules: {\n      \"worker.js\": `\n        import { WorkerEntrypoint } from \"cloudflare:workers\";\n        const endpoints = ${JSON.stringify(apiSchema)};\n        export default class SearchExecutor extends WorkerEntrypoint {\n          async evaluate() {\n            try {\n              const result = await (${code})();\n              return { result };\n            } catch (err) {\n              return { error: err.message };\n            }\n          }\n        }\n      `,\n    },\n  }));\n\n  const entrypoint = worker.getEntrypoint();\n  return (await entrypoint.evaluate()) as { result?: unknown; error?: string };\n}\n\nasync function executeCode(\n  loader: WorkerLoader,\n  code: string,\n  app: Hono<any>,\n): Promise<{ result?: unknown; error?: string }> {\n  const workerId = `execute-${crypto.randomUUID()}`;\n\n  const worker = loader.get(workerId, () => ({\n    compatibilityDate: \"2026-01-14\",\n    compatibilityFlags: [\"nodejs_compat\"],\n    mainModule: \"worker.js\",\n    modules: {\n      \"worker.js\": `\n        import { WorkerEntrypoint } from \"cloudflare:workers\";\n\n        export default class ExecuteWorker extends WorkerEntrypoint {\n          async evaluate(fetch) {\n            try {\n              const result = await (${code})();\n              return { result };\n            } catch (err) {\n              return { error: err.message };\n            }\n          }\n        }\n      `,\n    },\n  }));\n\n  const fetch = async (path: string, options: RequestInit = {}) => {\n    const response = await app.fetch(new Request(`http://internal${path}`, options));\n    const contentType = response.headers.get(\"content-type\") || \"\";\n    return contentType.includes(\"application/json\") ? response.json() : response.text();\n  };\n\n  const entrypoint = worker.getEntrypoint();\n  return (await entrypoint.evaluate(fetch)) as { result?: unknown; error?: string };\n}\n\nfunction registerCodemodeTools(\n  server: McpServer,\n  routes: Route[],\n  app: Hono<any>,\n  loader: WorkerLoader,\n): void {\n  const apiSchema = routesToApiSchema(routes);\n\n  // Search tool - discover available endpoints\n  server.registerTool(\n    \"search\",\n    {\n      description: `Search available API endpoints.\n\nAvailable in your code:\n  const endpoints = [...] // Array of { method, path, description, body? }\n\nExample:\n  async () => endpoints.filter(e => e.path.includes('users'))`,\n      inputSchema: {\n        code: z.string().describe(\"JavaScript async arrow function to search endpoints\"),\n      },\n    },\n    async ({ code }) => {\n      const result = await executeSearch(loader, code as string, apiSchema);\n      if (result.error) {\n        return {\n          content: [{ type: \"text\" as const, text: `Error: ${result.error}` }],\n          isError: true,\n        };\n      }\n      return { content: [{ type: \"text\" as const, text: JSON.stringify(result.result, null, 2) }] };\n    },\n  );\n\n  // Execute tool - run code against the API\n  server.registerTool(\n    \"execute\",\n    {\n      description: `Execute code against the API.\n\nTypes:\n  interface RequestInit {\n    method?: string;\n    headers?: Record<string, string>;\n    body?: string;\n  }\n  declare function fetch(path: string, options?: RequestInit): Promise<unknown>;\n\nExample:\n  async () => await fetch('/users')`,\n      inputSchema: { code: z.string().describe(\"JavaScript async arrow function to execute\") },\n    },\n    async ({ code }) => {\n      const result = await executeCode(loader, code as string, app);\n      if (result.error) {\n        return {\n          content: [{ type: \"text\" as const, text: `Error: ${result.error}` }],\n          isError: true,\n        };\n      }\n      return { content: [{ type: \"text\" as const, text: JSON.stringify(result.result, null, 2) }] };\n    },\n  );\n}\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "hono-mcp-server",
+  "version": "0.0.1",
+  "description": "hono app as mcp server",
+  "keywords": [
+    "api",
+    "cloudflare-workers",
+    "hono",
+    "mcp",
+    "model-context-protocol",
+    "server"
+  ],
+  "license": "MIT",
+  "author": "Matt Carey <mcarey@cloudflare.com>",
+  "workspaces": [
+    "examples/*"
+  ],
+  "files": [
+    "dist",
+    "src"
+  ],
+  "type": "module",
+  "main": "dist/index.mjs",
+  "types": "dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "prepublishOnly": "npm run build",
+    "check": "npm run typecheck && npm run format:check && npm run lint",
+    "typecheck": "tsc --noEmit",
+    "format": "oxfmt --write .",
+    "format:check": "oxfmt .",
+    "lint": "oxlint --ignore-pattern node_modules --ignore-pattern .wrangler --ignore-pattern dist",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "examples:types": "npm run types --workspaces"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.2",
+    "hono": "^4.0.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "oxfmt": "^0.24.0",
+    "oxlint": "^1.39.0",
+    "tsdown": "^0.20.0-beta.3",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.0",
+    "wrangler": "^4.59.2"
+  },
+  "peerDependencies": {
+    "hono": "^4.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { mcp, describe } from "./mcp";
+export type { McpOptions } from "./mcp";