@ductape/mcp 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased
+
+- Broadened Feature guidance from durable/event-driven workflows to synchronous or asynchronous named product capabilities.
+- Added evidence-backed `FEATURE`, `FEATURE_STEP`, `DOMAIN_SERVICE`, `UTILITY`, and `INFRASTRUCTURE_ADAPTER` classification guidance.
+- Added synchronous multi-step examples and repository discovery/grouping rules.
+
 ## 0.2.0 - 2026-07-26
 
 - Added exhaustive AI-led migration guidance for TypeScript, Go, Java, and .NET.

package/README.md

@@ -2,7 +2,7 @@
 
 Migration guidance is available from `ductape_docs({ topic: "migration" })`. It starts with an original E2E
 baseline, defaults to a separate new codebase, requires contextual review and strict parity evidence, and ends
-against the unchanged original E2E suite. Administrative work uses `ductape_cli`; `ductape_execute` remains
+against the unchanged original E2E suite. Administrative work and marketplace discovery use `ductape_cli`; `ductape_execute` remains
 publishable-key runtime-only. MCP never accepts or forwards `DUCTAPE_ACCESS_KEY`.
 
 MCP (Model Context Protocol) server that exposes **Ductape SDK** operations as tools. All calls go through the **Ductape backend proxy** at a fixed URL; the SDK never runs in the MCP process. It is completely stateless; you provide your **Publishable Key** per execution.
@@ -82,6 +82,19 @@ The server exposes **three tools**:
      - ready-to-copy SDK snippet in `typescript` or `python`
    - Intended for engineers and copilots that need executable examples quickly.
 
+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.
+
+## Feature classification
+
+`ductape_docs({ topic: "features" })` treats a Feature as a named, reusable product capability
+with a stable input/output contract and a useful managed-execution boundary. Features may be
+synchronous and entirely local; Events, signals, schedules, waits, retries, and rollback are
+optional patterns. Repository analysis distinguishes `FEATURE`, `FEATURE_STEP`, `DOMAIN_SERVICE`,
+`UTILITY`, and `INFRASTRUCTURE_ADAPTER`, explains its evidence, and groups related low-level
+operations instead of turning every exported function into a Feature.
+
 ## Security
 
 - Passing the `publishable_key` on a per-request basis guarantees that each execution is isolated. This architecture safely supports deployments that multiplex multiple user connections in a single server thread (e.g., SSE), avoiding cross-tenant leakage.

package/dist/index.js

@@ -725,6 +725,10 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
 ━━━ MODULE: features ━━━
   Feature definitions are code-first. Use features.define in application source; do not call
   administrative create/update/delete methods through ductape_execute.
+  A Feature is a named, reusable product capability with a stable input/output contract that
+  benefits from managed execution, composition, observability, retries, versioning, policy
+  enforcement, or explicit execution steps. It may execute synchronously and entirely locally.
+  Signals, Events, schedules, waits, checkpoints, compensation, and rollback are optional patterns.
   features.fetch   [product_tag, feature_tag]
   features.fetchAll [product_tag]
 
@@ -1129,7 +1133,7 @@ const ADMIN_SUBCOMMANDS = [
     'profiles',
     'workspaces',
     'link', 'unlink', 'init',
-    'products', 'apps',
+    'products', 'apps', 'marketplace',
     'resources',
     'notifications',
     'events',
@@ -1436,9 +1440,12 @@ COMPONENT DECISIONS
   Databases/transactions → Ductape Database; brokers/queues → Events; object stores → Storage;
   SMTP/SMS/push/callbacks → Notifications; Redis/cache → Cache; Neo4j/Neptune/Arango/Memgraph → Graph;
   Pinecone/Qdrant/Weaviate/OpenSearch → Vector; JWT/session middleware → Sessions.
-  Multi-step durable/scheduled/signal-driven work → code-first Features.
+  Named reusable product capabilities with a stable managed-execution boundary → code-first Features,
+  including synchronous multi-step capabilities and durable/scheduled/signal-driven orchestration.
   Retries, health checks, fallbacks, quotas, circuit breakers → Resilience.
-  Keep deterministic calculations, validation, domain rules, and ordinary synchronous services as code.
+  Keep low-level deterministic rules as ordinary domain functions when they do not form a useful
+  independent capability boundary. Wrap or compose them into Features when the combined operation
+  represents a reusable product capability.
 
 LANGUAGE RUNTIME SHAPES
   TypeScript: @ductape/sdk; NestJS uses @ductape/nestjs, @Events.Consumer, and request-scoped context.
@@ -1474,7 +1481,8 @@ AI EDITING STANDARD
   Compilation and happy-path tests alone do not demonstrate parity. Use existing tests, characterization
   tests, contract tests, integration tests, failure injection, and snd smoke tests appropriate to the slice.
   If parity cannot be demonstrated, stop short of cutover and report the exact unverified behavior.
-  Use Events for internal async boundaries and Apps/Actions for external APIs. Keep deterministic rules in code.
+  Use Events for internal async boundaries and Apps/Actions for external APIs. Keep low-level deterministic
+  rules in code, while allowing a coherent synchronous capability composed from those rules to be a Feature.
   Immediate work propagates the full session; durable work uses approved actor metadata or system context.
   Consumers are idempotent, retry ownership is singular and bounded, and external effects are not duplicated.
   After each slice: format, build, test, rescan, reconcile assets through ductape_cli, smoke-test in snd,
@@ -1550,6 +1558,10 @@ AUDITABLE REVIEW LEDGER
     ductape_cli("migration-review validate --ledger <path>/review-ledger.json --json")
   Before proposing cutover, require strict validation:
     ductape_cli("migration-review validate --ledger <path>/review-ledger.json --strict --json")
+
+  Before writing SDK integration code, query the exact supported language/version catalog:
+    ductape_cli("migration-capabilities --language <typescript|go|java|dotnet> --version <exact-version> --json")
+  The catalog is source-evidenced but does not replace inspection of the package actually installed in the target.
   Strict readiness requires no pending or stale files, reasoned exclusions, complete follow-ups,
   covered internal references, recorded file purpose, and verified or reasoned-not-applicable
   interface/functional/operational parity.
@@ -1627,6 +1639,18 @@ DEPENDENCY-AWARE LARGE-REPOSITORY PROPOSAL
   Verification-matrix records may declare details.depends_on using category.requirement identifiers. A stale
   cited dependency transitively invalidates dependent service/package summaries and readiness.
 
+MIGRATION ARTIFACT SAFETY
+  Migration JSON is size-limited, secret-material scanned, version checked, and written through exclusive
+  locks plus atomic rename. Mutating manifests retain a recoverable .bak copy. Validate or recover locally:
+    ductape_cli("migration-artifact validate --file <artifact.json> --json")
+    ductape_cli("migration-artifact recover --file <artifact.json> --json")
+  Controlled legacy upgrades never rewrite the source artifact:
+    ductape_cli("migration-artifact migrate --file <legacy.json> --output <v1.json> --json")
+  Inspect the machine-readable schema catalog:
+    ductape_cli("migration-artifact schemas --json")
+  Errors include stable codes such as ARTIFACT_TOO_LARGE, ARTIFACT_SECRET_MATERIAL, ARTIFACT_LOCKED,
+  ARTIFACT_VERSION_UNSUPPORTED, and ARTIFACT_RECOVERY_FAILED. Never bypass these checks with direct JSON edits.
+
 PARITY-GATED MIGRATION SLICES
   Create a JSON array containing the reviewed repository-relative files for one vertical slice, then:
     ductape_cli("migration-slice init --ledger <ledger> --tag <tag> --name <name> --files <files.json> --json")
@@ -2277,6 +2301,18 @@ An App must be fully set up in Ductape before any code can use it:
   4. Action endpoints must be defined (each action = one HTTP endpoint spec: method, path, body/query/header shape, response shape)
   5. The App must be connected to the product (product.apps.add) and its envs mapped
 
+DISCOVER BEFORE CREATING:
+  ductape_cli("marketplace search payments --json")
+  ductape_cli("marketplace search paystack --json")
+  ductape_cli("marketplace categories --json")
+  ductape_cli("marketplace get <app_tag> --json")
+
+marketplace search matches capability terms against public app names, tags, descriptions,
+categories, actions, and webhooks. marketplace get returns the complete public app definition,
+including the exact current-version action tags and body/query/header/param schemas. Never infer
+Paystack action names such as "initialize" or "verify": inspect the marketplace record first.
+If no suitable app exists, create one or import Paystack's OpenAPI/Postman definition.
+
 ONLY after all five steps can any code call:
   ctx.api.run({ app: '<app_tag>', event: '<action_tag>', input: { ... } })   ← in a feature handler
   actions.run([{ product, env, app: '<app_tag>', action: '<action_tag>', input }])   ← at runtime
@@ -2339,6 +2375,22 @@ Run an action at runtime:
   ductape_execute("actions.run", [{ product, env, app, action, input: { "body:field": value } }])
   ductape_execute("actions.dispatch", [{ product, env, app, action, input, schedule? }])
 
+In a Ductape feature handler, call the registered action through:
+  await ctx.api.run({ app: "<app_tag>", event: "<action_tag>", input: { ... } })
+ctx.api is the supported feature-context surface (also described as ctx.action in older code).
+There is no ctx.apps, ctx.integrations, or generic external-HTTP feature surface.
+
+PAYSTACK CONFIGURATION:
+  - Store the secret key as a workspace secret such as PAYSTACK_SECRET_KEY.
+  - Reference it from app auth as: Authorization = "Bearer $Secret{PAYSTACK_SECRET_KEY}".
+  - Never place the key in feature input, source code, logs, or marketplace app metadata.
+  - Initialization and verification are raw app actions unless the inspected app explicitly
+    publishes a higher-level contract. Ductape has no universal application payment abstraction.
+  - Model inbound events as app webhook events. Verify x-paystack-signature against the raw
+    request body using HMAC-SHA512 and PAYSTACK_SECRET_KEY before processing.
+  - Acknowledge quickly, process asynchronously, deduplicate by event/reference, and verify the
+    transaction through the inspected verification action before granting value.
+
 Auth schemes (how the app authenticates outbound requests):
   Setup types: header | bearer | basic | oauth2 | apikey
   Configure auth in Workbench (administrative).
@@ -2995,9 +3047,90 @@ PAYLOAD RECIPES
     features: `
 DUCTAPE FEATURES
 
-A feature is an orchestrated workflow of durable steps. Steps can call app actions, database
-operations, graph queries, storage uploads, notifications, broker publishes, child features,
-quotas, fallbacks, and more. Features support rollback, signals, checkpoints, and sleep.
+A Feature is a named, reusable product capability with a stable input/output contract that
+benefits from managed execution, composition, observability, retries, versioning, policy
+enforcement, or explicit execution steps.
+
+A Feature may be synchronous or asynchronous and may be entirely local. Signals, Events, waits,
+schedules, checkpoints, retries, compensation, and rollback are optional capabilities—not
+prerequisites. Asynchronous behavior is not the primary definition of a Feature.
+
+Common Feature patterns:
+  - synchronous capability
+  - multi-step computation
+  - event-driven orchestration
+  - signal-driven human workflow
+  - scheduled capability
+  - parent/child Feature composition
+
+━━━ CAPABILITY CLASSIFICATION — explain the evidence for every classification ━━━
+
+Use exactly these categories while reviewing application code:
+  FEATURE
+    An independently meaningful product/domain capability with a useful managed-execution boundary.
+    Recommendation: "Make this a standalone Ductape Feature."
+  FEATURE_STEP
+    A meaningful stage inside a larger capability, but not a useful independent execution boundary.
+    Recommendation: "Expose this as a named ctx.step(...) inside another Feature."
+  DOMAIN_SERVICE
+    Reusable domain logic without a useful independent managed-execution boundary.
+    Recommendation: "Keep this as ordinary domain logic called by a Feature."
+  UTILITY
+    A low-level helper such as hashing, formatting, redaction, normalization, conversion, or a type guard.
+    Recommendation: "Keep this as a utility."
+  INFRASTRUCTURE_ADAPTER
+    Database, Event, HTTP, cache, storage, provider, transport, or framework integration code.
+    Recommendation: "Keep this as an infrastructure adapter."
+
+TypeScript export is only evidence of reuse. It is neither sufficient nor necessary for Feature
+classification. Never classify every exported function as a Feature.
+
+Evaluate a candidate by asking:
+  - Does it represent a recognizable product or domain capability?
+  - Does it have a coherent responsibility?
+  - Can it have a stable, typed input/output contract?
+  - Is it reused across entry points, services, or other Features?
+  - Would independent execution or composition be useful?
+  - Would execution history or step-level observability be valuable?
+  - Does it need explicit versioning, authorization, quotas, retries, or policy?
+  - Does it contain several meaningful stages?
+  - Would users or developers naturally name it as a product feature?
+A positive answer to several questions makes it a Feature candidate even when it is synchronous
+and local. No single answer is sufficient, and signals, Events, or long runtime are never required.
+
+Keep low-level deterministic rules as ordinary domain functions when they do not form a useful
+independent capability boundary. Wrap or compose them into Features when the combined operation
+represents a reusable product capability.
+
+When inspecting a TypeScript repository, examine:
+  exported functions; public service methods; controller entry points; Event consumers; scheduled
+  jobs; repeated orchestration sequences; domain operations reused in several locations; functions
+  with substantial typed inputs/outputs; functions composing several stages; and product terminology
+  in documentation and API routes. Do not restrict discovery to *.feature.ts or features.define calls.
+
+Group related low-level operations into one coherent capability candidate. For example,
+resolveNationOrders, applyProvinceStockpileProduction, applyProvinceStockpileTransfers, and
+resolveFormationCommands may collectively suggest resolve-match-boundary or resolve-nation-turn.
+They must not automatically become four separate Features.
+
+For repository analysis, return a structured inventory for every recommendation:
+  {
+    "candidate": "resolve-nation-turn",
+    "classification": "FEATURE",
+    "executionStyle": "synchronous-multistep",
+    "evidence": [
+      "Represents a recognizable game capability",
+      "Has a stable input/output boundary",
+      "Composes validation, production, resolution, and reporting",
+      "Useful as an independently observable execution"
+    ],
+    "suggestedSteps": ["validate-orders", "apply-production", "resolve-orders", "build-reports"],
+    "signalsRequired": false,
+    "eventsRequired": false,
+    "recommendation": "Make this a standalone Ductape Feature."
+  }
+Every classification needs concrete code, caller, contract, or product-language evidence. If the
+boundary remains ambiguous, report both plausible categories and the missing evidence; do not guess.
 
 ━━━ AI DESIGN WORKFLOW — follow this process every time a user asks you to build or plan a feature ━━━
 
@@ -3033,12 +3166,14 @@ STEP 2 — INVENTORY existing Ductape components
 
 STEP 3 — PLAN each step
   For every logical step:
-    a. Identify which existing component handles it, or flag it as needing creation.
+    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.
        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.
     b. Note how inputs flow: ctx.input fields, or return values from earlier steps (plain JS variables — no special notation needed)
-    c. Decide if a rollback handler is needed (e.g. charge → refund on later failure)
+    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)
 
 STEP 4 — PRESENT the plan and get approval BEFORE writing any code or creating anything
@@ -3092,8 +3227,40 @@ STEP 8 — SET rollbacks for reversible steps
       async (result) => ctx.api.run({ app: 'stripe', event: 'refund', input: { chargeId: result.id } })
     );
 
-Step types: action | database | graph | notification | storage | produce | quota | fallback |
-  vector | child_feature | sleep | wait_for_signal | checkpoint
+Step types: local_domain | 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,
+calculate-route-capacity, price-subscription, evaluate-entitlement, and build-replay.
+
+Synchronous multi-step Feature (no Event, schedule, sleep, signal, or external system):
+  await ductape.features.define({
+    product: 'example-product',
+    tag: 'resolve-nation-turn',
+    name: 'Resolve Nation Turn',
+    input: {
+      nationId: { type: 'string', required: true },
+      tick: { type: 'number', required: true },
+    },
+    output: {
+      acceptedOrders: { type: 'number' },
+      rejectedOrders: { type: 'number' },
+    },
+    handler: async (ctx) => {
+      const validated = await ctx.step('validate-orders', async () => {
+        return validateOrders(ctx.input);
+      });
+      const resolved = await ctx.step('resolve-orders', async () => {
+        return resolveOrders(validated);
+      });
+      return ctx.step('build-result', async () => {
+        return buildResult(resolved);
+      });
+    },
+  });
+This is a valid Feature despite requiring no signal and producing no Event. Its qualification comes
+from the named capability, stable contract, meaningful stages, reuse/composition value, and useful
+step-level execution history.
 
 Define a feature (write this into the project's source files — do NOT use features.create):
   // src/features/onboard-user.ts  (or the equivalent path/language for the project)
@@ -3166,12 +3333,16 @@ 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).
 
-  Features do NOT execute arbitrary NestJS or server code directly. A feature handler can only
-  call Ductape component primitives (ctx.api, ctx.database, ctx.notification, etc.) as steps.
-  To invoke internal application business logic, produce a broker event from a feature step
-  (ctx.events.produce in the currently published SDK) and consume it in your NestJS service.
-  ctx.publish is deprecated; do not use it. Do not assume a ctx.messaging alias exists unless the
-  installed SDK types explicitly expose it.
+  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.
+
+  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
+  to reach local domain logic. When an Event is appropriate, use ctx.events.produce in the currently
+  published SDK and consume it in the NestJS service. ctx.publish is deprecated; do not use it.
+  Do not assume a ctx.messaging alias exists unless installed SDK types explicitly expose it.
 
 ━━━ ORCHESTRATION DECISION RULE ━━━
 
@@ -3181,7 +3352,10 @@ When you call features.define({ handler }), the handler runs TWICE:
       e.g. ductape.api.dispatch({ ..., schedule: { start_at: ... } })
       e.g. ductape.database.dispatch({ ..., schedule: { start_at: ... } })
 
-  Several durable Ductape component operations in sequence (with rollback / retry / state):
+  A named synchronous or asynchronous product capability with meaningful managed steps:
+    → define a Feature; execute it directly when immediate, or dispatch it when scheduled/background
+
+  Several durable Ductape component operations in sequence (with optional rollback / retry / state):
     → define a Feature, then features.dispatch to schedule it
 
   Invoke internal application business logic (your own NestJS/backend service code):
@@ -4204,13 +4378,7 @@ async function main() {
         const firstWord = args.command.trim().split(/\s+/)[0];
         const isAuthCommand = firstWord === 'login' || firstWord === 'logout';
         const isLocalMigrationGuidance = (firstWord === 'migrate-codebase' && !args.command.includes('--ensure-product')) ||
-            firstWord === 'migration-review' ||
-            firstWord === 'migration-slice' ||
-            firstWord === 'migration-portfolio' ||
-            firstWord === 'migration-database' ||
-            firstWord === 'migration-environments' ||
-            firstWord === 'migration-products' ||
-            firstWord === 'migration-secrets';
+            firstWord.startsWith('migration-');
         if (!isAuthCommand && !isLocalMigrationGuidance) {
             // Cache successful authentication, but re-check a missing/expired session on every call.
             // The user may complete `ductape login` in another terminal while this MCP process remains
@@ -4268,6 +4436,7 @@ async function main() {
                 isError: true,
             };
         }
+        const client = server.server?.getClientVersion?.();
         const command = [
             'migrate-codebase',
             '--source', shellArgument(args.source),
@@ -4282,6 +4451,9 @@ async function main() {
             ...(args.exclude.length ? ['--exclude', shellArgument(args.exclude.join(','))] : []),
             ...(args.ensure_product ? ['--ensure-product'] : []),
             ...(args.write ? ['--write'] : []),
+            ...(client?.name && client?.version
+                ? ['--mcp-client-name', shellArgument(client.name), '--mcp-client-version', shellArgument(client.version)]
+                : []),
             '--json',
         ].join(' ');
         return cliHandler({ command });
@@ -4480,6 +4652,10 @@ async function main() {
             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. ' +
+                '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. ' +
+                'Every recommendation must return classification, execution style, evidence, suggested steps, and whether signals or Events are actually required. ' +
                 'The AI must review files contextually and maintain an evidence ledger before proposing components or schemas. ' +
                 'It never generates or rewrites application code or executable assets. ' +
                 'Supports in-place and new-codebase guidance destinations. Read-only unless write or ensure_product is explicitly enabled.',

package/docs/TOOLS.md

@@ -4,6 +4,20 @@ The Ductape MCP server exposes **one tool**. All operations go through the backe
 
 ---
 
+## Marketplace discovery
+
+Use the `ductape_cli` tool before creating an integration or guessing action names:
+
+```text
+ductape_cli("marketplace search payments --json")
+ductape_cli("marketplace search paystack --json")
+ductape_cli("marketplace get <app_tag> --json")
+```
+
+The detail response is the authority for action tags and their body, query, header, and path
+inputs. After an app is connected to a product, call `ductape_generate_payload` for the selected
+action and then execute it through `actions.run`.
+
 ## Tool: `ductape_execute`
 
 Executes a Ductape SDK operation via the backend proxy. Use this for databases, graph, storage, vector, caches, webhooks, jobs, and all other supported modules.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ductape/mcp",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "MCP server that exposes Ductape SDK operations via the backend proxy",
   "type": "module",
   "main": "dist/index.js",