@ductape/mcp 0.2.12 → 0.2.14

package/CHANGELOG.md

@@ -6,6 +6,8 @@
 
 ## Unreleased
 
+- Added read-only `ductape_events_topic_setup` and `ductape_events_validate_project` tools and made the canonical one-topic-per-file `ductape/events/<topic-tag>.topic.json` layout explicit and enforceable through the CLI.
+- Mark `ductape_function_setup` as read-only, non-destructive, idempotent, and closed-world in both MCP registration APIs so hosts do not incorrectly require mutation approval for its pure setup-plan generation.
 - 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.

package/README.md

@@ -82,7 +82,12 @@ The server exposes runtime, schema, documentation, CLI, discovery, migration, an
      - ready-to-copy SDK snippet in `typescript` or `python`
    - Intended for engineers and copilots that need executable examples quickly.
 
-4. **`ductape_function_setup`**:
+4. **`ductape_events_topic_setup` / `ductape_events_validate_project`**:
+   - Generate one canonical `ductape/events/<topic-tag>.topic.json` asset shape without writing it.
+   - Validate filenames, one-object-per-file schemas, unique qualified tags, supported fields, and publisher references before provisioning.
+   - Aggregate topic catalogues, manifests, envelope registries, and custom event registries are rejected.
+
+5. **`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,

package/dist/index.js

@@ -630,8 +630,8 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   events.list     [product_tag]
   events.delete   [product_tag, broker_tag]
   events.topics.create  ← FORBIDDEN with publishable key. Use ductape_cli instead:
-    ductape_cli("events topics create -f topic.json")
-    topic.json: { tag: "broker-tag:topic-tag", name, description?, sample?, idempotent?, queueUrls?: [{ env_slug, url }] }
+    ductape_cli("events topics create -f ductape/events/<topic-tag>.topic.json")
+    One directly importable topic per file: { tag: "broker-tag:topic-tag", name, description?, sample?, idempotent?, queueUrls?: [{ env_slug, url }] }
   ← Always required before consuming. For SQS: must include queueUrls per env.
   ← For Pub/Sub, Kafka, RabbitMQ, Redis, NATS: the first produce call auto-registers the topic,
      but you should still create it explicitly so consumers can subscribe before any produce occurs.
@@ -1468,6 +1468,33 @@ const portableFunctionSetupInputSchema = z.object({
     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.'),
 });
+// This tool only derives setup instructions from its arguments. It performs no network request,
+// filesystem write, process launch, registration, deployment, or infrastructure provisioning.
+// Declare that explicitly so MCP hosts do not send it through mutation approval workflows.
+const portableFunctionSetupAnnotations = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+};
+const eventsTopicSetupInputSchema = z.object({
+    broker_tag: z.string().regex(/^[A-Za-z0-9]+(?:[-_][A-Za-z0-9]+)*$/).describe('Existing Ductape Events broker tag.'),
+    topic_tag: z.string().regex(/^[A-Za-z0-9]+(?:[-_][A-Za-z0-9]+)*$/).describe('Unqualified topic tag used as the canonical filename.'),
+    name: z.string().min(1),
+    description: z.string().optional(),
+    sample: z.record(z.unknown()).optional(),
+    idempotent: z.boolean().optional(),
+    queueUrls: z.array(z.object({ env_slug: z.string().min(1), url: z.string().url() }).strict()).optional(),
+});
+const eventsProjectValidationInputSchema = z.object({
+    dir: z.string().default('ductape/events').describe('Must be ductape/events relative to DUCTAPE_PROJECT_DIR.'),
+});
+const readOnlyLocalAnnotations = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+};
 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.'),
@@ -3854,10 +3881,28 @@ Import (register an EXISTING cloud resource):
   IMPORTANT: events.topics.create requires an access key (admin operation).
   Use ductape_cli — NOT ductape_execute — to create topics.
 
-  Write a topic.json file, then:
-    ductape_cli("events topics create -f topic.json")
-
-  topic.json schema:
+  CANONICAL ASSET CONTRACT — HARD REQUIREMENT:
+  Ductape topic assets are individual, directly importable files at
+    <project-root>/ductape/events/<topic-tag>.topic.json
+  Never replace them with an aggregate catalog, manifest, envelope registry, custom event registry,
+  or multi-topic JSON file. Exactly one topic definition is allowed per file. The filename uses the
+  unqualified topic portion: tag "order-events:order-created" must be stored as
+  ductape/events/order-created.topic.json.
+
+  Generate the exact path and body before writing a topic:
+    ductape_events_topic_setup({ broker_tag: "order-events", topic_tag: "order-created", name: "Order Created" })
+  Validate the complete repository before any remote mutation:
+    ductape_events_validate_project({ dir: "ductape/events" })
+  Or through the CLI:
+    ductape_cli("events topics validate --dir ductape/events --json")
+    ductape_cli("events topics create-all --dir ductape/events --json")
+
+  Create one topic directly from its canonical asset:
+    ductape_cli("events topics create -f ductape/events/order-created.topic.json --json")
+
+  Each *.topic.json file may contain ONLY tag, name, description, sample, idempotent, and the
+  currently supported provider-specific field queueUrls. Unknown custom fields are rejected.
+  Canonical topic file schema:
     {
       "tag": "order-events:order-created",  // ALWAYS "broker-tag:topic-tag" — full event string
       "name": "Order Created",
@@ -4729,6 +4774,48 @@ const portableFunctionSetupHandler = async (args) => {
                     ],
                 }, null, 2) }] };
 };
+const eventsTopicSetupHandler = async (args) => {
+    const tag = `${args.broker_tag}:${args.topic_tag}`;
+    const relativePath = `ductape/events/${args.topic_tag}.topic.json`;
+    const definition = {
+        tag,
+        name: args.name,
+        ...(args.description === undefined ? {} : { description: args.description }),
+        ...(args.sample === undefined ? {} : { sample: args.sample }),
+        ...(args.idempotent === undefined ? {} : { idempotent: args.idempotent }),
+        ...(args.queueUrls === undefined ? {} : { queueUrls: args.queueUrls }),
+    };
+    return {
+        content: [{ type: 'text', text: JSON.stringify({
+                    ok: true,
+                    project_root: cliCwd(),
+                    path: join(cliCwd(), relativePath),
+                    relative_path: relativePath,
+                    definition,
+                    create_command: `ductape events topics create -f ${relativePath} --json`,
+                    validate_command: 'ductape events topics validate --dir ductape/events --json',
+                    rules: [
+                        'Write exactly this one JSON object to the returned path.',
+                        'Do not create an aggregate topic catalogue, manifest, envelope registry, or multi-topic JSON file.',
+                        'Run project validation before creating any remote topic.',
+                    ],
+                }, null, 2) }],
+    };
+};
+const eventsProjectValidationHandler = async (args) => {
+    const dir = args.dir ?? 'ductape/events';
+    if (dir !== 'ductape/events') {
+        return {
+            content: [{ type: 'text', text: 'Events topic assets must use the canonical directory ductape/events; custom directories are forbidden.' }],
+            isError: true,
+        };
+    }
+    const result = runCli('events topics validate --dir ductape/events --json');
+    return {
+        content: [{ type: 'text', text: result.output || '(no output)' }],
+        ...(result.success ? {} : { isError: true }),
+    };
+};
 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", ' +
@@ -5221,12 +5308,29 @@ async function main() {
                 'applications own transactional outboxes, domain rejection handling, and idempotent consumer mutations.',
             inputSchema: eventsDiscoveryInputSchema,
         }, eventsDiscoveryHandler);
+        server.registerTool('ductape_events_topic_setup', {
+            title: 'Ductape Events Topic Setup',
+            description: 'Read-only generator for one canonical Ductape topic asset. Returns the required ' +
+                'ductape/events/<topic-tag>.topic.json path, its directly importable JSON object, and validation/create commands. ' +
+                'It does not write files or mutate remote resources.',
+            inputSchema: eventsTopicSetupInputSchema,
+            annotations: readOnlyLocalAnnotations,
+        }, eventsTopicSetupHandler);
+        server.registerTool('ductape_events_validate_project', {
+            title: 'Validate Ductape Events Project',
+            description: 'Read-only validation of canonical ductape/events/*.topic.json assets and statically discoverable publisher references. ' +
+                'Rejects aggregate catalogues, invalid filenames/shapes/tags, duplicates, unknown fields, and undefined published topics.',
+            inputSchema: eventsProjectValidationInputSchema,
+            annotations: readOnlyLocalAnnotations,
+        }, eventsProjectValidationHandler);
         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. ' +
+            description: 'Read-only: generate (without applying) the mandatory secure local + remote runtime setup for application functions used by Features. ' +
+                'This tool performs no network requests, writes, registrations, deployments, or infrastructure provisioning. ' +
                 '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,
+            annotations: portableFunctionSetupAnnotations,
         }, portableFunctionSetupHandler);
         server.registerTool('ductape_redis_setup', {
             title: 'Ductape Local Redis Setup',
@@ -5334,7 +5438,7 @@ async function main() {
                 '    GCP Pub/Sub service identifier is "pubsub". AWS SQS is "sqs". Azure Service Bus is "servicebus".\n' +
                 '    Message brokers are import-only (no provision-persist). Import flow is the same as storage.\n' +
                 '    type field = "messageBrokers" (not "messagebrokers" or "events").\n' +
-                '    After importing, create topics first with ductape_cli("events topics create -f topic.json") — SQS requires explicit topic creation with queueUrls. For other providers, topics auto-register on first produce but should still be created explicitly before any consumer subscribes.\n' +
+                '    After importing, create one topic per canonical ductape/events/<topic-tag>.topic.json file. First run "events topics validate --dir ductape/events --json", then use "events topics create-all --dir ductape/events --json" or create each file directly. SQS requires queueUrls. Aggregate topic catalogues are forbidden.\n' +
                 '  - Listing workspaces, products, focused product components, secrets\n' +
                 '    Prefer "products components list --product-tag <tag> --json" for compact inventory; use\n' +
                 '    "products components get --product-tag <tag> --type notifications|events|healthchecks|features --json" for focused detail.\n' +
@@ -5361,7 +5465,9 @@ 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_events_topic_setup', eventsTopicSetupInputSchema.shape, readOnlyLocalAnnotations, eventsTopicSetupHandler);
+        server.tool('ductape_events_validate_project', eventsProjectValidationInputSchema.shape, readOnlyLocalAnnotations, eventsProjectValidationHandler);
+        server.tool('ductape_function_setup', portableFunctionSetupInputSchema.shape, portableFunctionSetupAnnotations, 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/docs/TOOLS.md

@@ -2,6 +2,21 @@
 
 The Ductape MCP server exposes proxy, CLI, discovery, documentation, migration, and portable-function setup tools.
 
+## Tools: `ductape_events_topic_setup` and `ductape_events_validate_project`
+
+`ductape_events_topic_setup` is a read-only generator for one canonical topic asset. It returns the
+exact `<project-root>/ductape/events/<topic-tag>.topic.json` path, one directly importable JSON
+object, and its validation/create commands. It never writes the file or creates a remote topic.
+
+`ductape_events_validate_project` runs the CLI's repository validator. It rejects missing canonical
+directories, non-`.topic.json` JSON files, aggregate arrays/catalogues, filename/tag disagreement,
+unknown fields, duplicate tags, and statically discoverable publishers without a matching topic.
+
+Ductape topic assets are always one topic per file. Never substitute an aggregate catalogue,
+manifest, envelope registry, or custom event registry.
+
+---
+
 ## Tool: `ductape_function_setup`
 
 Produces the mandatory local registry and signed HTTPS exposure plan for portable application

package/package.json

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