@revojs/ai 0.2.16 → 0.2.17

package/README.md

@@ -2,6 +2,153 @@
 
 ## Model Context Protocol
 
+### Use local tools
+
+`useTools(scope)` discovers the same `./tools` source used by the HTTP endpoint,
+without opening a Model Context Protocol connection or making a network request.
+Definitions and validators are loaded lazily and cached per returned collection.
+
+```ts
+import { useAi, useTools } from "@revojs/ai";
+
+const localTools = useTools(scope);
+const { openai } = useAi(scope);
+const result = await openai.textGenerate({
+    model,
+    prompt,
+    tools: await localTools.listTools(),
+});
+
+for (const call of result.content) {
+    if (call.type === "tool-call" && !call.providerExecuted) {
+        const output = await localTools.executeTool(call, { signal });
+    }
+}
+```
+
+`listTools()` returns AI function-tool definitions. `executeTool()` accepts a
+normalized model tool call and returns a `LanguageModelToolResultPart`, preserving
+the entire tool result as JSON, like the Model Context Protocol client. Use
+`callTool(name, input, { signal })` for the original SDK `CallToolResult` without
+a model call. Both execution methods validate arguments before running a handler.
+Unknown tools, invalid arguments and unexpected handler failures throw locally;
+HTTP error responses and thrown responses become error results. The HTTP endpoint
+uses the same collection and sanitizes unexpected execution errors at its boundary.
+
+Function tools work with ordinary scopes, including Cloudflare Workflow scopes
+without an HTTP request. They receive the caller's scope unchanged, so application
+contexts can supply organization identity, conversation state and authorization.
+Route tools require an HTTP request scope and retain the target route's normal
+session requirements; they are not a workaround for user authentication.
+
+Handlers and route resolvers receive `ToolExecutionOptions` as their third
+argument. Its optional `signal` supports cooperative cancellation; pass it to
+database/network/execution APIs that support cancellation. Route requests combine
+it with the incoming request's signal. Already-started side effects cannot be
+rolled back by aborting. Applications own deadlines, model rounds, approval checks,
+tool-name routing, execution records and limits on spawned conversations.
+
+### Build a server
+
+The landing app includes two runnable examples: `apps/landing/tools/list-items.ts`
+calls the existing `/api/items` route, while `apps/landing/tools/add.ts` directly
+implements a function that adds two numbers. Both are available through
+`/v1/model-context-protocol` when running the landing app.
+
+The AI module includes `@revojs/server`, discovers default-exported tools from
+`./tools/**/*.{js,ts}` as `#tools`, and exposes a stateless Streamable HTTP Model Context Protocol
+endpoint at `/v1/model-context-protocol`. Only explicitly registered tools are exposed, not every HTTP route.
+
+```ts
+import { defineTool } from "@revojs/ai";
+
+export default defineTool({
+    name: "list-items",
+    description: "List available items.",
+    inputSchema: {
+        type: "object",
+        properties: { limit: { type: "integer", minimum: 1 } },
+        additionalProperties: false,
+    },
+    route: { path: "/api/items", method: "GET" },
+});
+```
+
+Route paths execute internally through the normal Server router and middleware.
+String routes default to `POST`. Arguments become query parameters for `GET`/`HEAD`
+or a JSON body for other methods. Incoming authorization, cookie, origin and
+cross-site metadata headers are preserved unless explicitly overridden by the
+tool definition; other headers must be supplied explicitly. No external requests
+or redirects are followed, and tools cannot target `/v1/model-context-protocol` recursively.
+
+Use a route resolver for custom path, query, body or header mapping:
+
+```ts
+import { defineTool } from "@revojs/ai";
+
+export default defineTool<{ id: string; title: string }>({
+    name: "update-item",
+    inputSchema: {
+        type: "object",
+        properties: { id: { type: "string" }, title: { type: "string" } },
+        required: ["id", "title"],
+        additionalProperties: false,
+    },
+    route: (scope, input) => ({
+        path: `/api/items/${encodeURIComponent(input.id)}`,
+        method: "PATCH",
+        body: { title: input.title },
+    }),
+});
+```
+
+Alternatively, implement the tool directly with the current Model Context Protocol request scope:
+
+```ts
+import { defineTool } from "@revojs/ai";
+
+export default defineTool<{ message: string }>({
+    name: "echo",
+    inputSchema: {
+        type: "object",
+        properties: { message: { type: "string" } },
+        required: ["message"],
+        additionalProperties: false,
+    },
+    execute(scope, input) {
+        return { message: input.message };
+    },
+});
+```
+
+`route` also accepts an imported `defineRoute(...)` object. It receives a separate
+POST request containing the tool arguments as JSON, sharing variables and states
+with the Model Context Protocol request. This reuses the handler only: it does **not** execute the
+route's original middleware or infer its original path parameters. Prefer a path
+target when middleware or route parameters are required.
+
+Choose exactly one of `route` and `execute`. Input schemas must describe an object;
+plain JSON Schema and Standard JSON Schema providers are supported. Arguments are
+validated before execution, and tool names must be unique across sources.
+Handlers can return JSON, text, a `Response`, or an SDK `CallToolResult` for custom
+multimodal content. JSON objects from direct handlers also become structured
+content. HTTP error responses and thrown responses become tool errors; unexpected
+exceptions return a generic tool error without disclosing internal details.
+
+Configure server identity through `ai.modelContextProtocol.name`, `ai.modelContextProtocol.version`, and optional
+`ai.modelContextProtocol.instructions` in the Vite module configuration. The endpoint uses JSON
+responses without persistent sessions, server-initiated SSE, resources or prompts.
+GET and DELETE are registered and return `405` with `Allow: POST` because there
+are no persistent SSE streams or sessions to terminate.
+
+Protect `/v1/model-context-protocol` with application middleware and enforce permissions in each tool
+or its target route. Discovery exposes registered tool metadata to callers allowed
+through that middleware. The endpoint rejects cross-origin requests by default;
+this is not authentication or a complete DNS-rebinding defense. Validate allowed
+hosts in your deployment. Model Context Protocol clients without an Origin header remain supported.
+
+### Connect to a server
+
 Connect to a Model Context Protocol server using Streamable HTTP. Headers,
 an SDK OAuth provider, a custom fetch implementation,
 and custom SDK transports are supported. Keep credentials on the server and only
@@ -10,7 +157,9 @@ connect to trusted endpoints.
 ```ts
 import { useAi, useModelContextProtocol } from "@revojs/ai";
 
-const modelContextProtocol = await useModelContextProtocol({ endpoint: "https://example.com/mcp" });
+const modelContextProtocol = await useModelContextProtocol({
+    endpoint: "https://example.com/v1/model-context-protocol",
+});
 
 try {
     const { openai } = useAi(scope);

package/dist/index.d.ts

@@ -2,8 +2,15 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { type StreamableHTTPClientTransportOptions } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import type { RequestOptions } from "@modelcontextprotocol/sdk/shared/protocol.js";
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import { type CallToolResult, type ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+import { type HttpMethod, type Route } from "@revojs/server";
 import { type Scope, type Source, type SourceScope, type SourceValue } from "revojs";
-import type { JSONObject, JSONValue, JsonSchema } from "revojs/shared";
+import { type Awaitable, type JSONObject, type JsonSchema, type JSONValue } from "revojs/shared";
+export type ToolResult = JSONValue | CallToolResult | Response | void;
+export type Tool<T extends JSONObject = JSONObject> = FunctionTool<T> | RouteTool<T>;
+export type ToolHandler<T extends JSONObject = JSONObject> = (scope: Scope, input: T, options: ToolExecutionOptions) => Awaitable<ToolResult>;
+export type ToolRouteResolver<T extends JSONObject = JSONObject> = (scope: Scope, input: T, options: ToolExecutionOptions) => Awaitable<ToolRequest>;
+export type ToolRoute<T extends JSONObject = JSONObject> = string | ToolRequest | Route | ToolRouteResolver<T>;
 export type ModelContextProtocolConnectOptions = ModelContextProtocolHttpConnectOptions | ModelContextProtocolTransportConnectOptions;
 export type SharedWarning = {
     type: "unsupported" | "compatibility";
@@ -34,6 +41,34 @@ export type LanguageModelMessage = ({
     providerOptions?: Record<string, JSONObject>;
 };
 export type LanguageModelContent = LanguageModelText | LanguageModelReasoning | LanguageModelCustomContent | LanguageModelReasoningFile | LanguageModelFile | LanguageModelToolApprovalRequest | LanguageModelSource | LanguageModelToolCall | LanguageModelToolResult;
+export interface ToolDefinition {
+    name: string;
+    description?: string;
+    inputSchema: JsonSchema;
+    annotations?: ToolAnnotations;
+}
+export interface ToolExecutionOptions {
+    signal?: AbortSignal;
+}
+export interface ToolDescription extends LanguageModelFunctionTool {
+    inputSchema: JSONObject;
+    annotations?: ToolAnnotations;
+}
+export interface FunctionTool<T extends JSONObject = JSONObject> extends ToolDefinition {
+    execute: ToolHandler<T>;
+    route?: never;
+}
+export interface RouteTool<T extends JSONObject = JSONObject> extends ToolDefinition {
+    route: ToolRoute<T>;
+    execute?: never;
+}
+export interface ToolRequest {
+    path: string;
+    method?: HttpMethod;
+    query?: Record<string, string> | URLSearchParams;
+    body?: JSONValue;
+    headers?: HeadersInit;
+}
 export interface ModelContextProtocolClientInfo {
     name: string;
     version: string;
@@ -642,6 +677,13 @@ export declare class ModelContextProtocolConnection {
     executeTool(call: LanguageModelToolCall, options?: RequestOptions): Promise<LanguageModelToolResultPart>;
     close(): Promise<void>;
 }
+export declare function defineTool<T extends JSONObject = JSONObject>(tool: Tool<T>): Tool<T>;
+export declare function useTools(scope: Scope): {
+    listTools(): Promise<Array<ToolDescription>>;
+    callTool: (name: string, input?: JSONObject, options?: ToolExecutionOptions) => Promise<CallToolResult>;
+    executeTool(call: LanguageModelToolCall, options?: ToolExecutionOptions): Promise<LanguageModelToolResultPart>;
+};
+export declare function handleModelContextProtocol(scope: Scope): Promise<Response>;
 export declare function useModelContextProtocol(options: ModelContextProtocolConnectOptions): Promise<ModelContextProtocolConnection>;
 export declare function defineProvider<TProvider extends Provider>(provider: TProvider): TProvider;
 export declare function useAi<TSource extends Source<Provider> = typeof import("#providers").default>(scope: Scope): AiConnections<TSource>;

package/dist/index.js

@@ -1,7 +1,15 @@
+import config from "#config/ai";
 import providers from "#providers";
+import tools from "#tools";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import "revojs";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError } from "@modelcontextprotocol/sdk/types.js";
+import { CfWorkerJsonSchemaValidator } from "@modelcontextprotocol/sdk/validation/cfworker-provider.js";
+import { SERVER_CONTEXT, createServerScope, isResponse, requireSameOrigin, useServer } from "@revojs/server";
+import { useVariables } from "revojs";
+import { toJsonSchema } from "revojs/shared";
 //#region src/index.ts
 var ModelContextProtocolConnection = class {
 	client;
@@ -53,6 +61,195 @@ var ModelContextProtocolConnection = class {
 		}
 	}
 };
+function defineTool(tool) {
+	return tool;
+}
+async function toToolResult(output) {
+	if (output instanceof Response) return {
+		content: [{
+			type: "text",
+			text: await output.text()
+		}],
+		isError: !output.ok
+	};
+	if (output !== null && typeof output === "object" && "content" in output && Array.isArray(output.content)) return output;
+	return {
+		content: [{
+			type: "text",
+			text: typeof output === "string" ? output : JSON.stringify(output ?? null)
+		}],
+		...output !== null && typeof output === "object" && !Array.isArray(output) ? { structuredContent: output } : {}
+	};
+}
+function useTools(scope) {
+	let loading;
+	let registered;
+	const resolveTools = async () => {
+		if (!loading) {
+			const pending = new Array();
+			for (const source of Object.values(tools)) for (const resolve of Object.values(source)) pending.push(resolve());
+			loading = Promise.all(pending);
+		}
+		const definitions = await loading;
+		if (registered) return registered;
+		const validator = new CfWorkerJsonSchemaValidator();
+		const entries = /* @__PURE__ */ new Map();
+		for (const tool of definitions) {
+			if (!/^[A-Za-z0-9_.-]{1,128}$/.test(tool.name)) throw new Error(`Invalid Model Context Protocol tool name "${tool.name}".`);
+			if (entries.has(tool.name)) throw new Error("Model Context Protocol tool names must be unique across all tool sources.");
+			const schema = toJsonSchema(tool.inputSchema);
+			if (schema.type !== "object") throw new Error(`Model Context Protocol tool "${tool.name}" must have an object input schema.`);
+			entries.set(tool.name, {
+				tool,
+				schema,
+				validate: validator.getValidator(schema)
+			});
+		}
+		registered = entries;
+		return registered;
+	};
+	const callTool = async (name, input = {}, options = {}) => {
+		options.signal?.throwIfAborted();
+		const entry = (await resolveTools()).get(name);
+		if (!entry) throw new McpError(ErrorCode.InvalidParams, `Unknown tool "${name}".`);
+		const result = entry.validate(input);
+		if (!result.valid) throw new McpError(ErrorCode.InvalidParams, result.errorMessage ?? "Invalid tool arguments.");
+		options.signal?.throwIfAborted();
+		try {
+			const { tool } = entry;
+			if (tool.execute) {
+				const output = await tool.execute(scope, result.data, options);
+				options.signal?.throwIfAborted();
+				return await toToolResult(output);
+			}
+			if (!scope.context[SERVER_CONTEXT]) throw new Error("Route tools require an HTTP request scope. Use function tools in workflows.");
+			const { request, states } = useServer(scope);
+			const signal = options.signal ? AbortSignal.any([request.signal, options.signal]) : request.signal;
+			signal.throwIfAborted();
+			let target = tool.route;
+			if (typeof target === "function") target = await target(scope, result.data, { signal });
+			let direct;
+			let targetOptions;
+			if (typeof target === "string") targetOptions = { path: target };
+			else if ("fetch" in target) {
+				direct = target;
+				targetOptions = { path: request.url };
+			} else targetOptions = target;
+			const url = new URL(targetOptions.path, request.url);
+			if (url.origin !== new URL(request.url).origin || url.username || url.password) throw new Error("Tool routes must target the application's own origin.");
+			if (!direct && (url.pathname === "/v1/model-context-protocol" || url.pathname === "/v1/model-context-protocol/")) throw new Error("A tool cannot call the Model Context Protocol endpoint.");
+			const method = targetOptions.method ?? "POST";
+			const readOnly = method === "GET" || method === "HEAD";
+			const query = targetOptions.query ?? (readOnly ? result.data : {});
+			for (const [name, value] of query instanceof URLSearchParams ? query : Object.entries(query)) if (value !== void 0) url.searchParams.append(name, typeof value === "string" ? value : JSON.stringify(value));
+			const headers = new Headers(targetOptions.headers);
+			for (const name of [
+				"authorization",
+				"cookie",
+				"origin",
+				"sec-fetch-site"
+			]) {
+				const value = request.headers.get(name);
+				if (value !== null && !headers.has(name)) headers.set(name, value);
+			}
+			let body;
+			if (!readOnly) {
+				headers.set("content-type", "application/json");
+				body = JSON.stringify("body" in targetOptions ? targetOptions.body : result.data);
+			}
+			const nextRequest = new Request(url, {
+				method,
+				headers,
+				body,
+				signal
+			});
+			const next = await createServerScope(nextRequest, useVariables(scope), states);
+			let response;
+			if (direct) response = await direct.fetch(next);
+			else response = await (await import("#server")).default.fetch(next);
+			signal.throwIfAborted();
+			if (!isResponse(response)) throw new Error("Tool routes must return an HTTP response.");
+			return await toToolResult(response);
+		} catch (error) {
+			options.signal?.throwIfAborted();
+			if (error instanceof Response) return toToolResult(error);
+			throw error;
+		}
+	};
+	return {
+		async listTools() {
+			const entries = await resolveTools();
+			const descriptions = new Array();
+			for (const { tool, schema } of entries.values()) descriptions.push({
+				type: "function",
+				name: tool.name,
+				description: tool.description,
+				inputSchema: schema,
+				annotations: tool.annotations
+			});
+			return descriptions;
+		},
+		callTool,
+		async executeTool(call, options) {
+			const input = JSON.parse(call.input);
+			if (input === null || typeof input !== "object" || Array.isArray(input)) throw new McpError(ErrorCode.InvalidParams, `Tool "${call.toolName}" requires a JSON object as input.`);
+			const result = await callTool(call.toolName, input, options);
+			return {
+				type: "tool-result",
+				toolCallId: call.toolCallId,
+				toolName: call.toolName,
+				output: {
+					type: result.isError ? "error-json" : "json",
+					value: result
+				}
+			};
+		}
+	};
+}
+async function handleModelContextProtocol(scope) {
+	requireSameOrigin(scope);
+	const { request } = useServer(scope);
+	if (request.method !== "POST") return new Response(null, {
+		status: 405,
+		headers: { Allow: "POST" }
+	});
+	const collection = useTools(scope);
+	const server = new McpServer({
+		name: config.modelContextProtocol.name,
+		version: config.modelContextProtocol.version
+	}, {
+		capabilities: { tools: {} },
+		instructions: config.modelContextProtocol.instructions,
+		jsonSchemaValidator: new CfWorkerJsonSchemaValidator()
+	});
+	const transport = new WebStandardStreamableHTTPServerTransport({ enableJsonResponse: true });
+	server.server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: (await collection.listTools()).map((tool) => ({
+		name: tool.name,
+		description: tool.description,
+		inputSchema: tool.inputSchema,
+		annotations: tool.annotations
+	})) }));
+	server.server.setRequestHandler(CallToolRequestSchema, async ({ params }, extra) => {
+		try {
+			return await collection.callTool(params.name, params.arguments ?? {}, { signal: AbortSignal.any([request.signal, extra.signal]) });
+		} catch (error) {
+			if (error instanceof McpError) throw error;
+			return {
+				content: [{
+					type: "text",
+					text: "Tool execution failed."
+				}],
+				isError: true
+			};
+		}
+	});
+	try {
+		await server.connect(transport);
+		return await transport.handleRequest(request);
+	} finally {
+		await server.close();
+	}
+}
 async function useModelContextProtocol(options) {
 	const client = new Client(options.clientInfo ?? {
 		name: "revojs",
@@ -157,4 +354,4 @@ function toStream(read) {
 	});
 }
 //#endregion
-export { ModelContextProtocolConnection, defineProvider, mergeHeaders, postJson, readDataFrames, toStream, useAi, useModelContextProtocol };
+export { ModelContextProtocolConnection, defineProvider, defineTool, handleModelContextProtocol, mergeHeaders, postJson, readDataFrames, toStream, useAi, useModelContextProtocol, useTools };

package/dist/module/index.d.ts

@@ -1,3 +1,9 @@
-export type AiConfig = Record<string, never>;
-declare const _default: import("revojs/module").Module<"ai", AiConfig, []>;
+export interface AiConfig {
+    modelContextProtocol: {
+        name: string;
+        version: string;
+        instructions?: string;
+    };
+}
+declare const _default: import("revojs/module").Module<"ai", AiConfig, readonly [import("revojs/module").Module<"server", Record<string, never>, []>]>;
 export default _default;

package/dist/module/index.js

@@ -1,10 +1,16 @@
+import server, { addRoutes } from "@revojs/server/module";
 import { defineModule, useModule } from "revojs/module";
 //#region src/module/index.ts
 var module_default = defineModule({
 	name: "ai",
-	config: () => ({}),
-	setup() {
+	config: () => ({ modelContextProtocol: {
+		name: "revojs",
+		version: "1.0.0"
+	} }),
+	modules: [server],
+	setup(config) {
 		const { fromModule } = useModule(import.meta.url);
+		addRoutes(config, fromModule("../routes"));
 		return {
 			variables: { server: {
 				anthropicApiKey: {
@@ -36,11 +42,18 @@ var module_default = defineModule({
 					optional: true
 				}
 			} },
-			sources: { providers: {
-				match: ["**/*.{js,ts}", "!**/*.d.ts"],
-				from: ["./providers", fromModule("../providers")],
-				format: "object"
-			} }
+			sources: {
+				tools: {
+					match: ["**/*.{js,ts}", "!**/*.d.ts"],
+					from: ["./tools"],
+					format: "object"
+				},
+				providers: {
+					match: ["**/*.{js,ts}", "!**/*.d.ts"],
+					from: ["./providers", fromModule("../providers")],
+					format: "object"
+				}
+			}
 		};
 	}
 });

package/dist/routes/v1/model-context-protocol/delete.d.ts

@@ -0,0 +1,5 @@
+import { handleModelContextProtocol } from "../../..";
+declare const _default: {
+    fetch: typeof handleModelContextProtocol;
+};
+export default _default;

package/dist/routes/v1/model-context-protocol/delete.js

@@ -0,0 +1,6 @@
+import { handleModelContextProtocol } from "../../../index.js";
+import { defineRoute } from "@revojs/server";
+//#region src/routes/v1/model-context-protocol/delete.ts
+var delete_default = defineRoute({ fetch: handleModelContextProtocol });
+//#endregion
+export { delete_default as default };

package/dist/routes/v1/model-context-protocol/get.d.ts

@@ -0,0 +1,5 @@
+import { handleModelContextProtocol } from "../../..";
+declare const _default: {
+    fetch: typeof handleModelContextProtocol;
+};
+export default _default;

package/dist/routes/v1/model-context-protocol/get.js

@@ -0,0 +1,6 @@
+import { handleModelContextProtocol } from "../../../index.js";
+import { defineRoute } from "@revojs/server";
+//#region src/routes/v1/model-context-protocol/get.ts
+var get_default = defineRoute({ fetch: handleModelContextProtocol });
+//#endregion
+export { get_default as default };

package/dist/routes/v1/model-context-protocol/post.d.ts

@@ -0,0 +1,5 @@
+import { handleModelContextProtocol } from "../../..";
+declare const _default: {
+    fetch: typeof handleModelContextProtocol;
+};
+export default _default;

package/dist/routes/v1/model-context-protocol/post.js

@@ -0,0 +1,6 @@
+import { handleModelContextProtocol } from "../../../index.js";
+import { defineRoute } from "@revojs/server";
+//#region src/routes/v1/model-context-protocol/post.ts
+var post_default = defineRoute({ fetch: handleModelContextProtocol });
+//#endregion
+export { post_default as default };

package/dist/types/index.d.ts

@@ -7,8 +7,16 @@
 
 declare module "#providers" {
     import type { Source } from "revojs";
-    import type { Provider } from "../draft";
+    import type { Provider } from "@revojs/ai";
 
     const entries: Source<Provider>;
     export default entries;
 }
+
+declare module "#tools" {
+    import type { Source } from "revojs";
+    import type { Tool } from "@revojs/ai";
+
+    const entries: Source<Tool>;
+    export default entries;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@revojs/ai",
-    "version": "0.2.16",
+    "version": "0.2.17",
     "license": "MIT",
     "repository": {
         "type": "git",
@@ -29,7 +29,9 @@
         "watch": "vite build --watch"
     },
     "dependencies": {
+        "@cfworker/json-schema": "^4.1.1",
         "@modelcontextprotocol/sdk": "^1.32.1",
+        "@revojs/server": "*",
         "revojs": "*"
     },
     "devDependencies": {