@ductape/mcp 0.2.7 → 0.2.9

package/README.md

@@ -55,7 +55,7 @@ Use an absolute path for `args[0]`.
 
 ## Tools
 
-The server exposes **three tools**:
+The server exposes runtime, schema, documentation, CLI, discovery, migration, and setup tools. Core tools include:
 
 1. **`ductape_execute`**:
    - It runs any allowed SDK module method via the backend proxy.
@@ -82,6 +82,14 @@ The server exposes **three tools**:
      - ready-to-copy SDK snippet in `typescript` or `python`
    - Intended for engineers and copilots that need executable examples quickly.
 
+4. **`ductape_function_setup`**:
+   - Produces the secure local and remote setup for application functions referenced by portable Features.
+   - Requires an externally reachable HTTPS base URL (HTTP only for localhost development).
+   - Returns deterministic well-known routes, framework raw-body requirements, HMAC-SHA256 headers,
+     runtime verification steps, and fail-closed conditions.
+   - Agents must implement and verify the route; they must not claim remote availability from local registration alone.
+   - Agents must first extract native Ductape primitives from migrated code and reserve Functions for irreducible residual domain logic while preserving original transaction boundaries.
+
 The `ductape_cli` MCP tool also exposes public app discovery:
 `marketplace search <capability>`, `marketplace categories`, and
 `marketplace get <app_tag>`. Inspect the app before generating or executing an action payload.

package/dist/index.js

@@ -10,7 +10,7 @@
  * the env var when provided.
  */
 import { createRequire } from 'module';
-import { execSync } from 'child_process';
+import { execFileSync, execSync } from 'child_process';
 import { homedir } from 'os';
 import { delimiter, join } from 'path';
 import { z } from 'zod';
@@ -21,6 +21,60 @@ const MODULES = [
     'events', 'messageBrokers', 'storage', 'vector', 'caches', 'sessions', 'quotas',
     'actions', 'features', 'jobs', 'logs', 'resilience', 'health', 'fallback', 'secrets',
 ];
+const redisSetupInputSchema = z.object({
+    approved: z.boolean().describe('Must be true only after the user explicitly approves creating/starting a local Docker Redis container.'),
+    port: z.number().int().min(1024).max(65535).default(6379),
+    container_name: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9_.-]{0,62}$/).default('ductape-redis'),
+});
+const redisSetupHandler = async (args) => {
+    const port = args.port ?? 6379;
+    const name = args.container_name ?? 'ductape-redis';
+    if (!args.approved) {
+        return {
+            content: [{ type: 'text', text: [
+                        'Redis materially reduces repeated Ductape bootstrap latency and is required for dispatch().',
+                        'Ask the user whether they approve pulling redis:7-alpine and creating a local Docker container bound to 127.0.0.1.',
+                        'Only call this tool again with approved=true after explicit approval.',
+                    ].join('\n') }],
+            isError: true,
+        };
+    }
+    try {
+        execFileSync('docker', ['version', '--format', '{{.Server.Version}}'], { encoding: 'utf8', timeout: 15_000 });
+    }
+    catch {
+        return { content: [{ type: 'text', text: 'Docker is not installed or its daemon is unavailable. Install/start Docker, or supply a managed DUCTAPE_REDIS_URL.' }], isError: true };
+    }
+    let exists = false;
+    let running = false;
+    try {
+        exists = true;
+        running = execFileSync('docker', ['inspect', '-f', '{{.State.Running}}', name], { encoding: 'utf8', timeout: 10_000 }).trim() === 'true';
+    }
+    catch {
+        exists = false;
+    }
+    if (exists && !running)
+        execFileSync('docker', ['start', name], { encoding: 'utf8', timeout: 30_000 });
+    if (!exists) {
+        execFileSync('docker', [
+            'run', '-d', '--name', name, '--restart', 'unless-stopped',
+            '-p', `127.0.0.1:${port}:6379`, 'redis:7-alpine',
+            'redis-server', '--appendonly', 'yes',
+        ], { encoding: 'utf8', timeout: 120_000 });
+    }
+    execFileSync('docker', ['exec', name, 'redis-cli', 'ping'], { encoding: 'utf8', timeout: 10_000 });
+    return { content: [{ type: 'text', text: JSON.stringify({
+                    ready: true,
+                    container: name,
+                    redis_url: `redis://127.0.0.1:${port}`,
+                    next_steps: [
+                        `Set DUCTAPE_REDIS_URL=redis://127.0.0.1:${port}`,
+                        'Pass redisUrl to @ductape/nestjs or redis_url/redis_client to the installed SDK API as supported by its types.',
+                        'Add the variable to local .env only; do not commit credentials for managed Redis.',
+                    ],
+                }, null, 2) }] };
+};
 // ─── Exhaustive SDK Method & Params Reference ────────────────────────────────
 // Built from a complete read of sdk/ts/src/index.ts (Ductape class public API).
 // Each entry follows: [module].[method] → params array signature.
@@ -213,6 +267,10 @@ SETUP — register once in AppModule:
   ║                                                                          ║
   ║  *.run(), events.produce(), and @Events.Consumer do NOT need Redis.     ║
   ║  Only dispatch() does — and it is non-negotiable.                       ║
+  ║                                                                          ║
+  ║  Redis is STRONGLY RECOMMENDED even without dispatch(): every bootstrap ║
+  ║  domain uses memory + optional Redis caching, so shared/multi-process    ║
+  ║  deployments avoid repeating control-plane reads after warm-up.         ║
   ╚══════════════════════════════════════════════════════════════════════════╝
 
   import { DuctapeModule } from '@ductape/nestjs';
@@ -245,6 +303,10 @@ SETUP — register once in AppModule:
     DUCTAPE_REDIS_URL=redis://localhost:6379          # local dev
     DUCTAPE_REDIS_URL=rediss://:<password>@host:6380  # managed Redis (TLS)
 
+  If no Redis URL exists, proactively explain the latency/dispatch benefits and ask whether the
+  user wants a local Docker Redis dedicated to Ductape. After explicit approval, call
+  ductape_redis_setup({ approved: true }). Never pull an image or create/start a container before approval.
+
 INJECTING IN SERVICES AND CONTROLLERS — use @InjectContext():
 
   import { InjectContext, DuctapeContext } from '@ductape/nestjs';
@@ -773,11 +835,12 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
     queries?: { queryName: { handler?: function } },
     options?: { timeout?: number, retries?: number },
     envs?: [{ slug: string, active?: boolean }],
-    recordInput?: object,         // sample input for step-recording (run once during define)
+    recordInput?: object,         // exposed only as ctx.sampleInput while recording
     recordScenarios?: object[],   // multiple recording scenarios for branching
     branchOverrides?: object,     // force step results during recording to reach later branches
     handler: async (ctx) => {
-      // ctx.input                – typed feature input
+      // ctx.input                – typed runtime input; always compiles to $Input{} operators
+      // ctx.sampleInput          – compile-time sample for loop/branch discovery only
       // ctx.step(tag, fn, rollback?, opts?)  – define a durable step
       // ctx.api.run({ app, event, input }) – call an app action
       // ctx.database.query/insert/update/delete({ database, event, ... })
@@ -1115,6 +1178,7 @@ const ductape = new Ductape({
   workspace_id: process.env.DUCTAPE_WORKSPACE_ID!,
   user_id: process.env.DUCTAPE_USER_ID!,
   public_key: process.env.DUCTAPE_PUBLIC_KEY!,
+  redis_url: process.env.DUCTAPE_REDIS_URL,
 });
 
 async function run() {
@@ -1349,13 +1413,20 @@ const docsInputSchema = z.object({
     topic: z.string().describe('Feature topic to look up. Supported: ' +
         'transactions, presave, triggers, aggregations, migrations, indexes, performance, actions, ' +
         'graphs, storage, cloud, vector, warehouse, secrets, apps, products, sessions, caches, ' +
-        'notifications, resilience, features, events, logs, migration, frontend, frontend-analytics, client, react, vue'),
+        'notifications, resilience, features, portable-functions, events, logs, migration, frontend, frontend-analytics, client, react, vue'),
 });
 const eventsDiscoveryInputSchema = z.object({
     query: z.string().optional().describe('Capability or recovery search, including DLQ, dead letter, failed messages, retry, poison message, replay, or consumer failure.'),
     product: z.string().optional().describe('Product tag used for live component inspection.'),
     component: z.string().optional().describe('Events component/broker tag used for live inspection.'),
 });
+const portableFunctionSetupInputSchema = z.object({
+    framework: z.enum(['express', 'nestjs', 'fastify', 'other']).describe('Application HTTP framework.'),
+    base_url: z.string().url().describe('Externally reachable HTTPS origin. HTTP is accepted only for localhost development.'),
+    namespace: z.string().min(1).describe('Portable function namespace.'),
+    version: z.string().min(1).describe('Contract version.'),
+    operations: z.array(z.string().min(1)).min(1).describe('Operation names that must be registered and exposed.'),
+});
 const migrationInputSchema = z.object({
     source: z.string().describe('Absolute path to the existing codebase.'),
     e2e_baseline: z.string().describe('Absolute path to a passing migration-e2e baseline manifest created before migration inspection.'),
@@ -1371,6 +1442,96 @@ const migrationInputSchema = z.object({
     write: z.boolean().optional().default(false).describe('Write redacted advisory artifacts only. This never writes application code or executable Ductape assets.'),
 });
 const DOCS = {
+    'portable-functions': `
+PORTABLE APPLICATION FUNCTIONS
+
+Use portable functions when a Feature needs application-owned logic that cannot be expressed with
+database, action, Event, storage, graph, vector, session, quota, fallback, or transform primitives.
+
+PRIMITIVES-FIRST DECOMPOSITION — REQUIRED
+Before creating a Function, inspect the implementation, its callees, side effects, transaction
+boundary, configuration, and tests. Extract every operation already represented by a Ductape
+primitive. A Function is the residual application-owned behavior after that extraction; it is not
+a wrapper around an entire existing service method merely because that method already exists.
+
+Classify each observed behavior:
+  database read/write/transaction/index   → database primitive or database action
+  external provider/API                   → connected App action
+  publish/consume asynchronous message    → Events primitive
+  session creation/validation/revocation  → session primitive
+  file/blob operation                     → storage primitive
+  graph/vector operation                  → graph/vector primitive
+  email/SMS/push/chat delivery             → notification primitive
+  quota/fallback/health/cache              → corresponding Ductape primitive
+  multi-step product capability            → Feature orchestration
+  reusable domain decision/transformation  → portable Function candidate
+  formatting/hash/redaction with one caller→ ordinary utility unless portability is required
+
+For a mixed legacy method, split the boundary. Keep its irreducible domain decision in a Function
+and orchestrate extracted primitives as named Feature steps. Preserve atomicity: do not split a
+database transaction into independently committed steps unless the original contract permits it;
+use a database action or a Function with an explicitly authorized transactional capability instead.
+
+Every proposed Function must include evidence for:
+  - why no existing Ductape primitive expresses it;
+  - exact business input/output, errors, side effects, idempotency, and transaction semantics;
+  - whether it is pure and therefore a future signed-WASM candidate;
+  - why it needs local, Events, or HTTPS availability;
+  - which extracted primitives remain separate Feature steps.
+
+Non-negotiable rule: arbitrary JavaScript/TypeScript callbacks are not serializable. Never write
+ctx.step('x', () => applicationService.method()) and assume the method will run elsewhere. The
+Feature compiler must reject a step that records no portable operation.
+
+Canonical TypeScript pattern:
+  const AuthFunctions = defineFunctions({
+    namespace: 'statecraft-auth', version: '1',
+    operations: {
+      register: {
+        input: { type: 'object', required: ['email', 'password'], properties: {
+          email: { type: 'string' }, password: { type: 'string', minLength: 12 }
+        }, additionalProperties: false },
+        output: { type: 'object', required: ['token', 'player'], properties: {
+          token: { type: 'string' }, player: { type: 'object' }
+        } },
+        transports: [{ type: 'local' }],
+        handler: (input, context) => authService.register(input.email, input.password)
+      }
+    }
+  });
+  ductape.functions.register(AuthFunctions);
+  await ductape.feature.define({
+    tag: 'register-player', name: 'Register Player',
+    input: { email: { type: 'string', required: true }, password: { type: 'string', required: true } },
+    handler: async ctx => {
+      const auth = ctx.functions.use(AuthFunctions);
+      return ctx.step('register', () => auth.register({ email: ctx.input.email, password: ctx.input.password }));
+    }
+  });
+
+The compiled step stores namespace, operation, version, input/output JSON Schemas, timeout,
+idempotency declaration, and permitted transports. It never stores the handler or a sample result.
+
+Resolution order is local registered handler, then a contract-declared signed HTTP transport.
+HTTP function calls use Ductape HMAC-SHA256 headers. Raw arbitrary URLs and unsigned invocation are
+not supported. Application endpoints should use handlePortableFunctionHttpRequest and must receive
+the raw request body so signature verification covers exactly the bytes sent.
+
+The feature session is inherited automatically in invocation.context.session, not mixed into the
+business input. Invocation context also includes product, env, workspace_id, feature_id,
+feature_tag, step_tag, invocation_id, and deadline_at.
+
+Failure behavior is strict:
+  FUNCTION_UNAVAILABLE                 no local handler or configured HTTP transport
+  FUNCTION_SCHEMA_VALIDATION_FAILED    input or output violates the contract
+  FUNCTION_SIGNATURE_INVALID           HTTP signature is absent, invalid, or expired
+  FUNCTION_CORRELATION_MISMATCH         response invocation_id differs from request
+  FUNCTION_TIMEOUT                     operation exceeded its declared deadline
+
+Do not invent a function contract. Inspect the application's defineFunctions declarations and use
+the exact namespace, operation, version, schemas, and transports. If no contract exists, add one in
+application code and explicitly register its runtime implementation.
+`.trim(),
     migration: `
 DUCTAPE CODEBASE MIGRATION GUIDE
 
@@ -1405,6 +1566,39 @@ START
   5. Call again with write=true only after confirming the destination. This writes guidance artifacts only.
   6. Call with ensure_product=true when product inventory confirms the product is absent.
 
+PRIMITIVES-FIRST CAPABILITY EXTRACTION — REQUIRED FOR EVERY MIGRATION SLICE
+  Do not translate controllers, services, handlers, or exported functions one-for-one into Features
+  or portable Functions. For each candidate capability, trace entry points, callees, state changes,
+  external calls, errors, authorization, session usage, transactions, retries, and tests, then create
+  a decomposition ledger with these classifications:
+
+    DUCTAPE_PRIMITIVE       database, App action, Events, session, storage, graph, vector,
+                           notification, cache, quota, fallback, healthcheck, secret
+    FEATURE                user/product capability coordinating multiple meaningful operations
+    PORTABLE_FUNCTION      residual reusable domain logic that primitives cannot express
+    CHILD_FEATURE          independently meaningful capability with its own contract/lifecycle
+    UTILITY                local implementation detail with no independent product contract
+    INFRASTRUCTURE_ADAPTER framework/provider plumbing replaced by a Ductape primitive
+
+  The required order is:
+    1. Extract and inventory Ductape primitives from the existing implementation.
+    2. Establish the capability and transaction boundary from behavior and tests.
+    3. Design named Feature steps around those primitives.
+    4. Put only irreducible application-owned logic behind ctx.functions.
+    5. For each Function, record pure/WASM-candidate versus framework-dependent classification.
+    6. Call ductape_function_setup and implement verified local plus remote availability.
+
+  Never create a Function that merely hides database, session, Events, storage, notification, graph,
+  vector, quota, fallback, healthcheck, cache, secret, or connected-App work that the Feature can
+  express directly. Never fragment an original atomic transaction just to maximize primitive count.
+  A mixed method may legitimately become several primitive steps plus one small Function, one database
+  action, or one capability-scoped Function when atomicity requires co-location.
+
+  Before implementation, present a decomposition table with: source behavior, evidence location,
+  classification, selected Ductape primitive/function, input/output, side effects, transaction owner,
+  session behavior, failure semantics, and verification test. If the residual Function has no clear
+  reason to exist after primitive extraction, do not create it.
+
 FINAL E2E ACCEPTANCE GATE
   End the migration by running the exact original E2E command against the migrated codebase while retaining
   the original checksum-bound suite. Do not silently edit, delete, skip, quarantine, or weaken baseline tests.
@@ -3284,7 +3478,8 @@ STEP 2 — INVENTORY existing Ductape components
 STEP 3 — PLAN each step
   For every logical step:
     a. Identify whether it is local domain logic, a child Feature, or an existing Ductape component.
-       Local typed domain logic may run inside ctx.step; it does not require an Event or App.
+       Application-owned logic must be a registered portable function called through ctx.functions.
+       A plain callback that calls an application service is not serializable and must fail compilation.
        If a step calls an external service, it MUST go through a registered Ductape App.
        If no App for that service exists in the product → mark it "App to create: <service name>".
        DO NOT plan a raw HTTP call, a direct dispatch to a URL, or any workaround in place of a missing App.
@@ -3292,6 +3487,14 @@ STEP 3 — PLAN each step
     c. Decide if a rollback handler is needed (e.g. charge → refund on later failure).
        Rollback is optional and is not a Feature qualification requirement.
     d. Decide allow_fail: true for non-critical steps (email, analytics, audit logs)
+    e. If the step needs application-owned code, search the repository for an existing
+       defineFunctions contract and runtime registration. If none exists, design the exact contract.
+       Then ALWAYS call ductape_function_setup with the detected framework, namespace, version,
+       operations, and intended external base URL. Proactively inspect deployment configuration to
+       discover that URL and implement both local registration and the signed HTTPS adapter. If no
+       deployable HTTPS origin exists, report that explicit blocker instead of stopping at a local-only
+       setup. Do not mark the function remotely available until the
+       well-known route is reachable and rejects an invalid signature with HTTP 401.
 
 STEP 4 — PRESENT the plan and get approval BEFORE writing any code or creating anything
   Show the user:
@@ -3329,7 +3532,7 @@ STEP 7 — HANDLE conditionals, loops, and branching (when applicable)
     → Add branchOverrides: { stepTag: { field: value } } so all branches are recorded
     → At runtime the executor evaluates the real result and skips or runs later steps accordingly
   Loop over input array:
-    → Add recordInput: { items: [{ id: "1" }, { id: "2" }] } so the loop runs during recording
+    → Add recordInput: { items: [{ id: "1" }, { id: "2" }] } and iterate ctx.sampleInput.items
     → Use unique step tags per iteration (e.g. "process-" + item.id)
   Switch/if-else on feature input values:
     → Add recordScenarios: [{ type: "a" }, { type: "b" }] — handler runs once per scenario
@@ -3344,7 +3547,7 @@ STEP 8 — SET rollbacks for reversible steps
       async (result) => ctx.api.run({ app: 'stripe', event: 'refund', input: { chargeId: result.id } })
     );
 
-Step types: local_domain | action | database | graph | notification | storage | produce | quota |
+Step types: function | action | database | graph | notification | storage | produce | quota |
   fallback | vector | child_feature | sleep | wait_for_signal | checkpoint
 
 Valid synchronous Feature candidates include generate-world, resolve-nation-turn,
@@ -3439,7 +3642,8 @@ When you call features.define({ handler }), the handler runs TWICE:
      This phase captures the step graph: which steps exist, their types, tags, and declared
      inputs/outputs. No real API calls, DB queries, or side effects occur.
      Arbitrary JS code OUTSIDE ctx.step() ALSO runs during recording — with proxy values.
-     For loops: use recordInput so the handler sees sample data and all iterations are recorded.
+     For loops: supply recordInput and iterate ctx.sampleInput so all iterations are recorded.
+     ctx.input is always the runtime operator surface and must never expose recordInput literals.
      For branches: use branchOverrides so each path is captured.
 
   2. EXECUTION PHASE (at runtime) — handler is called with a real ExecutionContext.
@@ -3450,10 +3654,12 @@ When you call features.define({ handler }), the handler runs TWICE:
   outer handler body. Code in the outer body runs during recording with proxy values and
   may behave unexpectedly (e.g. typeof proxy === 'object' is true but .someField is a proxy).
 
-  A ctx.step callback may call ordinary local domain functions and injected/application services
-  available to the registration scope. This is the normal shape for a synchronous capability such
-  as pricing, entitlement evaluation, route-capacity calculation, or turn resolution. Keep the
-  meaningful work inside ctx.step callbacks so recording does not execute it.
+  A ctx.step callback MUST NOT close over ordinary local domain functions or injected/application
+  services. Closures are not portable and compilation fails closed. Define application-owned logic
+  with defineFunctions, register its local runtime handler, and invoke it through ctx.functions.
+  The MCP workflow must also attempt secure remote availability: detect the framework and deployment
+  origin, install the signed well-known HTTPS adapter, and verify it. Local registration alone is
+  insufficient for a Feature intended to execute outside the application process.
 
   Use an Event when the operation genuinely crosses an asynchronous process/service boundary,
   needs broker delivery semantics, or must be consumed independently. Do not produce an Event merely
@@ -4429,6 +4635,59 @@ const docsHandler = async (args) => {
             : '';
     return { content: [{ type: 'text', text: doc + structured }] };
 };
+const portableFunctionSetupHandler = async (args) => {
+    const parsed = new URL(args.base_url);
+    const local = parsed.hostname === 'localhost' || parsed.hostname === '127.0.0.1' || parsed.hostname === '::1';
+    if (parsed.protocol !== 'https:' && !(local && parsed.protocol === 'http:')) {
+        return { content: [{ type: 'text', text: JSON.stringify({
+                        ok: false,
+                        error: 'FUNCTION_INSECURE_TRANSPORT',
+                        message: 'Use HTTPS for portable function endpoints. HTTP is allowed only for localhost development.',
+                    }, null, 2) }], isError: true };
+    }
+    const base = args.base_url.replace(/\/$/, '');
+    const routes = args.operations.map(operation => ({
+        operation,
+        url: `${base}/.well-known/ductape/functions/${encodeURIComponent(args.namespace)}/${encodeURIComponent(args.version)}/${encodeURIComponent(operation)}`,
+    }));
+    const adapter = args.framework === 'nestjs'
+        ? `Configure rawBody: true in NestFactory.create, then add a POST controller route at\n` +
+            `/.well-known/ductape/functions/:namespace/:version/:operation. Pass request.rawBody, headers,\n` +
+            `and params to handlePortableFunctionHttpRequest(..., process.env.DUCTAPE_ACCESS_KEY!).`
+        : args.framework === 'fastify'
+            ? `Register a raw-body plugin for only the well-known function route, then pass rawBody, headers,\nparams to handlePortableFunctionHttpRequest(..., process.env.DUCTAPE_ACCESS_KEY!).`
+            : args.framework === 'express'
+                ? `Mount express.raw({ type: 'application/json' }) before JSON parsing on the well-known function route,\nthen pass request.body, headers, and params to handlePortableFunctionHttpRequest(..., process.env.DUCTAPE_ACCESS_KEY!).`
+                : `Preserve the exact raw JSON request bytes and pass body, headers, and route params to\nhandlePortableFunctionHttpRequest(..., process.env.DUCTAPE_ACCESS_KEY!).`;
+    return { content: [{ type: 'text', text: JSON.stringify({
+                    ok: true,
+                    requiredActions: [
+                        'Prove that database, App, Events, session, storage, graph, vector, notification, cache, quota, fallback, healthcheck, and secret primitives were extracted before defining this residual application Function.',
+                        'Record whether the residual logic is pure/signed-WASM-capable or framework-dependent, including transaction and side-effect boundaries.',
+                        'Create or locate one defineFunctions contract with exact input/output JSON Schemas.',
+                        'Register handlers with ductape.functions.register during application startup.',
+                        `Set DUCTAPE_FUNCTION_BASE_URL=${JSON.stringify(base)} in the application runtime.`,
+                        'Mount the signed well-known HTTP adapter and preserve the exact raw body.',
+                        'Do not add bearer keys, access keys, static headers, or unsigned routes to Feature JSON.',
+                        'Verify invalid signatures receive HTTP 401 and missing handlers receive HTTP 503.',
+                        'Execute each operation and verify actual business state plus Feature/step processor records.',
+                    ],
+                    routes,
+                    adapter,
+                    security: {
+                        scheme: 'HMAC-SHA256',
+                        signedValue: '<timestamp>.<raw-request-body>',
+                        headers: ['X-Ductape-Invocation-Id', 'X-Ductape-Timestamp', 'X-Ductape-Signature', 'X-Ductape-Function'],
+                        replayToleranceMs: 300000,
+                        httpsRequired: !local,
+                    },
+                    stopConditions: [
+                        'Do not claim remote availability until the route is reachable from the intended executor.',
+                        'Do not compile a closure-only ctx.step; use ctx.functions.',
+                        'Do not fall back to sample output when a runtime is unavailable.',
+                    ],
+                }, null, 2) }] };
+};
 const cliInputSchema = z.object({
     command: z.string().describe('The ductape CLI command to run, without the leading "ductape" word. ' +
         'Examples: "products list", "products create --name \\"My Product\\" --tag my-product", ' +
@@ -4910,7 +5169,7 @@ async function main() {
                 'index strategy, operation types) that should be confirmed with the user first.\n\n' +
                 'Available topics: transactions, presave, triggers, aggregations, migrations, indexes, performance, actions, ' +
                 'graphs, storage, cloud, vector, warehouse, secrets, apps, products, sessions, caches, ' +
-                'notifications, resilience, features, events, logs, migration, frontend, frontend-analytics, client, react, vue',
+                'notifications, resilience, features, portable-functions, events, logs, migration, frontend, frontend-analytics, client, react, vue',
             inputSchema: docsInputSchema,
         }, docsHandler);
         server.registerTool('ductape_events_discover', {
@@ -4921,10 +5180,25 @@ async function main() {
                 'applications own transactional outboxes, domain rejection handling, and idempotent consumer mutations.',
             inputSchema: eventsDiscoveryInputSchema,
         }, eventsDiscoveryHandler);
+        server.registerTool('ductape_function_setup', {
+            title: 'Ductape Portable Function Setup',
+            description: 'Generate the mandatory secure local + remote runtime setup for application functions used by Features. ' +
+                'Use this only after a primitives-first decomposition proves residual application-owned logic remains. The result requires a registered local handler, ' +
+                'a deterministic HTTPS endpoint, raw-body HMAC verification, runtime checks, and fail-closed behavior.',
+            inputSchema: portableFunctionSetupInputSchema,
+        }, portableFunctionSetupHandler);
+        server.registerTool('ductape_redis_setup', {
+            title: 'Ductape Local Redis Setup',
+            description: 'Provision or start an isolated local Redis container for Ductape bootstrap caching and dispatch queues. ' +
+                'First explain the latency benefit and ask for explicit approval. Never pass approved=true before the user agrees. ' +
+                'Uses redis:7-alpine, binds only to 127.0.0.1, enables append-only persistence, and returns the redis URL to wire into Ductape initialization.',
+            inputSchema: redisSetupInputSchema,
+        }, redisSetupHandler);
         server.registerTool('ductape_migration_plan', {
             title: 'Ductape AI Migration Guidance',
             description: 'Inspect a TypeScript, Go, Java, or .NET repository without exposing secret values. ' +
                 'Builds a relevant-file review queue, secret-name inventory, checksummed migration evidence, and low-confidence navigation hints. ' +
+                'Migration review must extract Ductape primitives before classifying residual domain logic as portable Functions. ' +
                 'The review standards classify capability candidates as FEATURE, FEATURE_STEP, DOMAIN_SERVICE, UTILITY, or INFRASTRUCTURE_ADAPTER; ' +
                 'they inspect exports, public methods, entry points, consumers, jobs, repeated orchestration, typed operations, routes, and product terminology. ' +
                 'Synchronous local multi-step capabilities may be Features, while related low-level functions must be grouped rather than promoted one-by-one. ' +
@@ -5046,6 +5320,8 @@ async function main() {
         server.tool('ductape_schema', schemaInputSchema.shape, schemaHandler);
         server.tool('ductape_docs', docsInputSchema.shape, docsHandler);
         server.tool('ductape_events_discover', eventsDiscoveryInputSchema.shape, eventsDiscoveryHandler);
+        server.tool('ductape_function_setup', portableFunctionSetupInputSchema.shape, portableFunctionSetupHandler);
+        server.tool('ductape_redis_setup', redisSetupInputSchema.shape, redisSetupHandler);
         server.tool('ductape_migration_plan', migrationInputSchema.shape, migrationHandler);
         server.tool('ductape_cli', cliInputSchema.shape, cliHandler);
     }

package/dist/proxy-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"proxy-client.d.ts","sourceRoot":"","sources":["../src/proxy-client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,eAAO,MAAM,YAAY,4BAA4B,CAAC;AAEtD,MAAM,MAAM,SAAS,GACjB,SAAS,GACT,KAAK,GACL,WAAW,GACX,OAAO,GACP,UAAU,GACV,eAAe,GACf,gBAAgB,GAChB,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,UAAU,GACV,QAAQ,GACR,SAAS,GACT,UAAU,GACV,MAAM,GACN,MAAM,GACN,YAAY,GACZ,QAAQ,GACR,UAAU,GACV,SAAS,CAAC;AAUd;;GAEG;AACH,wBAAsB,eAAe,CAAC,CAAC,GAAG,OAAO,EAC/C,eAAe,EAAE,MAAM,EACvB,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,OAAO,EAAO,GACrB,OAAO,CAAC,CAAC,CAAC,CAuBZ;AAED,MAAM,WAAW,iCAAiC;IAChD,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAC;IACpD,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,WAAW,CAAC,EAAE,QAAQ,GAAG,aAAa,CAAC;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,kCAAkC;IACjD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AASD,wBAAsB,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAuBxF;AA4BD,wBAAsB,yBAAyB,CAAC,CAAC,GAAG,kCAAkC,EACpF,OAAO,EAAE,iCAAiC,GACzC,OAAO,CAAC,CAAC,CAAC,CAiCZ"}
+{"version":3,"file":"proxy-client.d.ts","sourceRoot":"","sources":["../src/proxy-client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,eAAO,MAAM,YAAY,4BAA4B,CAAC;AAEtD,MAAM,MAAM,SAAS,GACjB,SAAS,GACT,KAAK,GACL,WAAW,GACX,OAAO,GACP,UAAU,GACV,eAAe,GACf,gBAAgB,GAChB,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,UAAU,GACV,QAAQ,GACR,SAAS,GACT,UAAU,GACV,MAAM,GACN,MAAM,GACN,YAAY,GACZ,QAAQ,GACR,UAAU,GACV,SAAS,CAAC;AAUd;;GAEG;AACH,wBAAsB,eAAe,CAAC,CAAC,GAAG,OAAO,EAC/C,eAAe,EAAE,MAAM,EACvB,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,OAAO,EAAO,GACrB,OAAO,CAAC,CAAC,CAAC,CAuBZ;AAED,MAAM,WAAW,iCAAiC;IAChD,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAC;IACpD,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,WAAW,CAAC,EAAE,QAAQ,GAAG,aAAa,CAAC;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,kCAAkC;IACjD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AA4BD,wBAAsB,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAoGxF;AA4BD,wBAAsB,yBAAyB,CAAC,CAAC,GAAG,kCAAkC,EACpF,OAAO,EAAE,iCAAiC,GACzC,OAAO,CAAC,CAAC,CAAC,CAiCZ"}

package/dist/proxy-client.js

@@ -28,28 +28,113 @@ export async function executeViaProxy(publishable_key, module, method, params =
     }
     return body.data?.data;
 }
+async function readJsonResponse(res, label) {
+    const contentType = res.headers.get('content-type')?.toLowerCase() ?? '';
+    if (!contentType.includes('json')) {
+        const responseText = await res.text();
+        const preview = responseText.replace(/\s+/g, ' ').trim().slice(0, 160);
+        throw new Error(`${label}: HTTP ${res.status} returned ${contentType || 'an unknown content type'}` +
+            (preview ? ` (${preview})` : ''));
+    }
+    try {
+        return await res.json();
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`${label}: HTTP ${res.status} returned invalid JSON (${detail})`);
+    }
+}
 export async function getAssetSchemas(module, method) {
     const path = module
         ? `/proxy/v1/schema/${encodeURIComponent(module)}${method ? `/${encodeURIComponent(method)}` : ''}`
         : '/proxy/v1/schema';
     const url = `${API_BASE_URL.replace(/\/$/, '')}${path}`;
     const res = await fetch(url);
-    const body = (await res.json());
     if (res.status === 404 && module && method) {
         const fallbackUrl = `${API_BASE_URL.replace(/\/$/, '')}/proxy/v1/schema/${encodeURIComponent(module)}`;
         const fallbackRes = await fetch(fallbackUrl);
-        const fallbackBody = (await fallbackRes.json());
-        const methodSchema = fallbackBody.data?.methods?.[method];
-        if (fallbackRes.ok && methodSchema) {
-            return { module, method, schema: methodSchema };
+        const fallbackBody = await readJsonResponse(fallbackRes, `Module schema fallback for ${module}.${method}`);
+        if (!fallbackRes.ok) {
+            throw new Error(fallbackBody.message ?? `Schema fallback request failed: ${fallbackRes.status}`);
+        }
+        if (typeof fallbackBody.status === 'boolean' && !fallbackBody.status) {
+            throw new Error(fallbackBody.message ?? 'Schema fallback fetch failed');
         }
+        const methods = fallbackBody.data?.method_schemas ?? fallbackBody.data?.methods;
+        const hasExactMethod = methods !== null && typeof methods === 'object' &&
+            !Array.isArray(methods) &&
+            Object.prototype.hasOwnProperty.call(methods, method);
+        const methodSchema = hasExactMethod ? methods[method] : undefined;
+        if (methodSchema !== null && typeof methodSchema === 'object') {
+            return {
+                module,
+                method,
+                schema: methodSchema,
+                resolution: {
+                    exact: true,
+                    source: fallbackBody.data?.method_schemas ? 'module.method_schemas' : 'module.methods',
+                    targeted_route_status: res.status,
+                    lookup_path: fallbackBody.data?.method_schemas
+                        ? `data.method_schemas[${JSON.stringify(method)}]`
+                        : `data.methods[${JSON.stringify(method)}]`,
+                },
+            };
+        }
+        if (Array.isArray(fallbackBody.data?.methods)) {
+            const rootUrl = `${API_BASE_URL.replace(/\/$/, '')}/proxy/v1/schema`;
+            const rootRes = await fetch(rootUrl);
+            const rootBody = await readJsonResponse(rootRes, `Root schema fallback for ${module}.${method}`);
+            if (!rootRes.ok) {
+                throw new Error(rootBody.message ?? `Root schema fallback request failed: ${rootRes.status}`);
+            }
+            if (typeof rootBody.status === 'boolean' && !rootBody.status) {
+                throw new Error(rootBody.message ?? 'Root schema fallback fetch failed');
+            }
+            const moduleSchemas = rootBody.data?.modules?.[module];
+            const hasRootMethod = moduleSchemas !== null && typeof moduleSchemas === 'object' &&
+                !Array.isArray(moduleSchemas) &&
+                Object.prototype.hasOwnProperty.call(moduleSchemas, method);
+            const rootMethodSchema = hasRootMethod ? moduleSchemas[method] : undefined;
+            if (rootMethodSchema !== null && typeof rootMethodSchema === 'object') {
+                return {
+                    module,
+                    method,
+                    schema: rootMethodSchema,
+                    resolution: {
+                        exact: true,
+                        source: 'root.modules',
+                        targeted_route_status: res.status,
+                        lookup_path: `data.modules[${JSON.stringify(module)}][${JSON.stringify(method)}]`,
+                    },
+                };
+            }
+        }
+        throw new Error(hasExactMethod
+            ? `Schema method "${method}" in the ${module} module schema is malformed`
+            : `Schema method "${method}" was not found in the ${module} module schema`);
     }
+    const body = await readJsonResponse(res, 'Schema request');
     if (!res.ok) {
         throw new Error(body.message ?? `Schema request failed: ${res.status}`);
     }
     if (typeof body.status === 'boolean' && !body.status) {
         throw new Error(body.message ?? 'Schema fetch failed');
     }
+    if (module && method) {
+        if (body.data === null || typeof body.data !== 'object') {
+            throw new Error(`Targeted schema response for ${module}.${method} is malformed`);
+        }
+        return {
+            module,
+            method,
+            schema: body.data,
+            resolution: {
+                exact: true,
+                source: 'targeted-route',
+                targeted_route_status: res.status,
+            },
+        };
+    }
     return body.data;
 }
 function normalizeTargets(targets) {

package/docs/TOOLS.md

@@ -1,6 +1,18 @@
 # MCP Tools Reference
 
-The Ductape MCP server exposes **one tool**. All operations go through the backend proxy; the list of allowed modules and methods is enforced by the proxy
+The Ductape MCP server exposes proxy, CLI, discovery, documentation, migration, and portable-function setup tools.
+
+## Tool: `ductape_function_setup`
+
+Produces the mandatory local registry and signed HTTPS exposure plan for portable application
+functions referenced by Features. The route is
+`/.well-known/ductape/functions/:namespace/:version/:operation` and requests use HMAC-SHA256.
+
+Call it only after a primitives-first migration review. Extract database, App, Events, session,
+storage, graph, vector, notification, cache, quota, fallback, healthcheck, and secret behavior into
+native Ductape primitives. A Function contains only the irreducible application-owned logic unless
+the original atomic transaction requires co-location. Classify that residual logic as pure and
+future-WASM-capable or framework-dependent.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ductape/mcp",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "description": "MCP server that exposes Ductape SDK operations via the backend proxy",
   "type": "module",
   "main": "dist/index.js",
@@ -15,7 +15,7 @@
   ],
   "scripts": {
     "build": "tsc",
-    "test": "npm run build && node scripts/check-frontend-analytics-guidance.mjs && node scripts/check-events-discovery.mjs",
+    "test": "npm run build && node scripts/check-frontend-analytics-guidance.mjs && node scripts/check-events-discovery.mjs && node scripts/check-schema-fallback.mjs && node scripts/check-portable-functions.mjs",
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts"
   },