effortless-aws 0.33.1 → 0.35.0

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { StandardSchemaV1, StandardJSONSchemaV1 } from '@standard-schema/spec';
+
 /**
  * Configuration for an Effortless project.
  *
@@ -371,6 +373,10 @@ type BucketConfig = {
     suffix?: string;
     /** Typed JSON entity definitions for key-value storage */
     entities?: Record<string, BucketEntityConfig>;
+    /** Local directory to seed into bucket on deploy (only uploads files that don't already exist) */
+    seed?: string;
+    /** Local directory to sync into bucket on every deploy (uploads new/changed, deletes removed) */
+    sync?: string;
 };
 /**
  * S3 event record passed to onObjectCreated/onObjectRemoved callbacks.
@@ -417,7 +423,7 @@ type BucketObjectRemovedFn<C = undefined> = (args: {
  * Internal handler object created by defineBucket
  * @internal
  */
-type BucketHandler$1<C = any, Entities extends Record<string, any> = {}> = {
+type BucketHandler$1<C = any, _Entities extends Record<string, any> = {}> = {
     readonly __brand: "effortless-bucket";
     readonly __spec: BucketConfig;
     readonly onError?: (...args: any[]) => any;
@@ -435,6 +441,10 @@ type BucketOptions = {
     prefix?: string;
     /** S3 key suffix filter for event notifications (e.g., ".jpg") */
     suffix?: string;
+    /** Local directory to seed into bucket on deploy (only uploads files that don't already exist) */
+    seed?: string;
+    /** Local directory to sync into bucket on every deploy (uploads new/changed, deletes removed) */
+    sync?: string;
 };
 interface BucketBuilder<D = undefined, P = undefined, C = undefined, HasFiles extends boolean = false, Entities extends Record<string, any> = {}> {
     /** Declare handler dependencies */
@@ -720,7 +730,7 @@ type WorkerMessageFn<T, C = undefined> = (msg: T, ctx: SpreadCtx$4<C>) => Promis
  * Handler object created by defineWorker.
  * @internal
  */
-type WorkerHandler$1<T = any, C = any> = {
+type WorkerHandler$1<_T = any, C = any> = {
     readonly __brand: "effortless-worker";
     readonly __spec: WorkerConfig;
     readonly onError?: (...args: any[]) => any;
@@ -1384,6 +1394,7 @@ type RouteEntry = {
     method: HttpMethod;
     path: string;
     onRequest: (...args: any[]) => any;
+    schema?: unknown;
     public?: boolean;
     cache?: ResolvedCache;
 };
@@ -1391,23 +1402,24 @@ type RouteEntry = {
 type SpreadCtx$2<C> = ([C] extends [undefined] ? {} : Omit<C & {}, 'auth'>) & ([ExtractAuth<C>] extends [undefined] ? {} : {
     auth: AuthHelpers<ExtractAuth<C>>;
 });
+/** Infer validated output type from a Standard Schema, or fall back to unknown */
+type InferInput<S> = S extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<S> : unknown;
 /** Callback args available inside each route — ctx is spread into args */
-type RouteArgs<C, ST> = SpreadCtx$2<C> & {
+type RouteArgs<C, ST, S = undefined> = SpreadCtx$2<C> & {
     req: HttpRequest;
-    input: unknown;
+    input: InferInput<S>;
     ok: OkHelper;
     fail: FailHelper;
 } & ([ST] extends [true] ? {
     stream: ResponseStream;
 } : {});
 /** Route handler function */
-type RouteHandler<C, ST> = (args: RouteArgs<C, ST>) => Promise<HttpResponse | void> | HttpResponse | void;
-/** Route options for all methods */
-type RouteOptions = {
+type RouteHandler<C, ST, S = undefined> = (args: RouteArgs<C, ST, S>) => Promise<HttpResponse | void> | HttpResponse | void;
+/** Route definition — pass `input` for typed schema validation */
+type RouteDef<S extends StandardSchemaV1 | undefined = undefined> = {
+    path: `/${string}`;
+    input?: S;
     public?: boolean;
-};
-/** Route options for GET — supports caching */
-type GetRouteOptions = RouteOptions & {
     cache?: CacheOptions;
 };
 /** Setup factory — receives deps/config/files/enableAuth based on what was declared */
@@ -1459,11 +1471,11 @@ type ApiOptions = {
  * Has `__brand` so CLI discovers it. Each `.get()/.post()` adds a route and returns self.
  */
 interface ApiRoutes<C = undefined, ST extends boolean = false> extends ApiHandler<C> {
-    get(path: `/${string}`, handler: RouteHandler<C, ST>, options?: GetRouteOptions): ApiRoutes<C, ST>;
-    post(path: `/${string}`, handler: RouteHandler<C, ST>, options?: RouteOptions): ApiRoutes<C, ST>;
-    put(path: `/${string}`, handler: RouteHandler<C, ST>, options?: RouteOptions): ApiRoutes<C, ST>;
-    patch(path: `/${string}`, handler: RouteHandler<C, ST>, options?: RouteOptions): ApiRoutes<C, ST>;
-    delete(path: `/${string}`, handler: RouteHandler<C, ST>, options?: RouteOptions): ApiRoutes<C, ST>;
+    get<S extends StandardSchemaV1 | undefined = undefined>(def: RouteDef<S>, handler: RouteHandler<C, ST, S>): ApiRoutes<C, ST>;
+    post<S extends StandardSchemaV1 | undefined = undefined>(def: RouteDef<S>, handler: RouteHandler<C, ST, S>): ApiRoutes<C, ST>;
+    put<S extends StandardSchemaV1 | undefined = undefined>(def: RouteDef<S>, handler: RouteHandler<C, ST, S>): ApiRoutes<C, ST>;
+    patch<S extends StandardSchemaV1 | undefined = undefined>(def: RouteDef<S>, handler: RouteHandler<C, ST, S>): ApiRoutes<C, ST>;
+    delete<S extends StandardSchemaV1 | undefined = undefined>(def: RouteDef<S>, handler: RouteHandler<C, ST, S>): ApiRoutes<C, ST>;
 }
 /**
  * Builder interface for defining API handlers.
@@ -1493,16 +1505,11 @@ interface ApiBuilder<D = undefined, P = undefined, C = undefined, ST extends boo
     } & SpreadCtx$2<C>) => HttpResponse | Promise<HttpResponse>): ApiBuilder<D, P, C, ST, HasFiles>;
     /** Cleanup callback — runs after each invocation, before Lambda freezes */
     onCleanup(fn: (args: SpreadCtx$2<C>) => void | Promise<void>): ApiBuilder<D, P, C, ST, HasFiles>;
-    /** Add a GET route (terminal — returns finalized handler with route methods) */
-    get(path: `/${string}`, handler: RouteHandler<C, ST>, options?: GetRouteOptions): ApiRoutes<C, ST>;
-    /** Add a POST route (terminal) */
-    post(path: `/${string}`, handler: RouteHandler<C, ST>, options?: RouteOptions): ApiRoutes<C, ST>;
-    /** Add a PUT route (terminal) */
-    put(path: `/${string}`, handler: RouteHandler<C, ST>, options?: RouteOptions): ApiRoutes<C, ST>;
-    /** Add a PATCH route (terminal) */
-    patch(path: `/${string}`, handler: RouteHandler<C, ST>, options?: RouteOptions): ApiRoutes<C, ST>;
-    /** Add a DELETE route (terminal) */
-    delete(path: `/${string}`, handler: RouteHandler<C, ST>, options?: RouteOptions): ApiRoutes<C, ST>;
+    get<S extends StandardSchemaV1 | undefined = undefined>(def: RouteDef<S>, handler: RouteHandler<C, ST, S>): ApiRoutes<C, ST>;
+    post<S extends StandardSchemaV1 | undefined = undefined>(def: RouteDef<S>, handler: RouteHandler<C, ST, S>): ApiRoutes<C, ST>;
+    put<S extends StandardSchemaV1 | undefined = undefined>(def: RouteDef<S>, handler: RouteHandler<C, ST, S>): ApiRoutes<C, ST>;
+    patch<S extends StandardSchemaV1 | undefined = undefined>(def: RouteDef<S>, handler: RouteHandler<C, ST, S>): ApiRoutes<C, ST>;
+    delete<S extends StandardSchemaV1 | undefined = undefined>(def: RouteDef<S>, handler: RouteHandler<C, ST, S>): ApiRoutes<C, ST>;
 }
 /**
  * Define an API with typed routes using a builder pattern.
@@ -1519,8 +1526,8 @@ interface ApiBuilder<D = undefined, P = undefined, C = undefined, ST extends boo
  *     auth: enableAuth<Session>({ secret: config.dbUrl }),
  *   }))
  *   .onError(({ error, fail }) => fail(String(error), 500))
- *   .get("/me", async ({ users, auth, ok }) => ok(auth.session))
- *   .post("/login", async ({ auth, ok }) => ok(await auth.createSession()), { public: true })
+ *   .get({ path: "/me" }, async ({ users, auth, ok }) => ok(auth.session))
+ *   .post({ path: "/login", public: true }, async ({ auth, ok }) => ok(await auth.createSession()))
  * ```
  */
 declare function defineApi<const O extends ApiOptions>(options: O): ApiBuilder<undefined, undefined, undefined, O["stream"] extends true ? true : false, false>;
@@ -1649,6 +1656,8 @@ type McpConfig = {
     name: string;
     /** MCP server version (default: "1.0.0") */
     version?: string;
+    /** Human-readable description — sent to clients in initialize response as system prompt context */
+    instructions?: string;
     /** Lambda function settings (memory, timeout, permissions, etc.) */
     lambda?: LambdaWithPermissions;
 };
@@ -1679,17 +1688,133 @@ type McpToolResult = {
     content: McpToolContent[];
     isError?: boolean;
 };
-/** A single MCP tool definition */
-type McpToolDef<C = undefined> = {
+/** Content returned when reading a resource */
+type McpResourceContent = {
+    uri: string;
+    mimeType?: string;
+    text: string;
+} | {
+    uri: string;
+    mimeType?: string;
+    blob: string;
+};
+/** Legacy resource content result type used by runtime internals */
+type McpResourceResult = McpResourceContent | McpResourceContent[] | Promise<McpResourceContent | McpResourceContent[]>;
+/** Infer resource params type from schema, or fall back to Record<string, string> */
+type InferResourceParams<S> = S extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<S> : Record<string, string>;
+/** Resource definition — pass `params` for typed schema validation on URI template params */
+type McpResourceDefInput<S extends StandardSchemaV1 | undefined = undefined> = {
+    /** Resource URI or URI template (e.g. "resource://contacts/{id}") */
+    uri: string;
+    /** Human-readable name */
+    name: string;
+    /** Schema for URI template params — provides type inference + validation */
+    params?: S;
+    /** Optional description */
+    description?: string;
+    /** Optional MIME type */
+    mimeType?: string;
+};
+/** What resource handlers can return — plain data is auto-wrapped by the runtime */
+type McpResourceReturn = unknown | Promise<unknown>;
+/** Resource handler — receives params (typed or Record<string, string>) and ctx */
+type McpResourceHandler<C, S = undefined> = (params: InferResourceParams<S>, ctx: SpreadCtx<C>) => McpResourceReturn;
+/** @internal */
+type McpResourceDef$1<C = undefined> = {
+    name: string;
+    description?: string;
+    mimeType?: string;
+    handler: (ctx: SpreadCtx<C>) => McpResourceResult;
+};
+/** @internal */
+type McpResourceTemplateDef$1<C = undefined> = {
+    name: string;
+    description?: string;
+    mimeType?: string;
+    handler: (params: Record<string, string>, ctx: SpreadCtx<C>) => McpResourceResult;
+};
+/** @internal */
+type McpResourceMap$1<C = undefined> = {
+    [uriOrTemplate: string]: McpResourceDef$1<C> | McpResourceTemplateDef$1<C>;
+};
+/** An argument accepted by a prompt */
+type McpPromptArgument = {
+    /** Argument name */
+    name: string;
+    /** Optional description */
+    description?: string;
+    /** Whether the argument is required (default: false) */
+    required?: boolean;
+};
+/** Content block inside a prompt message */
+type McpPromptContent = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+} | {
+    type: "audio";
+    data: string;
+    mimeType: string;
+} | {
+    type: "resource";
+    resource: {
+        uri: string;
+        mimeType?: string;
+        text?: string;
+        blob?: string;
+    };
+};
+/** A single message returned by a prompt */
+type McpPromptMessage = {
+    role: "user" | "assistant";
+    content: McpPromptContent;
+};
+/** Result returned by a prompt handler */
+type McpPromptResult = {
+    description?: string;
+    messages: McpPromptMessage[];
+};
+/** @internal Legacy prompt definition used by runtime */
+type McpPromptDef$1<C = undefined> = {
+    description?: string;
+    arguments?: McpPromptArgument[];
+    handler: (args: Record<string, string>, ctx: SpreadCtx<C>) => McpPromptResult | Promise<McpPromptResult>;
+};
+/** Infer prompt args type from schema, or fall back to Record<string, string> */
+type InferPromptArgs<S> = S extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<S> : Record<string, string>;
+/** Prompt definition — pass a Standard Schema for `args` for typed validation, or McpPromptArgument[] for untyped */
+type McpPromptDefInput<S extends StandardSchemaV1 | McpPromptArgument[] | undefined = undefined> = {
+    /** Prompt name */
+    name: string;
+    /** Human-readable description */
+    description?: string;
+    /** Args: Standard Schema for typed validation, or McpPromptArgument[] for untyped */
+    args?: S;
+};
+/** Handler return: string auto-wraps as user message, or return full McpPromptResult */
+type McpPromptReturn = string | McpPromptResult | Promise<string | McpPromptResult>;
+/** Prompt handler — receives args (typed or Record<string, string>) and ctx */
+type McpPromptHandler<C, S = undefined> = (args: InferPromptArgs<S>, ctx: SpreadCtx<C>) => McpPromptReturn;
+/** Infer tool input type from schema, or fall back to any */
+type InferToolInput<S> = S extends StandardJSONSchemaV1 ? StandardJSONSchemaV1.InferOutput<S> : any;
+/** Tool definition — pass a StandardJSONSchemaV1 for `input` for typed validation, or McpInputSchema for raw JSON Schema */
+type McpToolDefInput<S extends StandardJSONSchemaV1 | McpInputSchema = McpInputSchema> = {
+    /** Tool name */
+    name: string;
     /** Human-readable description of the tool */
     description: string;
-    /** JSON Schema describing the tool's input parameters */
-    input: McpInputSchema;
-    /** Handler function called when the tool is invoked */
-    handler: (input: any, ctx: SpreadCtx<C>) => McpToolResult | Promise<McpToolResult>;
+    /** Schema for tool input: StandardJSONSchemaV1 (e.g. z.object({...})) or raw McpInputSchema */
+    input: S;
 };
-/** Setup factory — receives deps/config/files based on what was declared */
-type SetupArgs<D, P, HasFiles extends boolean> = ([D] extends [undefined] ? {} : {
+/** Tool handler — receives input (typed or any) and ctx */
+type McpToolHandler<C, S = McpInputSchema> = (input: InferToolInput<S>, ctx: SpreadCtx<C>) => unknown | Promise<unknown>;
+/** Setup factory — receives deps/config/files/enableAuth based on what was declared */
+type SetupArgs<D, P, HasFiles extends boolean> = {
+    enableAuth: EnableAuth;
+} & ([D] extends [undefined] ? {} : {
     deps: ResolveDeps<D>;
 }) & ([P] extends [undefined] ? {} : {
     config: ResolveConfig<P & {}>;
@@ -1711,14 +1836,30 @@ type McpHandler$1<C = any> = {
     readonly deps?: Record<string, unknown> | (() => Record<string, unknown>);
     readonly config?: Record<string, unknown>;
     readonly static?: string[];
+    readonly resources?: (...args: any[]) => any;
+    readonly prompts?: (...args: any[]) => any;
     readonly tools?: (...args: any[]) => any;
 };
+/**
+ * Finalized MCP handler with chainable registration methods.
+ * Has `__brand` so CLI discovers it. Each `.tool()/.resource()/.prompt()` adds an entry and returns self.
+ */
+interface McpEntries<C = undefined> extends McpHandler$1<C> {
+    /** Register a tool */
+    tool<S extends StandardJSONSchemaV1 | McpInputSchema = McpInputSchema>(def: McpToolDefInput<S>, handler: McpToolHandler<C, S>): McpEntries<C>;
+    /** Register a resource */
+    resource<S extends StandardSchemaV1 | undefined = undefined>(def: McpResourceDefInput<S>, handler: McpResourceHandler<C, S>): McpEntries<C>;
+    /** Register a prompt */
+    prompt<S extends StandardSchemaV1 | McpPromptArgument[] | undefined = undefined>(def: McpPromptDefInput<S>, handler: McpPromptHandler<C, S>): McpEntries<C>;
+}
 /** Options passed to `defineMcp()` */
 type McpOptions = {
     /** MCP server name (used in server info) */
     name: string;
     /** MCP server version (default: "1.0.0") */
     version?: string;
+    /** Human-readable description — sent to clients in initialize response as system prompt context */
+    instructions?: string;
 };
 interface McpBuilder<D = undefined, P = undefined, C = undefined, HasFiles extends boolean = false> {
     /** Declare handler dependencies (tables, queues, buckets, mailers, workers) */
@@ -1740,33 +1881,32 @@ interface McpBuilder<D = undefined, P = undefined, C = undefined, HasFiles exten
     } & SpreadCtx<C>) => void | Promise<void>): McpBuilder<D, P, C, HasFiles>;
     /** Cleanup callback — runs on shutdown */
     onCleanup(fn: (args: SpreadCtx<C>) => void | Promise<void>): McpBuilder<D, P, C, HasFiles>;
-    /** Define MCP tools (terminal) */
-    tools(fn: (ctx: SpreadCtx<C>) => Record<string, McpToolDef<C>>): McpHandler$1<C>;
+    /** Register a tool */
+    tool<S extends StandardJSONSchemaV1 | McpInputSchema = McpInputSchema>(def: McpToolDefInput<S>, handler: McpToolHandler<C, S>): McpEntries<C>;
+    /** Register a resource */
+    resource<S extends StandardSchemaV1 | undefined = undefined>(def: McpResourceDefInput<S>, handler: McpResourceHandler<C, S>): McpEntries<C>;
+    /** Register a prompt */
+    prompt<S extends StandardSchemaV1 | McpPromptArgument[] | undefined = undefined>(def: McpPromptDefInput<S>, handler: McpPromptHandler<C, S>): McpEntries<C>;
+    /** Finalize the handler without adding more entries */
+    build(): McpHandler$1<C>;
 }
 /**
  * Define an MCP (Model Context Protocol) server endpoint.
  *
- * Creates a Lambda-backed MCP server that exposes tools for AI models
- * and MCP-compatible clients to discover and invoke.
+ * Creates a Lambda-backed MCP server that exposes tools, resources, and prompts
+ * for AI models and MCP-compatible clients via Streamable HTTP (JSON-RPC over POST).
  *
- * @example
- * ```typescript
- * export const mcp = defineMcp({ name: "my-tools" })
- *   .deps(() => ({ users: usersTable }))
- *   .setup(({ deps }) => ({ db: deps.users }))
- *   .tools(({ db }) => ({
- *     get_user: {
- *       description: "Get a user by ID",
- *       input: { type: "object", properties: { id: { type: "string" } }, required: ["id"] },
- *       handler: async (input) => ({
- *         content: [{ type: "text", text: JSON.stringify(await db.get({ pk: input.id, sk: "profile" })) }]
- *       })
- *     }
- *   }))
- * ```
+ * @see https://modelcontextprotocol.io/specification/2025-03-26 — MCP specification
+ * @see https://effortless-aws.com/use-cases/mcp-server/ — full documentation with examples
  */
 declare function defineMcp(options: McpOptions): McpBuilder;
 
+type McpToolDef = McpToolDefInput;
+type McpResourceDef = McpResourceDef$1;
+type McpResourceTemplateDef = McpResourceTemplateDef$1;
+type McpResourceMap = McpResourceMap$1;
+type McpPromptDef = McpPromptDef$1;
+
 type TableHandler<T = Record<string, unknown>> = TableHandler$1<T, any>;
 type FifoQueueHandler<T = unknown> = FifoQueueHandler$1<T, any>;
 type BucketHandler<Entities extends Record<string, any> = {}> = BucketHandler$1<any, Entities>;
@@ -1774,4 +1914,4 @@ type CronHandler = CronHandler$1<any>;
 type WorkerHandler<T = any> = WorkerHandler$1<T, any>;
 type McpHandler = McpHandler$1<any>;
 
-export { type ApiAuthConfig, type ApiConfig, type ApiHandler, type ApiRoutes, type AppConfig, type AppHandler, type AuthHelpers, type BucketClient, type BucketClientWithEntities, type BucketConfig, type BucketEntityConfig, type BucketEvent, type BucketHandler, type BucketRouteConfig, type CacheOptions, type CdnPolicyOptions, type ConfigHelpers, type ContentType, type CronConfig, type CronHandler, type DefineSecretFn, type Duration, type EffortlessConfig, type EmailClient, type FifoQueueConfig, type FifoQueueHandler, type FifoQueueMessage, type HttpMethod$1 as HttpMethod, type HttpRequest, type HttpResponse, type LogLevel, type MailerConfig, type MailerHandler, type McpConfig, type McpHandler, type McpInputSchema, type McpToolContent, type McpToolDef, type McpToolResult, type MiddlewareDeny, type MiddlewareHandler, type MiddlewareRedirect, type MiddlewareRequest, type MiddlewareResult, type ParamRef, type Permission, type PutInput, type PutOptions, type QueryByTagParams, type QueryParams, type QueueClient, type ResponseStream, type SecretRef, type SendEmailOptions, type SendMessageInput, type SkCondition, type StaticFiles, type StaticSiteConfig, type StaticSiteHandler, type StaticSiteSeo, type StoreEntityClient, type StreamView, type TableClient, type TableConfig, type TableHandler, type TableItem, type TableKey, type TableRecord, type Timezone, type UpdateActions, type WorkerClient, type WorkerConfig, type WorkerHandler, type WorkerSendOptions, defineApi, defineApp, defineBucket, defineConfig, defineCron, defineFifoQueue, defineMailer, defineMcp, defineSecret, defineStaticSite, defineTable, defineWorker, generateBase64, generateHex, generateUuid, isBucketRoute, param, secret, toSeconds };
+export { type ApiAuthConfig, type ApiConfig, type ApiHandler, type ApiRoutes, type AppConfig, type AppHandler, type AuthHelpers, type BucketClient, type BucketClientWithEntities, type BucketConfig, type BucketEntityConfig, type BucketEvent, type BucketHandler, type BucketRouteConfig, type CacheOptions, type CdnPolicyOptions, type ConfigHelpers, type ContentType, type CronConfig, type CronHandler, type DefineSecretFn, type Duration, type EffortlessConfig, type EmailClient, type FifoQueueConfig, type FifoQueueHandler, type FifoQueueMessage, type HttpMethod$1 as HttpMethod, type HttpRequest, type HttpResponse, type LogLevel, type MailerConfig, type MailerHandler, type McpConfig, type McpEntries, type McpHandler, type McpInputSchema, type McpPromptArgument, type McpPromptContent, type McpPromptDef, type McpPromptMessage, type McpPromptResult, type McpResourceContent, type McpResourceDef, type McpResourceMap, type McpResourceTemplateDef, type McpToolContent, type McpToolDef, type McpToolResult, type MiddlewareDeny, type MiddlewareHandler, type MiddlewareRedirect, type MiddlewareRequest, type MiddlewareResult, type ParamRef, type Permission, type PutInput, type PutOptions, type QueryByTagParams, type QueryParams, type QueueClient, type ResponseStream, type SecretRef, type SendEmailOptions, type SendMessageInput, type SkCondition, type StaticFiles, type StaticSiteConfig, type StaticSiteHandler, type StaticSiteSeo, type StoreEntityClient, type StreamView, type TableClient, type TableConfig, type TableHandler, type TableItem, type TableKey, type TableRecord, type Timezone, type UpdateActions, type WorkerClient, type WorkerConfig, type WorkerHandler, type WorkerSendOptions, defineApi, defineApp, defineBucket, defineConfig, defineCron, defineFifoQueue, defineMailer, defineMcp, defineSecret, defineStaticSite, defineTable, defineWorker, generateBase64, generateHex, generateUuid, isBucketRoute, param, secret, toSeconds };

package/dist/index.js

@@ -301,13 +301,14 @@ function defineApi(options) {
     },
     routes: []
   };
-  const addRoute = (method, path, handler, opts) => {
-    const routeCache = opts?.cache != null ? resolveCache(opts.cache) : void 0;
+  const addRoute = (method, def, handler) => {
+    const routeCache = def.cache != null ? resolveCache(def.cache) : void 0;
     state.routes.push({
       method,
-      path,
+      path: def.path,
       onRequest: handler,
-      ...opts?.public ? { public: true } : {},
+      ...def.input ? { schema: def.input } : {},
+      ...def.public ? { public: true } : {},
       ...routeCache ? { cache: routeCache } : {}
     });
   };
@@ -329,8 +330,8 @@ function defineApi(options) {
       ...state.static ? { static: state.static } : {}
     };
     for (const m of ["get", "post", "put", "patch", "delete"]) {
-      handler[m] = (path, fn, opts) => {
-        addRoute(m.toUpperCase(), path, fn, opts);
+      handler[m] = (def, fn) => {
+        addRoute(m.toUpperCase(), def, fn);
         handler.routes = state.routes;
         return handler;
       };
@@ -367,24 +368,24 @@ function defineApi(options) {
       state.onCleanup = fn;
       return builder;
     },
-    get(path, handler, opts) {
-      addRoute("GET", path, handler, opts);
+    get(def, fn) {
+      addRoute("GET", def, fn);
       return finalize();
     },
-    post(path, handler, opts) {
-      addRoute("POST", path, handler, opts);
+    post(def, fn) {
+      addRoute("POST", def, fn);
       return finalize();
     },
-    put(path, handler, opts) {
-      addRoute("PUT", path, handler, opts);
+    put(def, fn) {
+      addRoute("PUT", def, fn);
       return finalize();
     },
-    patch(path, handler, opts) {
-      addRoute("PATCH", path, handler, opts);
+    patch(def, fn) {
+      addRoute("PATCH", def, fn);
       return finalize();
     },
-    delete(path, handler, opts) {
-      addRoute("DELETE", path, handler, opts);
+    delete(def, fn) {
+      addRoute("DELETE", def, fn);
       return finalize();
     }
   };
@@ -519,25 +520,57 @@ function defineWorker(options) {
 function defineMcp(options) {
   const spec = {
     name: options.name,
-    ...options.version ? { version: options.version } : {}
+    ...options.version ? { version: options.version } : {},
+    ...options.instructions ? { instructions: options.instructions } : {}
   };
-  const state = { spec };
+  const state = { spec, toolEntries: [], resourceEntries: [], promptEntries: [] };
   const applyLambdaOptions = (lambda) => {
     if (Object.keys(lambda).length > 0) {
       state.spec = { ...state.spec, lambda: { ...state.spec.lambda, ...lambda } };
     }
   };
-  const finalize = () => ({
-    __brand: "effortless-mcp",
-    __spec: state.spec,
-    ...state.onError ? { onError: state.onError } : {},
-    ...state.onCleanup ? { onCleanup: state.onCleanup } : {},
-    ...state.setup ? { setup: state.setup } : {},
-    ...state.deps ? { deps: state.deps } : {},
-    ...state.config ? { config: state.config } : {},
-    ...state.static ? { static: state.static } : {},
-    ...state.tools ? { tools: state.tools } : {}
-  });
+  const buildToolsFactory = () => state.toolEntries.length > 0 ? () => Object.fromEntries(state.toolEntries) : void 0;
+  const buildResourcesFactory = () => state.resourceEntries.length > 0 ? () => Object.fromEntries(state.resourceEntries) : void 0;
+  const buildPromptsFactory = () => state.promptEntries.length > 0 ? () => Object.fromEntries(state.promptEntries) : void 0;
+  const finalize = () => {
+    const tools = buildToolsFactory();
+    const resources = buildResourcesFactory();
+    const prompts = buildPromptsFactory();
+    return {
+      __brand: "effortless-mcp",
+      __spec: state.spec,
+      ...state.onError ? { onError: state.onError } : {},
+      ...state.onCleanup ? { onCleanup: state.onCleanup } : {},
+      ...state.setup ? { setup: state.setup } : {},
+      ...state.deps ? { deps: state.deps } : {},
+      ...state.config ? { config: state.config } : {},
+      ...state.static ? { static: state.static } : {},
+      ...resources ? { resources } : {},
+      ...prompts ? { prompts } : {},
+      ...tools ? { tools } : {}
+    };
+  };
+  const finalizeWithEntries = () => {
+    const handler = finalize();
+    handler.tool = (def, fn) => {
+      state.toolEntries.push([def.name, { description: def.description, input: def.input, handler: fn }]);
+      handler.tools = buildToolsFactory();
+      return handler;
+    };
+    handler.resource = (def, fn) => {
+      const entry = { name: def.name, ...def.description ? { description: def.description } : {}, ...def.mimeType ? { mimeType: def.mimeType } : {}, handler: fn, ...def.params ? { params: def.params } : {} };
+      state.resourceEntries.push([def.uri, entry]);
+      handler.resources = buildResourcesFactory();
+      return handler;
+    };
+    handler.prompt = (def, fn) => {
+      const entry = { ...def.description ? { description: def.description } : {}, args: def.args, handler: fn };
+      state.promptEntries.push([def.name, entry]);
+      handler.prompts = buildPromptsFactory();
+      return handler;
+    };
+    return handler;
+  };
   const builder = {
     deps(fn) {
       state.deps = fn;
@@ -568,8 +601,21 @@ function defineMcp(options) {
       state.onCleanup = fn;
       return builder;
     },
-    tools(fn) {
-      state.tools = fn;
+    tool(def, fn) {
+      state.toolEntries.push([def.name, { description: def.description, input: def.input, handler: fn }]);
+      return finalizeWithEntries();
+    },
+    resource(def, fn) {
+      const entry = { name: def.name, ...def.description ? { description: def.description } : {}, ...def.mimeType ? { mimeType: def.mimeType } : {}, handler: fn, ...def.params ? { params: def.params } : {} };
+      state.resourceEntries.push([def.uri, entry]);
+      return finalizeWithEntries();
+    },
+    prompt(def, fn) {
+      const entry = { ...def.description ? { description: def.description } : {}, args: def.args, handler: fn };
+      state.promptEntries.push([def.name, entry]);
+      return finalizeWithEntries();
+    },
+    build() {
       return finalize();
     }
   };