@farm.js/mcp 0.0.0-stage → 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Farm.js Team
+
+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,3 +1,97 @@
-# Temporary Holding Version
+# @farm.js/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Experimental Streamable HTTP MCP servers with typed Farm API routes and standalone tools.
+
+```ts
+import { defineConfig } from "@farm.js/core/config";
+
+export default defineConfig({
+  mcp: {
+    authorize: async ({ request }) =>
+      request.headers.get("authorization") ? { subject: "api-user" } : false,
+  },
+});
+```
+
+Opt an endpoint in where it is defined:
+
+```ts
+import { createEndpoint } from "@farm.js/core/api";
+
+export const GET = createEndpoint(
+  {
+    method: "GET",
+    mcp: { name: "list_projects", description: "List visible projects." },
+  },
+  listProjects,
+);
+```
+
+`mcp: true` derives a name from the route method and path. The endpoint defaults to `/api/mcp`.
+Selected routes keep their normal Farm validation,
+endpoint middleware, request context, error responses, and cancellation behavior.
+
+Alternatively, compose server-only endpoint references and standalone tools in config:
+
+```ts
+import { defineTool } from "@farm.js/mcp";
+import { z } from "zod";
+import { GET as listProjects } from "./src/app/api/projects/route";
+import { getSession } from "./src/lib/session";
+import { searchProjects } from "./src/lib/projects";
+
+export default defineConfig({
+  mcp: {
+    tools: [
+      { endpoint: listProjects, name: "list_projects" },
+      defineTool({
+        name: "search_projects",
+        description: "Search projects visible to the current user.",
+        inputSchema: z.object({ query: z.string().trim().min(1) }),
+        readOnlyHint: true,
+        destructiveHint: false,
+        execute: ({ query }, { authorization, signal }) =>
+          searchProjects({ query, userId: authorization.subject, signal }),
+      }),
+    ],
+    authorize: async ({ request, tools, server }) => {
+      const session = await getSession(request);
+      if (!session) return false;
+      return {
+        subject: session.user.id,
+        tools: tools
+          .filter((tool) => session.scopes.includes(`${server.name}:${tool.name}`))
+          .map((tool) => tool.name),
+      };
+    },
+  },
+});
+```
+
+Config references need an explicit path, for example
+`createEndpoint("/api/projects", { method: "GET" }, handler)`, matching a mounted app route.
+`mcp.tools` replaces automatic discovery; omit it to keep route-owned opt-ins. Bare references
+such as `tools: [listProjects]` preserve route metadata. `authorize` receives a frozen catalog
+with each tool's name and kind (`endpoint` or `standalone`), plus method/path for endpoints and
+the resolved server identity. Its optional returned
+`tools` list controls both discovery and invocation: omitted means all configured tools; `[]`
+means none. Scopes and annotations alone never grant or restrict access. Keep endpoint middleware
+for direct HTTP and argument-level permissions; standalone tools use `authorization` in `execute`
+for argument-level checks.
+
+Standalone tools need no separate HTTP route and can be the only tools in a server. Their
+arguments match `inputSchema` directly (for example `{ query: "farm" }`, without a `query` or
+`body` wrapper). The schema must describe an object and support input JSON Schema conversion:
+Zod 4 works directly, as does Standard Schema with `~standard.jsonSchema.input()`. Farm runs
+the original validator before execution, including async refinements and transforms; `execute`
+receives the inferred, validated output and `{ authorization, request, signal }`.
+
+Return JSON-serializable data, not a Web `Response`, stream, or MCP protocol envelope. Farm wraps
+the result as text content and `structuredContent: { result: data }`. Pass `signal` to cancellable
+work; cancellation cannot undo completed side effects. Denied tools never reach execution.
+
+`apiMcp()` remains exported for advanced manual plugin composition with the same options.
+Normal applications should use the top-level `mcp` config.
+
+See the [API MCP guide](https://farmjs.dev/docs/plugins/mcp) and the runnable
+[`examples/api-mcp`](https://github.com/farming-labs/farm.js/tree/main/examples/api-mcp).

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+import { type FarmPlugin, type EndpointMCPMetadata, type RouteSchema } from "@farm.js/core/plugin";
+import type { FarmMCPAuthorization, FarmMCPAuthorizeContext, FarmMCPConfig, FarmMCPStandaloneTool } from "@farm.js/core";
+export interface APIMCPAuthorization extends FarmMCPAuthorization {
+}
+export interface APIMCPAuthorizeContext extends FarmMCPAuthorizeContext {
+}
+/** @deprecated Put `EndpointMCPMetadata` on a route's `mcp` option instead. */
+export interface APIMCPToolOptions extends EndpointMCPMetadata {
+    name: string;
+}
+export interface APIMCPOptions extends Omit<FarmMCPConfig, "enabled"> {
+}
+export type { FarmMCPStandaloneTool, FarmMCPExecuteContext } from "@farm.js/core";
+/** Define a server-only MCP tool with schema-inferred execute arguments. */
+export declare function defineTool<Schema extends RouteSchema, Result, OutputSchema extends RouteSchema | undefined = undefined>(definition: FarmMCPStandaloneTool<Schema, Result, OutputSchema>): FarmMCPStandaloneTool<Schema, Result, OutputSchema>;
+/**
+ * Mount an experimental Streamable HTTP MCP server with API routes and standalone tools.
+ * API endpoints retain their validation and middleware; standalone tools own their schema and execute.
+ */
+export declare function apiMcp(options: APIMCPOptions): FarmPlugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAQA,OAAO,EACL,KAAK,UAAU,EACf,KAAK,mBAAmB,EAIxB,KAAK,WAAW,EACjB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EACV,oBAAoB,EACpB,uBAAuB,EACvB,aAAa,EAEb,qBAAqB,EAEtB,MAAM,eAAe,CAAC;AAYvB,MAAM,WAAW,mBAAoB,SAAQ,oBAAoB;CAAG;AAEpE,MAAM,WAAW,sBAAuB,SAAQ,uBAAuB;CAAG;AAE1E,+EAA+E;AAC/E,MAAM,WAAW,iBAAkB,SAAQ,mBAAmB;IAC5D,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAc,SAAQ,IAAI,CAAC,aAAa,EAAE,SAAS,CAAC;CAAG;AAqBxE,YAAY,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAElF,4EAA4E;AAC5E,wBAAgB,UAAU,CACxB,MAAM,SAAS,WAAW,EAC1B,MAAM,EACN,YAAY,SAAS,WAAW,GAAG,SAAS,GAAG,SAAS,EAExD,UAAU,EAAE,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,CAAC,GAC9D,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,CAAC,CAErD;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,UAAU,CAuBzD"}

package/dist/index.js

@@ -0,0 +1,630 @@
+import { createMcpHandler, fromJsonSchema, McpServer, } from "@modelcontextprotocol/server";
+import { CfWorkerJsonSchemaValidator } from "@modelcontextprotocol/server/validators/cf-worker";
+import { parseRouteSchema } from "@farm.js/core/api/runtime";
+import { toJSONSchema } from "zod";
+const TOOL_NAME = /^[A-Za-z0-9_.-]{1,128}$/;
+const PROTECTED_HEADER = /^(authorization|cookie|set-cookie|proxy-authorization|x-api-key|x-auth-token|x-.*(?:token|secret|key)|connection|keep-alive|te|trailer|transfer-encoding|upgrade|host|origin|referer|forwarded|via|x-forwarded-.+|x-real-ip|x-client-ip|x-cluster-client-ip|x-original-.+|x-rewrite-url|cf-.+|true-client-ip|fastly-.+|x-vercel-.+|sec-fetch-.+|access-control-request-.+)$/i;
+const schemaValidator = new CfWorkerJsonSchemaValidator();
+/** Define a server-only MCP tool with schema-inferred execute arguments. */
+export function defineTool(definition) {
+    return definition;
+}
+/**
+ * Mount an experimental Streamable HTTP MCP server with API routes and standalone tools.
+ * API endpoints retain their validation and middleware; standalone tools own their schema and execute.
+ */
+export function apiMcp(options) {
+    const normalized = validateOptions(options);
+    return {
+        name: "farm:api-mcp",
+        routes: ({ route, api }) => {
+            const tools = api.available ? bindTools(api, normalized) : [];
+            const handler = createHandler(normalized, tools);
+            const serve = (request, body) => handler(request, body);
+            return [
+                route.get(normalized.path, {
+                    handler: (request) => serve(request, undefined),
+                }),
+                route.post(normalized.path, {
+                    handler: (request, { input }) => serve(request, input.body),
+                }),
+                route.delete(normalized.path, {
+                    handler: (request, { input }) => serve(request, input.body),
+                }),
+            ];
+        },
+    };
+}
+function createHandler(options, tools) {
+    const catalog = Object.freeze(tools.map((tool) => Object.freeze({
+        name: tool.config.name,
+        title: tool.config.title,
+        description: tool.config.description,
+        ...tool.annotations,
+        ...(tool.kind === "endpoint"
+            ? { kind: "endpoint", method: tool.route.method, path: tool.route.path }
+            : { kind: "standalone" }),
+    })));
+    const serverIdentity = Object.freeze({
+        name: options.name,
+        version: options.version,
+        path: options.path,
+    });
+    const toolNames = new Set(catalog.map(({ name }) => name));
+    const mcp = createMcpHandler(({ requestInfo, authInfo }) => {
+        const server = new McpServer({ name: options.name, version: options.version }, { capabilities: { tools: {} } });
+        const allowed = authInfo?.extra?.farmAllowedTools;
+        const allowedNames = allowed === undefined ? undefined : new Set(allowed);
+        // A fresh server is created per HTTP request. Unregistered tools are neither
+        // discoverable nor callable, regardless of the incoming protocol method.
+        for (const tool of tools) {
+            if (allowedNames && !allowedNames.has(tool.config.name))
+                continue;
+            server.registerTool(tool.config.name, {
+                title: tool.config.title,
+                description: tool.config.description,
+                inputSchema: fromJsonSchema(tool.inputSchema, schemaValidator),
+                ...(tool.outputSchema === undefined
+                    ? {}
+                    : {
+                        outputSchema: fromJsonSchema(tool.outputSchema, schemaValidator),
+                    }),
+                annotations: tool.annotations,
+            }, async (input, context) => {
+                const request = context.http?.req ?? requestInfo;
+                if (tool.kind === "endpoint") {
+                    return invokeTool(tool, input, request, context.mcpReq.signal);
+                }
+                const authorization = authInfo?.extra?.farmAuthorization;
+                if (!request || !authorization)
+                    return toolError("Missing MCP authorization context.");
+                return invokeStandaloneTool(tool, input, {
+                    request,
+                    authorization,
+                    signal: AbortSignal.any([request.signal, context.mcpReq.signal]),
+                });
+            });
+        }
+        return server;
+    });
+    return async (request, parsedBody) => {
+        let authorization;
+        if (options.authorize) {
+            const messages = Array.isArray(parsedBody) && parsedBody.length > 0 ? parsedBody : [parsedBody];
+            let first;
+            let denied = false;
+            let inconsistent = false;
+            for (const message of messages) {
+                const result = await options.authorize({
+                    request,
+                    tool: getCalledTool(message),
+                    tools: catalog,
+                    server: serverIdentity,
+                });
+                if (result === false) {
+                    denied = true;
+                    continue;
+                }
+                if (!result || typeof result.subject !== "string" || result.subject.length === 0) {
+                    throw new TypeError("apiMcp authorize must return false or an object with a subject string.");
+                }
+                if (first && !sameAuthorizationIdentity(first, result)) {
+                    inconsistent = true;
+                }
+                first ??= result;
+            }
+            if (denied || inconsistent)
+                return unauthorized();
+            authorization = first;
+        }
+        else {
+            authorization = { subject: "anonymous" };
+        }
+        return mcp.fetch(request, {
+            parsedBody,
+            authInfo: toMCPAuthInfo(authorization, resolveAllowedTools(authorization, toolNames)),
+        });
+    };
+}
+async function invokeTool(tool, input, sourceRequest, signal) {
+    try {
+        const params = asRecord(input.params, "params");
+        const pathname = interpolatePath(tool.route.path, params);
+        const origin = sourceRequest ? new URL(sourceRequest.url).origin : "http://farm.local";
+        const url = new URL(pathname, origin);
+        appendQuery(url, asRecord(input.query, "query"));
+        const headers = createForwardedHeaders(sourceRequest?.headers, asRecord(input.headers, "headers"));
+        const body = input.body === undefined ? undefined : JSON.stringify(input.body);
+        if (body !== undefined)
+            headers.set("content-type", "application/json");
+        const request = new Request(url, {
+            method: tool.route.method,
+            headers,
+            body: tool.route.method === "GET" || tool.route.method === "HEAD" ? undefined : body,
+            signal,
+        });
+        const routeParams = Object.fromEntries(Object.entries(params).map(([key, value]) => [
+            key,
+            Array.isArray(value) ? value.map(String) : String(value),
+        ]));
+        const response = await tool.route.invoke(request, routeParams);
+        const mediaType = response.headers.get("content-type")?.split(";", 1)[0].trim() ?? "";
+        if (response.status !== 204 &&
+            mediaType !== "application/json" &&
+            !mediaType.endsWith("+json")) {
+            return toolError(`${tool.key} returned ${mediaType || "a response without a Content-Type"}; MCP API tools must return JSON.`);
+        }
+        const result = response.status === 204 ? null : await response.json();
+        if (!response.ok) {
+            return toolError(JSON.stringify({ status: response.status, error: result }));
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(result) }],
+            structuredContent: { result },
+        };
+    }
+    catch (error) {
+        return toolError(error instanceof Error ? error.message : "Farm API tool invocation failed.");
+    }
+}
+async function invokeStandaloneTool(tool, input, context) {
+    try {
+        context.signal.throwIfAborted();
+        // JSON Schema advertises the wire shape; the original validator owns async
+        // refinements, defaults, and transforms, just as it does for API endpoints.
+        const parsed = await parseRouteSchema(tool.definition.inputSchema, input);
+        context.signal.throwIfAborted();
+        let result = await tool.definition.execute(parsed, context);
+        context.signal.throwIfAborted();
+        if (tool.definition.outputSchema !== undefined) {
+            try {
+                result = await parseRouteSchema(tool.definition.outputSchema, result);
+            }
+            catch {
+                // Output can contain private application data. Do not return validator
+                // issues or custom refinement messages to the caller.
+                return toolError(`MCP tool "${tool.config.name}" returned a value that does not match its output schema.`);
+            }
+            context.signal.throwIfAborted();
+        }
+        const text = JSON.stringify(result, (_key, value) => {
+            if (typeof value === "bigint" ||
+                typeof value === "function" ||
+                typeof value === "symbol" ||
+                (typeof value === "number" && !Number.isFinite(value)) ||
+                (value !== null &&
+                    typeof value === "object" &&
+                    !Array.isArray(value) &&
+                    Object.getPrototypeOf(value) !== Object.prototype &&
+                    Object.getPrototypeOf(value) !== null))
+                throw new TypeError("Standalone MCP tools must return JSON-serializable data, not a Response or stream.");
+            return value;
+        });
+        if (text === undefined)
+            throw new TypeError("Standalone MCP tools must return JSON-serializable data.");
+        return {
+            content: [{ type: "text", text }],
+            structuredContent: { result: JSON.parse(text) },
+        };
+    }
+    catch (error) {
+        return toolError(error instanceof Error ? error.message : "Farm MCP tool execution failed.");
+    }
+}
+function bindTools(api, options) {
+    const selected = [];
+    const endpoints = new Set();
+    const select = (endpoint, metadata) => {
+        if (endpoint.path === options.path) {
+            throw new TypeError(`apiMcp cannot expose its own route (${endpoint.method} ${endpoint.path}).`);
+        }
+        if (endpoint.method === "OPTIONS") {
+            throw new TypeError(`apiMcp cannot expose OPTIONS route ${endpoint.path}; use an application operation instead.`);
+        }
+        const key = `${endpoint.method} ${endpoint.path}`;
+        if (endpoints.has(key))
+            throw new TypeError(`apiMcp endpoint ${key} is selected more than once.`);
+        endpoints.add(key);
+        const config = { ...(endpoint.mcp === true ? {} : endpoint.mcp), ...metadata };
+        const resolved = {
+            ...config,
+            name: config.name ?? deriveToolName(endpoint.method, endpoint.path),
+        };
+        selected.push({
+            kind: "endpoint",
+            key,
+            route: endpoint,
+            config: resolved,
+            inputSchema: createToolInputSchema(endpoint),
+            outputSchema: createToolOutputSchema(endpoint.output),
+            annotations: createAnnotations(endpoint.method, resolved),
+        });
+    };
+    if (options.tools === undefined) {
+        for (const endpoint of api.list()) {
+            if (endpoint.mcp)
+                select(endpoint);
+        }
+    }
+    else {
+        for (const definition of options.tools) {
+            if (definition && typeof definition === "object" && "execute" in definition) {
+                if ("endpoint" in definition ||
+                    typeof definition.execute !== "function" ||
+                    !definition.inputSchema) {
+                    throw new TypeError("Standalone MCP tools need inputSchema and execute, without an endpoint reference.");
+                }
+                const config = { ...definition, name: definition.name };
+                selected.push({
+                    kind: "standalone",
+                    key: `tool ${definition.name}`,
+                    definition,
+                    config,
+                    inputSchema: requireObjectSchema(toToolJSONSchema(definition.inputSchema, "inputSchema"), "inputSchema"),
+                    outputSchema: createToolOutputSchema(definition.outputSchema),
+                    annotations: createAnnotations(undefined, config),
+                });
+                continue;
+            }
+            const { endpoint, ...metadata } = typeof definition === "function" ? { endpoint: definition } : (definition ?? {});
+            if (typeof endpoint !== "function" ||
+                !endpoint.__types ||
+                typeof endpoint.__path !== "string" ||
+                !endpoint.__path.startsWith("/api/") ||
+                typeof endpoint.__method !== "string") {
+                throw new TypeError("apiMcp tools need a createEndpoint reference with an explicit /api path; use createEndpoint('/api/...', options, handler), or keep mcp metadata on a path-inferred route.");
+            }
+            if (endpoint.__path === options.path) {
+                throw new TypeError(`apiMcp cannot expose its own route (${endpoint.__method} ${endpoint.__path}).`);
+            }
+            // Config and route modules may be independently evaluated. Resolve the
+            // mounted endpoint by its declared contract, never by function identity.
+            const mounted = api.get(endpoint.__method, endpoint.__path);
+            if (!mounted)
+                throw new TypeError(`apiMcp ${endpoint.__method} ${endpoint.__path} is not a mounted app endpoint.`);
+            select(mounted, metadata);
+        }
+    }
+    if (selected.length === 0) {
+        throw new TypeError("apiMcp needs at least one endpoint or standalone tool selected in tools, or route-owned MCP metadata.");
+    }
+    const names = new Set();
+    for (const { key, config } of selected) {
+        if (typeof config.name !== "string" || !TOOL_NAME.test(config.name)) {
+            throw new TypeError(`apiMcp tool for "${key}" needs a valid MCP name (1-128 letters, numbers, dots, underscores, or hyphens).`);
+        }
+        if (names.has(config.name))
+            throw new TypeError(`apiMcp tool name "${config.name}" is duplicated.`);
+        names.add(config.name);
+    }
+    return selected;
+}
+function deriveToolName(method, path) {
+    const parts = [method.toLowerCase()];
+    for (const segment of path.split("/").slice(2)) {
+        const parameter = /^\[{1,2}(?:\.\.\.)?([^\]]+)\]{1,2}$/.exec(segment)?.[1];
+        const source = parameter ?? segment;
+        const normalized = source
+            .normalize("NFKD")
+            .replace(/[^A-Za-z0-9]+/g, "_")
+            .replace(/^_+|_+$/g, "")
+            .toLowerCase();
+        if (!normalized) {
+            throw new TypeError(`apiMcp cannot derive a tool name for ${method} ${path}; set mcp: { name: "..." }.`);
+        }
+        if (parameter)
+            parts.push("by");
+        parts.push(normalized);
+    }
+    if (parts.length === 1)
+        parts.push("api");
+    const name = parts.join("_");
+    if (!TOOL_NAME.test(name)) {
+        throw new TypeError(`apiMcp cannot derive a valid tool name for ${method} ${path}; set mcp: { name: "..." }.`);
+    }
+    return name;
+}
+function createToolInputSchema(endpoint) {
+    const properties = {};
+    const required = [];
+    const pathParams = createPathParamsSchema(endpoint.path, endpoint.input.params);
+    if (pathParams) {
+        properties.params = pathParams;
+        if (pathParams.required?.length)
+            required.push("params");
+    }
+    if (endpoint.input.query) {
+        const query = requireObjectSchema(toToolJSONSchema(endpoint.input.query, "query"), "query");
+        properties.query = query;
+        if (query.required?.length)
+            required.push("query");
+    }
+    if (endpoint.input.body) {
+        properties.body = toToolJSONSchema(endpoint.input.body, "body");
+        required.push("body");
+    }
+    if (endpoint.input.headers) {
+        const headers = safeHeaderSchema(requireObjectSchema(toToolJSONSchema(endpoint.input.headers, "headers"), "headers"));
+        if (Object.keys(headers.properties ?? {}).length > 0) {
+            properties.headers = headers;
+            if (headers.required?.length)
+                required.push("headers");
+        }
+    }
+    return {
+        type: "object",
+        properties,
+        ...(required.length ? { required } : {}),
+        additionalProperties: false,
+    };
+}
+function createPathParamsSchema(path, schema) {
+    const segments = [
+        ...path.matchAll(/\/(?:\[\[\.\.\.([^\]]+)\]\]|\[\.\.\.([^\]]+)\]|\[([^\]]+)\])/g),
+    ];
+    if (segments.length === 0)
+        return undefined;
+    if (schema)
+        return requireObjectSchema(toToolJSONSchema(schema, "params"), "params");
+    const properties = {};
+    const required = [];
+    for (const match of segments) {
+        const name = match[1] ?? match[2] ?? match[3];
+        const catchAll = Boolean(match[1] || match[2]);
+        properties[name] = catchAll
+            ? { type: "array", items: { type: "string" }, minItems: match[1] ? 0 : 1 }
+            : { type: "string" };
+        if (!match[1])
+            required.push(name);
+    }
+    return { type: "object", properties, required, additionalProperties: false };
+}
+function toToolJSONSchema(schema, location, io = "input") {
+    let result;
+    try {
+        const standardJSON = schema["~standard"]?.jsonSchema?.[io];
+        result =
+            typeof standardJSON === "function"
+                ? standardJSON({ target: "draft-2020-12" })
+                : toJSONSchema(schema, { io });
+    }
+    catch (error) {
+        const reason = error instanceof Error ? ` ${error.message}` : "";
+        throw new TypeError(`apiMcp cannot represent the selected tool's ${location} schema.${reason}`);
+    }
+    if (!result || typeof result !== "object" || Array.isArray(result)) {
+        throw new TypeError(`apiMcp cannot represent the selected tool's ${location} schema.`);
+    }
+    const json = { ...result };
+    delete json.$schema;
+    return json;
+}
+function createToolOutputSchema(schema) {
+    if (schema === undefined)
+        return undefined;
+    return {
+        type: "object",
+        properties: { result: nestOutputSchema(toToolJSONSchema(schema, "outputSchema", "output")) },
+        required: ["result"],
+        additionalProperties: false,
+    };
+}
+/** Keep document-local references pointing at the result schema, not the new envelope. */
+function nestOutputSchema(schema) {
+    // An explicit resource ID already establishes its own reference scope.
+    if (typeof schema.$id === "string")
+        return schema;
+    const result = { ...schema };
+    for (const keyword of ["$ref", "$dynamicRef"]) {
+        const reference = result[keyword];
+        if (typeof reference === "string" && (reference === "#" || reference.startsWith("#/"))) {
+            result[keyword] = `#/properties/result${reference.slice(1)}`;
+        }
+    }
+    const nest = (value) => value && typeof value === "object" && !Array.isArray(value)
+        ? nestOutputSchema(value)
+        : value;
+    // Visit schema positions only: const/default/examples can contain literal $ref keys.
+    for (const keyword of [
+        "$defs",
+        "definitions",
+        "properties",
+        "patternProperties",
+        "dependentSchemas",
+        "dependencies",
+    ]) {
+        const children = result[keyword];
+        if (children && typeof children === "object" && !Array.isArray(children)) {
+            result[keyword] = Object.fromEntries(Object.entries(children).map(([key, child]) => [key, nest(child)]));
+        }
+    }
+    for (const keyword of [
+        "items",
+        "prefixItems",
+        "allOf",
+        "anyOf",
+        "oneOf",
+        "additionalItems",
+        "additionalProperties",
+        "unevaluatedItems",
+        "unevaluatedProperties",
+        "propertyNames",
+        "contains",
+        "not",
+        "if",
+        "then",
+        "else",
+        "contentSchema",
+    ]) {
+        if (keyword in result) {
+            const child = result[keyword];
+            result[keyword] = Array.isArray(child) ? child.map(nest) : nest(child);
+        }
+    }
+    return result;
+}
+function requireObjectSchema(schema, location) {
+    if (schema.type !== "object" || !schema.properties || typeof schema.properties !== "object") {
+        throw new TypeError(`apiMcp ${location} schemas must describe an object.`);
+    }
+    return schema;
+}
+function safeHeaderSchema(schema) {
+    const properties = Object.fromEntries(Object.entries(schema.properties).filter(([name]) => !PROTECTED_HEADER.test(name)));
+    const required = (schema.required ?? []).filter((name) => !PROTECTED_HEADER.test(name));
+    const safe = {
+        ...schema,
+        properties,
+        additionalProperties: false,
+    };
+    if (required.length)
+        safe.required = required;
+    else
+        delete safe.required;
+    return safe;
+}
+function interpolatePath(path, params) {
+    return path
+        .split("/")
+        .map((segment) => {
+        const optional = /^\[\[\.\.\.(.+)\]\]$/.exec(segment);
+        const catchAll = /^\[\.\.\.(.+)\]$/.exec(segment);
+        const dynamic = /^\[(.+)\]$/.exec(segment);
+        const name = optional?.[1] ?? catchAll?.[1] ?? dynamic?.[1];
+        if (!name)
+            return segment;
+        const value = params[name];
+        if (optional && (value === undefined || (Array.isArray(value) && value.length === 0)))
+            return "";
+        if (value === undefined)
+            throw new TypeError(`Missing route parameter "${name}".`);
+        if (optional || catchAll) {
+            if (!Array.isArray(value))
+                throw new TypeError(`Route parameter "${name}" must be an array.`);
+            return value.map((part) => encodeURIComponent(String(part))).join("/");
+        }
+        if (Array.isArray(value) || (typeof value === "object" && value !== null)) {
+            throw new TypeError(`Route parameter "${name}" must be a scalar value.`);
+        }
+        return encodeURIComponent(String(value));
+    })
+        .filter(Boolean)
+        .join("/")
+        .replace(/^/, "/");
+}
+function appendQuery(url, query) {
+    for (const [key, value] of Object.entries(query)) {
+        const values = Array.isArray(value) ? value : [value];
+        for (const entry of values) {
+            if (entry === undefined)
+                continue;
+            if (entry !== null && typeof entry === "object") {
+                throw new TypeError(`Query parameter "${key}" must be a scalar value or an array.`);
+            }
+            url.searchParams.append(key, String(entry));
+        }
+    }
+}
+function createForwardedHeaders(source, supplied) {
+    const headers = new Headers(source);
+    headers.delete("content-length");
+    headers.delete("content-type");
+    for (const name of Array.from(headers.keys())) {
+        if (name.toLowerCase().startsWith("mcp-"))
+            headers.delete(name);
+    }
+    for (const [name, value] of Object.entries(supplied)) {
+        if (PROTECTED_HEADER.test(name)) {
+            throw new TypeError(`Tool input cannot override protected header "${name}".`);
+        }
+        if (typeof value !== "string")
+            throw new TypeError(`Header "${name}" must be a string.`);
+        headers.set(name, value);
+    }
+    return headers;
+}
+function asRecord(value, location) {
+    if (value === undefined)
+        return {};
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new TypeError(`Tool ${location} must be an object.`);
+    }
+    return value;
+}
+function createAnnotations(method, options) {
+    const readOnly = method === "GET" || method === "HEAD" || method === "QUERY";
+    return {
+        readOnlyHint: options.readOnlyHint ?? readOnly,
+        destructiveHint: options.destructiveHint ?? (method === undefined || method === "DELETE"),
+        ...(options.idempotentHint === undefined ? {} : { idempotentHint: options.idempotentHint }),
+        ...(options.openWorldHint === undefined ? {} : { openWorldHint: options.openWorldHint }),
+    };
+}
+function getCalledTool(body) {
+    if (!body || typeof body !== "object" || Array.isArray(body))
+        return undefined;
+    const request = body;
+    return request.method === "tools/call" && typeof request.params?.name === "string"
+        ? request.params.name
+        : undefined;
+}
+function sameAuthorizationIdentity(left, right) {
+    return (left.subject === right.subject &&
+        sameAuthorizationList(left.scopes, right.scopes) &&
+        sameAuthorizationList(left.tools, right.tools));
+}
+function sameAuthorizationList(left, right) {
+    if (left === undefined || right === undefined)
+        return left === right;
+    if (!Array.isArray(left) || !Array.isArray(right))
+        return false;
+    const leftSet = new Set(left);
+    const rightSet = new Set(right);
+    return (leftSet.size === rightSet.size && Array.from(leftSet).every((value) => rightSet.has(value)));
+}
+function resolveAllowedTools(authorization, names) {
+    if (authorization.tools === undefined)
+        return undefined;
+    if (!Array.isArray(authorization.tools) ||
+        authorization.tools.some((name) => typeof name !== "string" || !names.has(name))) {
+        throw new TypeError("apiMcp authorize tools must be an array of configured tool names.");
+    }
+    return [...authorization.tools];
+}
+function toMCPAuthInfo(authorization, allowedTools) {
+    return {
+        token: "farm-authorized",
+        clientId: authorization.subject,
+        scopes: Array.isArray(authorization.scopes) ? authorization.scopes : [],
+        extra: { farmAuthorization: authorization, farmAllowedTools: allowedTools },
+    };
+}
+function unauthorized() {
+    return new Response(JSON.stringify({ error: "Unauthorized" }), {
+        status: 401,
+        headers: { "content-type": "application/json", "cache-control": "no-store" },
+    });
+}
+function toolError(message) {
+    return { isError: true, content: [{ type: "text", text: message }] };
+}
+function validateOptions(options) {
+    if (!options || typeof options !== "object")
+        throw new TypeError("apiMcp options are required.");
+    if (options.tools !== undefined && !Array.isArray(options.tools)) {
+        throw new TypeError("apiMcp tools must be an array of endpoint references, { endpoint, ...metadata } declarations, or defineTool() tools, not a method/path map.");
+    }
+    if (!options.authorize && options.allowUnauthenticated !== true) {
+        throw new TypeError("apiMcp requires authorize; set allowUnauthenticated: true only for a deliberately public server.");
+    }
+    const path = options.path ?? "/api/mcp";
+    if (!/^\/api\/[^/?#]+(?:\/[^/?#]+)*$/.test(path)) {
+        throw new TypeError("apiMcp path must be a canonical /api path.");
+    }
+    return {
+        ...options,
+        path,
+        name: options.name ?? "farm-api",
+        version: options.version ?? "1.0.0",
+    };
+}

package/dist/internal.d.ts

@@ -0,0 +1,4 @@
+import type { FarmMCPConfig } from "@farm.js/core";
+/** @internal Loaded by Farm when the top-level `mcp` config is enabled. */
+export declare function createFarmMCPPlugin(config: FarmMCPConfig): import("@farm.js/core").FarmPlugin<any, Record<string, unknown>, any, any, unknown, false, import("@farm.js/core").PluginRoutes>;
+//# sourceMappingURL=internal.d.ts.map

package/dist/internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAGnD,2EAA2E;AAC3E,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,aAAa,oIAGxD"}

package/dist/internal.js

@@ -0,0 +1,6 @@
+import { apiMcp } from "./index.js";
+/** @internal Loaded by Farm when the top-level `mcp` config is enabled. */
+export function createFarmMCPPlugin(config) {
+    const { enabled: _enabled, ...options } = config;
+    return apiMcp(options);
+}

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@farm.js/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-beta.1",
+  "description": "Compose Farm.js API routes and standalone tools in one MCP server",
+  "keywords": [
+    "agents",
+    "farm.js",
+    "mcp"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/farming-labs/farm.js",
+    "directory": "packages/farm-mcp"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./internal": {
+      "types": "./dist/internal.d.ts",
+      "import": "./dist/internal.js",
+      "default": "./dist/internal.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "2.0.0",
+    "zod": "^4.1.12",
+    "@farm.js/core": "0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.5",
+    "typescript": "^5.3.3",
+    "vitest": "^3.2.7"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc",
+    "dev": "tsc --watch",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }