@farm.js/core 0.1.15 → 0.1.17

package/dist/server-fn.cjs

@@ -25,9 +25,14 @@ __export(server_fn_exports, {
   FARM_SERVER_FN_SYMBOL: () => FARM_SERVER_FN_SYMBOL,
   ServerActionError: () => ServerActionError,
   ServerFnFailure: () => ServerFnFailure,
+  _attachServerFunctionDescriptor: () => _attachServerFunctionDescriptor,
+  _describeServerFunction: () => _describeServerFunction,
+  _invokeServerFunction: () => _invokeServerFunction,
   _parseServerFnSchema: () => _parseServerFnSchema,
+  _runServerFunctionForCaller: () => _runServerFunctionForCaller,
   createServerFn: () => createServerFn,
   createServerFnTransportError: () => createServerFnTransportError,
+  createServerFunctionDescriptor: () => createServerFunctionDescriptor,
   createServerMiddleware: () => createServerMiddleware,
   isServerFnFailure: () => isServerFnFailure
 });
@@ -137,6 +142,26 @@ __name(isSerializedServerFnFailure, "isSerializedServerFnFailure");
 // src/server-action-security.ts
 var SERVER_ACTION_STORAGE_KEY = /* @__PURE__ */ Symbol.for("farm.serverActionStorage");
 var FALLBACK_ABORT_CONTROLLER_KEY = /* @__PURE__ */ Symbol.for("farm.serverActionFallbackAbortController");
+async function runWithServerActionRequest(request, callback) {
+  throwIfAborted(request.signal);
+  const context2 = {
+    request,
+    signal: request.signal,
+    invalidations: /* @__PURE__ */ new Set(),
+    cacheTasks: /* @__PURE__ */ new Set()
+  };
+  return getServerActionStorage().run(context2, async () => {
+    try {
+      const result = await callback();
+      await Promise.all(context2.cacheTasks);
+      return result;
+    } catch (error) {
+      await Promise.allSettled(context2.cacheTasks);
+      throw error;
+    }
+  });
+}
+__name(runWithServerActionRequest, "runWithServerActionRequest");
 function getServerActionExecutionContext() {
   return getServerActionStorage().getStore();
 }
@@ -167,6 +192,12 @@ function getFallbackAbortController() {
   return globalState2[FALLBACK_ABORT_CONTROLLER_KEY];
 }
 __name(getFallbackAbortController, "getFallbackAbortController");
+function throwIfAborted(signal) {
+  if (!signal.aborted) return;
+  if (signal.reason !== void 0) throw signal.reason;
+  throw new DOMException("The operation was aborted", "AbortError");
+}
+__name(throwIfAborted, "throwIfAborted");
 
 // src/server/request-bridge.ts
 var CURRENT_REQUEST_RESOLVER_KEY = /* @__PURE__ */ Symbol.for("farm.currentRequestResolver");
@@ -563,6 +594,8 @@ var _FarmDataCache = class _FarmDataCache {
   constructor(config = {}) {
     this.entries = /* @__PURE__ */ new Map();
     this.inflight = /* @__PURE__ */ new Map();
+    /** Local entries by tag, so tag counts and pruning never scan unrelated entries. */
+    this.entriesByTag = /* @__PURE__ */ new Map();
     this.invalidatedTagVersions = /* @__PURE__ */ new Map();
     this.activeGenerations = /* @__PURE__ */ new Set();
     this.version = 0;
@@ -581,6 +614,7 @@ var _FarmDataCache = class _FarmDataCache {
   configure(config = {}) {
     this.generation++;
     this.entries.clear();
+    this.entriesByTag.clear();
     this.inflight.clear();
     this.invalidatedTagVersions.clear();
     this.activeGenerations.clear();
@@ -747,14 +781,12 @@ var _FarmDataCache = class _FarmDataCache {
     return entry;
   }
   delete(key) {
-    const deleted = this.entries.delete(key);
-    if (deleted) this.pruneInvalidatedTagVersions();
+    const deleted = this.deleteLocalEntry(key);
     emitFarmEvent({ type: "cache.delete", key, deleted });
     return deleted;
   }
   async deleteAsync(key) {
-    const deleted = this.entries.delete(key);
-    if (deleted) this.pruneInvalidatedTagVersions();
+    const deleted = this.deleteLocalEntry(key);
     if (this.adapter) {
       await this.adapter.delete(this.createAdapterKey(key));
     }
@@ -765,6 +797,7 @@ var _FarmDataCache = class _FarmDataCache {
     const count = this.entries.size;
     this.generation++;
     this.entries.clear();
+    this.entriesByTag.clear();
     this.inflight.clear();
     this.invalidatedTagVersions.clear();
     this.activeGenerations.clear();
@@ -850,23 +883,32 @@ var _FarmDataCache = class _FarmDataCache {
       return cached.value;
     }
     const inflight = this.inflight.get(key);
-    if (inflight) {
+    if (inflight && !this.wasInvalidatedSince(inflight.tags, inflight.startVersion)) {
       emitFarmEvent({ type: "cache.dedupe", key });
-      return inflight;
+      return inflight.promise;
     }
     const tags = Array.from(normalizeCacheOptionsTags(options));
     const generation = this.generation;
+    const startVersion = this.version;
     const promise = this.fillCacheEntry(key, producer, options, tags, generation).catch((error) => {
       emitFarmEvent({ type: "cache.error", key, operation: "set", error });
       throw error;
     }).finally(() => {
-      if (this.inflight.get(key) === promise) {
+      if (this.inflight.get(key)?.promise === promise) {
         this.inflight.delete(key);
       }
     });
-    this.inflight.set(key, promise);
+    this.inflight.set(key, { promise, tags, startVersion });
     return promise;
   }
+  /** A fill that started before one of its tags was invalidated cannot satisfy later readers. */
+  wasInvalidatedSince(tags, version) {
+    for (const tag of tags) {
+      const invalidatedVersion = this.invalidatedTagVersions.get(tag);
+      if (invalidatedVersion !== void 0 && invalidatedVersion > version) return true;
+    }
+    return false;
+  }
   async fillCacheEntry(key, producer, options, tags, generation) {
     const adapter = this.adapter;
     const namespace = this.namespace;
@@ -907,7 +949,7 @@ var _FarmDataCache = class _FarmDataCache {
       return value;
     } finally {
       this.activeGenerations.delete(activeGeneration);
-      this.pruneInvalidatedTagVersions();
+      this.pruneInvalidatedTagVersions(activeGeneration.tags);
       if (leaseToken && adapter?.releaseLease) {
         try {
           await adapter.releaseLease(leaseKey, leaseToken);
@@ -952,18 +994,9 @@ var _FarmDataCache = class _FarmDataCache {
     }
     return void 0;
   }
-  countEntriesForTag(tag) {
-    let count = 0;
-    for (const entry of this.entries.values()) {
-      if (entry.tags.has(tag)) {
-        count++;
-      }
-    }
-    return count;
-  }
   countEntriesForTags(tags) {
     let count = 0;
-    for (const entry of this.entries.values()) {
+    for (const entry of this.entriesByTag.get(tags[0]) ?? []) {
       if (tags.every((tag) => entry.tags.has(tag))) {
         count++;
       }
@@ -971,10 +1004,10 @@ var _FarmDataCache = class _FarmDataCache {
     return count;
   }
   invalidateTag(normalizedTag) {
-    const count = this.countEntriesForTag(normalizedTag);
+    const count = this.entriesByTag.get(normalizedTag)?.size ?? 0;
     this.invalidatedTagVersions.delete(normalizedTag);
     this.invalidatedTagVersions.set(normalizedTag, ++this.version);
-    this.pruneInvalidatedTagVersions();
+    this.pruneInvalidatedTagVersions([normalizedTag]);
     return count;
   }
   toPublicEntry(entry) {
@@ -1004,19 +1037,51 @@ var _FarmDataCache = class _FarmDataCache {
     this.entries.set(key, entry);
   }
   storeLocalEntry(entry) {
-    this.entries.delete(entry.key);
+    const removed = [];
+    const replaced = this.detachLocalEntry(entry.key);
+    if (replaced) removed.push(replaced);
     this.entries.set(entry.key, entry);
+    for (const tag of entry.tags) {
+      let tagged = this.entriesByTag.get(tag);
+      if (!tagged) this.entriesByTag.set(tag, tagged = /* @__PURE__ */ new Set());
+      tagged.add(entry);
+    }
     while (this.entries.size > this.maxEntries) {
       const oldestKey = this.entries.keys().next().value;
       if (oldestKey === void 0) break;
-      this.entries.delete(oldestKey);
+      removed.push(this.detachLocalEntry(oldestKey));
     }
-    this.pruneInvalidatedTagVersions();
+    for (const removedEntry of removed) this.pruneInvalidatedTagVersions(removedEntry.tags);
   }
-  pruneInvalidatedTagVersions() {
-    tags: for (const [tag, invalidatedVersion] of this.invalidatedTagVersions) {
-      for (const entry of this.entries.values()) {
-        if (entry.tags.has(tag) && entry.createdVersion < invalidatedVersion) continue tags;
+  deleteLocalEntry(key) {
+    const entry = this.detachLocalEntry(key);
+    if (!entry) return false;
+    this.pruneInvalidatedTagVersions(entry.tags);
+    return true;
+  }
+  detachLocalEntry(key) {
+    const entry = this.entries.get(key);
+    if (!entry) return void 0;
+    this.entries.delete(key);
+    for (const tag of entry.tags) {
+      const tagged = this.entriesByTag.get(tag);
+      if (!tagged) continue;
+      tagged.delete(entry);
+      if (tagged.size === 0) this.entriesByTag.delete(tag);
+    }
+    return entry;
+  }
+  /**
+   * Drop invalidation versions that no local entry or active fill can be stale against.
+   * Callers pass only the tags whose dependents just changed, so the cost is bounded by
+   * the entries sharing those tags rather than by the whole cache.
+   */
+  pruneInvalidatedTagVersions(tags) {
+    tags: for (const tag of tags) {
+      const invalidatedVersion = this.invalidatedTagVersions.get(tag);
+      if (invalidatedVersion === void 0) continue;
+      for (const entry of this.entriesByTag.get(tag) ?? []) {
+        if (entry.createdVersion < invalidatedVersion) continue tags;
       }
       for (const generation of this.activeGenerations) {
         if (generation.tags.has(tag) && generation.createdVersion < invalidatedVersion)
@@ -1379,8 +1444,100 @@ function stableSerialize(value, seen = /* @__PURE__ */ new WeakSet()) {
 }
 __name(stableSerialize, "stableSerialize");
 
+// src/navigation-errors.ts
+var REDIRECT_ERROR_CODE = "FARM_REDIRECT";
+var REDIRECT_ERROR_SYMBOL = /* @__PURE__ */ Symbol.for("farm.navigation.redirect");
+function getFarmRedirectError(error) {
+  if (!error || typeof error !== "object") return null;
+  const candidate = error;
+  if (candidate[REDIRECT_ERROR_SYMBOL]) {
+    return candidate[REDIRECT_ERROR_SYMBOL];
+  }
+  if (typeof candidate.digest === "string" && candidate.digest.startsWith(`${REDIRECT_ERROR_CODE};`)) {
+    const [, status, ...urlParts] = candidate.digest.split(";");
+    const parsedStatus = Number(status);
+    if (isFarmRedirectStatus(parsedStatus)) {
+      return {
+        status: parsedStatus,
+        url: urlParts.join(";")
+      };
+    }
+  }
+  return null;
+}
+__name(getFarmRedirectError, "getFarmRedirectError");
+function isFarmRedirectStatus(status) {
+  return status === 301 || status === 302 || status === 303 || status === 307 || status === 308;
+}
+__name(isFarmRedirectStatus, "isFarmRedirectStatus");
+
 // src/server-fn.ts
 var FARM_SERVER_FN_SYMBOL = /* @__PURE__ */ Symbol.for("farm.server-fn");
+var FARM_SERVER_FUNCTION_DESCRIPTOR = /* @__PURE__ */ Symbol.for("farm.server-function.descriptor");
+var _ServerFnInputError = class _ServerFnInputError extends Error {
+  constructor(cause) {
+    super("Server function input is invalid");
+    this.cause = cause;
+  }
+};
+__name(_ServerFnInputError, "ServerFnInputError");
+var ServerFnInputError = _ServerFnInputError;
+function createServerFunctionDescriptor(kind, options, run) {
+  return Object.freeze({
+    kind,
+    input: options.input,
+    output: options.output,
+    mcp: options.mcp === void 0 ? void 0 : Object.freeze({ ...options.mcp }),
+    run
+  });
+}
+__name(createServerFunctionDescriptor, "createServerFunctionDescriptor");
+function _attachServerFunctionDescriptor(target, descriptor) {
+  Object.defineProperty(target, FARM_SERVER_FUNCTION_DESCRIPTOR, {
+    value: descriptor,
+    enumerable: false
+  });
+}
+__name(_attachServerFunctionDescriptor, "_attachServerFunctionDescriptor");
+function getServerFunctionRunner(value) {
+  if (typeof value !== "function") return void 0;
+  return value[FARM_SERVER_FUNCTION_DESCRIPTOR];
+}
+__name(getServerFunctionRunner, "getServerFunctionRunner");
+function _runServerFunctionForCaller(value, input) {
+  const runner = getServerFunctionRunner(value);
+  if (!runner) throw new TypeError("Expected a function created with createServerFn");
+  return runner.run(input);
+}
+__name(_runServerFunctionForCaller, "_runServerFunctionForCaller");
+function _describeServerFunction(value) {
+  const runner = getServerFunctionRunner(value);
+  if (!runner) return void 0;
+  const { kind, input, output, mcp } = runner;
+  return Object.freeze({ kind, input, output, mcp });
+}
+__name(_describeServerFunction, "_describeServerFunction");
+async function _invokeServerFunction(value, input, request) {
+  const runner = getServerFunctionRunner(value);
+  if (!runner) {
+    throw new TypeError("Expected a function created with createServerFn or createServerQuery");
+  }
+  try {
+    const data = await runWithServerActionRequest(request, () => runner.run(input));
+    return { ok: true, data };
+  } catch (error) {
+    if (error instanceof ServerFnInputError) {
+      return { ok: false, reason: "input", error: error.cause };
+    }
+    if (isServerFnFailure(error)) return { ok: false, reason: "failure", failure: error };
+    const redirect = getFarmRedirectError(error);
+    if (redirect) {
+      return { ok: false, reason: "redirect", url: redirect.url, status: redirect.status };
+    }
+    return { ok: false, reason: "error", error };
+  }
+}
+__name(_invokeServerFunction, "_invokeServerFunction");
 var UNSAFE_FORM_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
 function createServerMiddleware(options) {
   if (!options || typeof options.handler !== "function") {
@@ -1404,10 +1561,15 @@ function createServerFn(options) {
   const middleware = resolveServerFnMiddleware(options.middleware);
   const errors = normalizeServerFnErrors(options.errors);
   const error = createServerFnErrorHandler(errors);
-  const serverFn = /* @__PURE__ */ __name(async (value) => {
+  const run = /* @__PURE__ */ __name(async (value, labelInputErrors) => {
     const formData = isFormData(value) ? value : void 0;
     const rawInput = formData ? formDataToObject(formData) : value;
-    const input = await _parseServerFnSchema(options.input, rawInput, "input");
+    let input;
+    try {
+      input = await _parseServerFnSchema(options.input, rawInput, "input");
+    } catch (cause) {
+      throw labelInputErrors && isSchemaValidationFailure(cause) ? new ServerFnInputError(cause) : cause;
+    }
     const executionContext = getServerActionExecutionContext();
     const request = executionContext?.request ?? _resolveCurrentRequest();
     const signal = executionContext?.signal ?? request?.signal ?? getServerActionSignal();
@@ -1433,7 +1595,8 @@ function createServerFn(options) {
       await applyFarmCacheInvalidationTargets(declaration);
     }
     return parsedResult;
-  }, "serverFn");
+  }, "run");
+  const serverFn = /* @__PURE__ */ __name((value) => run(value, false), "serverFn");
   Object.defineProperties(serverFn, {
     [FARM_SERVER_FN_SYMBOL]: {
       value: true,
@@ -1464,6 +1627,10 @@ function createServerFn(options) {
       enumerable: false
     }
   });
+  _attachServerFunctionDescriptor(
+    serverFn,
+    createServerFunctionDescriptor("action", options, (value) => run(value, true))
+  );
   return serverFn;
 }
 __name(createServerFn, "createServerFn");
@@ -1621,9 +1788,17 @@ async function _parseServerFnSchema(schema, value, contract, owner = "createServ
   throw new TypeError(`${owner} ${contract} must provide parse, parseAsync, or safeParse`);
 }
 __name(_parseServerFnSchema, "_parseServerFnSchema");
+var schemaValidationFailures = /* @__PURE__ */ new WeakSet();
+function isSchemaValidationFailure(error) {
+  if (!error || typeof error !== "object") return false;
+  return schemaValidationFailures.has(error) || Array.isArray(error.issues);
+}
+__name(isSchemaValidationFailure, "isSchemaValidationFailure");
 function unwrapSafeParseResult(result) {
   if (result && typeof result === "object" && "success" in result && result.success === false) {
-    throw result.error;
+    const error = result.error;
+    if (error && typeof error === "object") schemaValidationFailures.add(error);
+    throw error;
   }
   if (result && typeof result === "object" && "success" in result && result.success === true) {
     return result.data;
@@ -1665,9 +1840,14 @@ __name(isFormData, "isFormData");
   FARM_SERVER_FN_SYMBOL,
   ServerActionError,
   ServerFnFailure,
+  _attachServerFunctionDescriptor,
+  _describeServerFunction,
+  _invokeServerFunction,
   _parseServerFnSchema,
+  _runServerFunctionForCaller,
   createServerFn,
   createServerFnTransportError,
+  createServerFunctionDescriptor,
   createServerMiddleware,
   isServerFnFailure
 });

package/dist/server-fn.d.mts

@@ -1,6 +1,7 @@
 import { FarmCacheInvalidationTarget } from './cache.mjs';
 import { S as ServerFnFailure, a as ServerActionError } from './server-fn-error-DDh14a0V.mjs';
 export { F as FARM_SERVER_FN_FAILURE_SYMBOL, b as SerializedServerFnFailure, c as createServerFnTransportError, i as isServerFnFailure } from './server-fn-error-DDh14a0V.mjs';
+import { d as EndpointMCPMetadata } from './endpoint-DAc96i93.mjs';
 
 type MaybePromise<T> = T | Promise<T>;
 type ServerFnSchema = {
@@ -38,6 +39,10 @@ type ServerFnDeclaredError<TErrors extends ServerFnErrorDefinitions> = {
 type ServerFnError<TErrors extends ServerFnErrorDefinitions> = keyof TErrors extends never ? Error : ServerActionError | ServerFnDeclaredError<TErrors>;
 type ServerFnErrorHandler<TErrors extends ServerFnErrorDefinitions> = <TCode extends keyof TErrors & string>(code: TCode, data: InferServerFnSchemaInput<TErrors[TCode]["data"]>) => never;
 type ServerFnFormInput = FormData;
+/** MCP tool metadata for a server function or query. Server functions have no path to derive a name from. */
+type ServerFnMCPMetadata = EndpointMCPMetadata & {
+    name: string;
+};
 type Simplify<T> = {
     [TKey in keyof T]: T[TKey];
 } & {};
@@ -92,6 +97,8 @@ type ServerFnOptions<TSchema extends ServerFnSchema | undefined, TResult, TMiddl
     output?: undefined;
     middleware?: TMiddlewares;
     errors?: TErrors;
+    /** Expose this function as an MCP tool when it is listed in `mcp.tools`. `name` is required. */
+    mcp?: ServerFnMCPMetadata;
     invalidates?: ServerFnInvalidations<TSchema extends ServerFnSchema ? InferServerFnSchemaOutput<TSchema> : unknown, Awaited<TResult>, ServerFnMiddlewareContext<TMiddlewares>>;
     handler: ServerFnHandler<TSchema extends ServerFnSchema ? InferServerFnSchemaOutput<TSchema> : unknown, TResult, ServerFnMiddlewareContext<TMiddlewares>, TErrors>;
 };
@@ -100,6 +107,8 @@ type ServerFnOutputOptions<TInputSchema extends ServerFnSchema | undefined, TOut
     output: TOutputSchema;
     middleware?: TMiddlewares;
     errors?: TErrors;
+    /** Expose this function as an MCP tool when it is listed in `mcp.tools`. `name` is required. */
+    mcp?: ServerFnMCPMetadata;
     invalidates?: ServerFnInvalidations<TInputSchema extends ServerFnSchema ? InferServerFnSchemaOutput<TInputSchema> : unknown, Awaited<InferServerFnSchemaOutput<TOutputSchema>>, ServerFnMiddlewareContext<TMiddlewares>>;
     handler: ServerFnHandler<TInputSchema extends ServerFnSchema ? InferServerFnSchemaOutput<TInputSchema> : unknown, unknown, ServerFnMiddlewareContext<TMiddlewares>, TErrors>;
 };
@@ -111,6 +120,68 @@ type ServerFn<TInput, TResult, TError extends Error = Error> = ([unknown] extend
 };
 type InferServerFnError<TServerFn> = TServerFn extends ServerFn<any, any, infer TError> ? TError : Error;
 declare const FARM_SERVER_FN_SYMBOL: unique symbol;
+/** @internal What a non-browser caller, such as an MCP tool, needs to know about a server function. */
+interface ServerFunctionDescriptor {
+    /** Queries only read data; actions may change it. */
+    readonly kind: "action" | "query";
+    readonly input: ServerFnSchema | undefined;
+    readonly output: ServerFnSchema | undefined;
+    readonly mcp: Readonly<ServerFnMCPMetadata> | undefined;
+}
+interface ServerFunctionRunner extends ServerFunctionDescriptor {
+    /** Runs the full pipeline and labels input validation failures with ServerFnInputError. */
+    readonly run: (input: unknown) => Promise<unknown>;
+}
+/** @internal Shared by createServerFn and createServerQuery. */
+declare function createServerFunctionDescriptor(kind: ServerFunctionDescriptor["kind"], options: {
+    input?: ServerFnSchema;
+    output?: ServerFnSchema;
+    mcp?: ServerFnMCPMetadata;
+}, run: ServerFunctionRunner["run"]): ServerFunctionRunner;
+/** @internal Attaches the descriptor that `_describeServerFunction` reads. */
+declare function _attachServerFunctionDescriptor(target: object, descriptor: ServerFunctionRunner): void;
+/** @internal Runs a server function's pipeline with input failures labelled, for createServerQuery. */
+declare function _runServerFunctionForCaller(value: unknown, input: unknown): Promise<unknown>;
+/**
+ * @internal Describes a createServerFn or createServerQuery function, or returns undefined for
+ * anything else. Exposes schemas and metadata, never the handler.
+ */
+declare function _describeServerFunction(value: unknown): ServerFunctionDescriptor | undefined;
+/** @internal How a server function call ended, for callers that are not the browser action transport. */
+type ServerFunctionInvocation = {
+    readonly ok: true;
+    readonly data: unknown;
+}
+/** The caller's input failed the input schema. The validator's error describes the caller's own data. */
+ | {
+    readonly ok: false;
+    readonly reason: "input";
+    readonly error: unknown;
+}
+/** A failure declared in `errors`, public by design. */
+ | {
+    readonly ok: false;
+    readonly reason: "failure";
+    readonly failure: ServerFnFailure;
+} | {
+    readonly ok: false;
+    readonly reason: "redirect";
+    readonly url: string;
+    readonly status: number;
+}
+/** Anything else. Can contain private data, so callers must not expose it. */
+ | {
+    readonly ok: false;
+    readonly reason: "error";
+    readonly error: unknown;
+};
+/**
+ * @internal Runs a server function or query on behalf of a non-browser caller, such as an MCP
+ * tool call. Runs the same pipeline as a browser action (input schema, middleware, handler,
+ * output schema, invalidations) with `request` as the action request, so middleware reads the
+ * caller's headers. A query resolves to its data rather than the client cache envelope.
+ */
+declare function _invokeServerFunction(value: unknown, input: unknown, request: Request): Promise<ServerFunctionInvocation>;
 declare function createServerMiddleware<const TMiddlewares extends readonly AnyServerFnMiddleware[] = readonly [], TProvidedContext extends object = {}>(options: ServerFnMiddlewareOptions<TMiddlewares, TProvidedContext>): ServerFnMiddleware<AssignContext<ServerFnMiddlewareContext<TMiddlewares>, TProvidedContext>>;
 declare function createServerFn<TInputSchema extends ServerFnSchema, TOutputSchema extends ServerFnSchema, const TMiddlewares extends readonly AnyServerFnMiddleware[] = readonly [], const TErrors extends ServerFnErrorDefinitions = {}>(options: ServerFnOutputOptions<TInputSchema, TOutputSchema, TMiddlewares, TErrors>): ServerFn<InferServerFnSchemaInput<TInputSchema>, Awaited<InferServerFnSchemaOutput<TOutputSchema>>, ServerFnError<TErrors>>;
 declare function createServerFn<TOutputSchema extends ServerFnSchema, const TMiddlewares extends readonly AnyServerFnMiddleware[] = readonly [], const TErrors extends ServerFnErrorDefinitions = {}>(options: ServerFnOutputOptions<undefined, TOutputSchema, TMiddlewares, TErrors>): ServerFn<unknown, Awaited<InferServerFnSchemaOutput<TOutputSchema>>, ServerFnError<TErrors>>;
@@ -118,4 +189,4 @@ declare function createServerFn<TSchema extends ServerFnSchema, TResult, const T
 declare function createServerFn<TResult, const TMiddlewares extends readonly AnyServerFnMiddleware[] = readonly [], const TErrors extends ServerFnErrorDefinitions = {}>(options: ServerFnOptions<undefined, TResult, TMiddlewares, TErrors>): ServerFn<unknown, Awaited<TResult>, ServerFnError<TErrors>>;
 declare function _parseServerFnSchema(schema: ServerFnSchema | undefined, value: unknown, contract: "input" | "output", owner?: string): Promise<any>;
 
-export { type AnyServerFnMiddleware, FARM_SERVER_FN_SYMBOL, type InferServerFnError, type InferServerFnSchemaInput, type InferServerFnSchemaOutput, ServerActionError, type ServerFn, type ServerFnContext, type ServerFnDeclaredError, type ServerFnError, type ServerFnErrorDefinition, type ServerFnErrorDefinitions, type ServerFnErrorHandler, type ServerFnErrorSchema, ServerFnFailure, type ServerFnFormInput, type ServerFnHandler, type ServerFnHandlerContext, type ServerFnInvalidationContext, type ServerFnInvalidations, type ServerFnMiddleware, type ServerFnMiddlewareContext, type ServerFnMiddlewareContinuation, type ServerFnMiddlewareHandler, type ServerFnMiddlewareHandlerContext, type ServerFnMiddlewareNext, type ServerFnMiddlewareOptions, type ServerFnOptions, type ServerFnOutputOptions, type ServerFnSchema, _parseServerFnSchema, createServerFn, createServerMiddleware };
+export { type AnyServerFnMiddleware, FARM_SERVER_FN_SYMBOL, type InferServerFnError, type InferServerFnSchemaInput, type InferServerFnSchemaOutput, ServerActionError, type ServerFn, type ServerFnContext, type ServerFnDeclaredError, type ServerFnError, type ServerFnErrorDefinition, type ServerFnErrorDefinitions, type ServerFnErrorHandler, type ServerFnErrorSchema, ServerFnFailure, type ServerFnFormInput, type ServerFnHandler, type ServerFnHandlerContext, type ServerFnInvalidationContext, type ServerFnInvalidations, type ServerFnMCPMetadata, type ServerFnMiddleware, type ServerFnMiddlewareContext, type ServerFnMiddlewareContinuation, type ServerFnMiddlewareHandler, type ServerFnMiddlewareHandlerContext, type ServerFnMiddlewareNext, type ServerFnMiddlewareOptions, type ServerFnOptions, type ServerFnOutputOptions, type ServerFnSchema, type ServerFunctionDescriptor, type ServerFunctionInvocation, _attachServerFunctionDescriptor, _describeServerFunction, _invokeServerFunction, _parseServerFnSchema, _runServerFunctionForCaller, createServerFn, createServerFunctionDescriptor, createServerMiddleware };

package/dist/server-fn.d.ts

@@ -1,6 +1,7 @@
 import { FarmCacheInvalidationTarget } from './cache.js';
 import { S as ServerFnFailure, a as ServerActionError } from './server-fn-error-DDh14a0V.js';
 export { F as FARM_SERVER_FN_FAILURE_SYMBOL, b as SerializedServerFnFailure, c as createServerFnTransportError, i as isServerFnFailure } from './server-fn-error-DDh14a0V.js';
+import { d as EndpointMCPMetadata } from './endpoint-1zA994xL.js';
 
 type MaybePromise<T> = T | Promise<T>;
 type ServerFnSchema = {
@@ -38,6 +39,10 @@ type ServerFnDeclaredError<TErrors extends ServerFnErrorDefinitions> = {
 type ServerFnError<TErrors extends ServerFnErrorDefinitions> = keyof TErrors extends never ? Error : ServerActionError | ServerFnDeclaredError<TErrors>;
 type ServerFnErrorHandler<TErrors extends ServerFnErrorDefinitions> = <TCode extends keyof TErrors & string>(code: TCode, data: InferServerFnSchemaInput<TErrors[TCode]["data"]>) => never;
 type ServerFnFormInput = FormData;
+/** MCP tool metadata for a server function or query. Server functions have no path to derive a name from. */
+type ServerFnMCPMetadata = EndpointMCPMetadata & {
+    name: string;
+};
 type Simplify<T> = {
     [TKey in keyof T]: T[TKey];
 } & {};
@@ -92,6 +97,8 @@ type ServerFnOptions<TSchema extends ServerFnSchema | undefined, TResult, TMiddl
     output?: undefined;
     middleware?: TMiddlewares;
     errors?: TErrors;
+    /** Expose this function as an MCP tool when it is listed in `mcp.tools`. `name` is required. */
+    mcp?: ServerFnMCPMetadata;
     invalidates?: ServerFnInvalidations<TSchema extends ServerFnSchema ? InferServerFnSchemaOutput<TSchema> : unknown, Awaited<TResult>, ServerFnMiddlewareContext<TMiddlewares>>;
     handler: ServerFnHandler<TSchema extends ServerFnSchema ? InferServerFnSchemaOutput<TSchema> : unknown, TResult, ServerFnMiddlewareContext<TMiddlewares>, TErrors>;
 };
@@ -100,6 +107,8 @@ type ServerFnOutputOptions<TInputSchema extends ServerFnSchema | undefined, TOut
     output: TOutputSchema;
     middleware?: TMiddlewares;
     errors?: TErrors;
+    /** Expose this function as an MCP tool when it is listed in `mcp.tools`. `name` is required. */
+    mcp?: ServerFnMCPMetadata;
     invalidates?: ServerFnInvalidations<TInputSchema extends ServerFnSchema ? InferServerFnSchemaOutput<TInputSchema> : unknown, Awaited<InferServerFnSchemaOutput<TOutputSchema>>, ServerFnMiddlewareContext<TMiddlewares>>;
     handler: ServerFnHandler<TInputSchema extends ServerFnSchema ? InferServerFnSchemaOutput<TInputSchema> : unknown, unknown, ServerFnMiddlewareContext<TMiddlewares>, TErrors>;
 };
@@ -111,6 +120,68 @@ type ServerFn<TInput, TResult, TError extends Error = Error> = ([unknown] extend
 };
 type InferServerFnError<TServerFn> = TServerFn extends ServerFn<any, any, infer TError> ? TError : Error;
 declare const FARM_SERVER_FN_SYMBOL: unique symbol;
+/** @internal What a non-browser caller, such as an MCP tool, needs to know about a server function. */
+interface ServerFunctionDescriptor {
+    /** Queries only read data; actions may change it. */
+    readonly kind: "action" | "query";
+    readonly input: ServerFnSchema | undefined;
+    readonly output: ServerFnSchema | undefined;
+    readonly mcp: Readonly<ServerFnMCPMetadata> | undefined;
+}
+interface ServerFunctionRunner extends ServerFunctionDescriptor {
+    /** Runs the full pipeline and labels input validation failures with ServerFnInputError. */
+    readonly run: (input: unknown) => Promise<unknown>;
+}
+/** @internal Shared by createServerFn and createServerQuery. */
+declare function createServerFunctionDescriptor(kind: ServerFunctionDescriptor["kind"], options: {
+    input?: ServerFnSchema;
+    output?: ServerFnSchema;
+    mcp?: ServerFnMCPMetadata;
+}, run: ServerFunctionRunner["run"]): ServerFunctionRunner;
+/** @internal Attaches the descriptor that `_describeServerFunction` reads. */
+declare function _attachServerFunctionDescriptor(target: object, descriptor: ServerFunctionRunner): void;
+/** @internal Runs a server function's pipeline with input failures labelled, for createServerQuery. */
+declare function _runServerFunctionForCaller(value: unknown, input: unknown): Promise<unknown>;
+/**
+ * @internal Describes a createServerFn or createServerQuery function, or returns undefined for
+ * anything else. Exposes schemas and metadata, never the handler.
+ */
+declare function _describeServerFunction(value: unknown): ServerFunctionDescriptor | undefined;
+/** @internal How a server function call ended, for callers that are not the browser action transport. */
+type ServerFunctionInvocation = {
+    readonly ok: true;
+    readonly data: unknown;
+}
+/** The caller's input failed the input schema. The validator's error describes the caller's own data. */
+ | {
+    readonly ok: false;
+    readonly reason: "input";
+    readonly error: unknown;
+}
+/** A failure declared in `errors`, public by design. */
+ | {
+    readonly ok: false;
+    readonly reason: "failure";
+    readonly failure: ServerFnFailure;
+} | {
+    readonly ok: false;
+    readonly reason: "redirect";
+    readonly url: string;
+    readonly status: number;
+}
+/** Anything else. Can contain private data, so callers must not expose it. */
+ | {
+    readonly ok: false;
+    readonly reason: "error";
+    readonly error: unknown;
+};
+/**
+ * @internal Runs a server function or query on behalf of a non-browser caller, such as an MCP
+ * tool call. Runs the same pipeline as a browser action (input schema, middleware, handler,
+ * output schema, invalidations) with `request` as the action request, so middleware reads the
+ * caller's headers. A query resolves to its data rather than the client cache envelope.
+ */
+declare function _invokeServerFunction(value: unknown, input: unknown, request: Request): Promise<ServerFunctionInvocation>;
 declare function createServerMiddleware<const TMiddlewares extends readonly AnyServerFnMiddleware[] = readonly [], TProvidedContext extends object = {}>(options: ServerFnMiddlewareOptions<TMiddlewares, TProvidedContext>): ServerFnMiddleware<AssignContext<ServerFnMiddlewareContext<TMiddlewares>, TProvidedContext>>;
 declare function createServerFn<TInputSchema extends ServerFnSchema, TOutputSchema extends ServerFnSchema, const TMiddlewares extends readonly AnyServerFnMiddleware[] = readonly [], const TErrors extends ServerFnErrorDefinitions = {}>(options: ServerFnOutputOptions<TInputSchema, TOutputSchema, TMiddlewares, TErrors>): ServerFn<InferServerFnSchemaInput<TInputSchema>, Awaited<InferServerFnSchemaOutput<TOutputSchema>>, ServerFnError<TErrors>>;
 declare function createServerFn<TOutputSchema extends ServerFnSchema, const TMiddlewares extends readonly AnyServerFnMiddleware[] = readonly [], const TErrors extends ServerFnErrorDefinitions = {}>(options: ServerFnOutputOptions<undefined, TOutputSchema, TMiddlewares, TErrors>): ServerFn<unknown, Awaited<InferServerFnSchemaOutput<TOutputSchema>>, ServerFnError<TErrors>>;
@@ -118,4 +189,4 @@ declare function createServerFn<TSchema extends ServerFnSchema, TResult, const T
 declare function createServerFn<TResult, const TMiddlewares extends readonly AnyServerFnMiddleware[] = readonly [], const TErrors extends ServerFnErrorDefinitions = {}>(options: ServerFnOptions<undefined, TResult, TMiddlewares, TErrors>): ServerFn<unknown, Awaited<TResult>, ServerFnError<TErrors>>;
 declare function _parseServerFnSchema(schema: ServerFnSchema | undefined, value: unknown, contract: "input" | "output", owner?: string): Promise<any>;
 
-export { type AnyServerFnMiddleware, FARM_SERVER_FN_SYMBOL, type InferServerFnError, type InferServerFnSchemaInput, type InferServerFnSchemaOutput, ServerActionError, type ServerFn, type ServerFnContext, type ServerFnDeclaredError, type ServerFnError, type ServerFnErrorDefinition, type ServerFnErrorDefinitions, type ServerFnErrorHandler, type ServerFnErrorSchema, ServerFnFailure, type ServerFnFormInput, type ServerFnHandler, type ServerFnHandlerContext, type ServerFnInvalidationContext, type ServerFnInvalidations, type ServerFnMiddleware, type ServerFnMiddlewareContext, type ServerFnMiddlewareContinuation, type ServerFnMiddlewareHandler, type ServerFnMiddlewareHandlerContext, type ServerFnMiddlewareNext, type ServerFnMiddlewareOptions, type ServerFnOptions, type ServerFnOutputOptions, type ServerFnSchema, _parseServerFnSchema, createServerFn, createServerMiddleware };
+export { type AnyServerFnMiddleware, FARM_SERVER_FN_SYMBOL, type InferServerFnError, type InferServerFnSchemaInput, type InferServerFnSchemaOutput, ServerActionError, type ServerFn, type ServerFnContext, type ServerFnDeclaredError, type ServerFnError, type ServerFnErrorDefinition, type ServerFnErrorDefinitions, type ServerFnErrorHandler, type ServerFnErrorSchema, ServerFnFailure, type ServerFnFormInput, type ServerFnHandler, type ServerFnHandlerContext, type ServerFnInvalidationContext, type ServerFnInvalidations, type ServerFnMCPMetadata, type ServerFnMiddleware, type ServerFnMiddlewareContext, type ServerFnMiddlewareContinuation, type ServerFnMiddlewareHandler, type ServerFnMiddlewareHandlerContext, type ServerFnMiddlewareNext, type ServerFnMiddlewareOptions, type ServerFnOptions, type ServerFnOutputOptions, type ServerFnSchema, type ServerFunctionDescriptor, type ServerFunctionInvocation, _attachServerFunctionDescriptor, _describeServerFunction, _invokeServerFunction, _parseServerFnSchema, _runServerFunctionForCaller, createServerFn, createServerFunctionDescriptor, createServerMiddleware };