@ductape/mcp 0.1.15 → 0.1.16

package/dist/index.js

@@ -155,9 +155,9 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   webhooks.events.list   [app_tag, webhook_tag]
 
 ━━━ MODULE: sessions ━━━
-  sessions.create        [product_tag, data: { tag: string, name: string, description?: string, expiry: number, period: "seconds"|"minutes"|"hours"|"days", selector: string, schema: { fieldName: { type: "string"|"number"|"boolean"|"object"|"array", required?: boolean, description?: string } } }]
-  ← selector is the dot-path of the primary identifier field (e.g. "playerId"); it MUST exist in schema.
-  ← schema declares the shape of data encrypted in the JWT; actual values are passed at runtime via sessions.start.
+  sessions.create        [product_tag, data: { tag: string, name: string, description?: string, expiry: number, period: "seconds"|"minutes"|"hours"|"days", selector: string, schema: Record<string, unknown> }]
+  ← selector MUST be in the format "$Session{fieldName}" (e.g. "$Session{playerId}"). Plain dot-paths are rejected.
+  ← schema is SAMPLE DATA — actual example values, not type declarations. The value at the selector path must be a primitive (string|number|boolean), not an object.
   sessions.update        [product_tag, session_tag, data: { name?: string, description?: string, expiry?: number, period?: "seconds"|"minutes"|"hours"|"days", selector?: string, schema?: object }]
   sessions.fetch         [product_tag, session_tag]
   sessions.list          [product_tag]
@@ -587,7 +587,8 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   features.compare [executionId1: string, executionId2: string]
 
 ━━━ MODULE: caches ━━━
-  caches.create  [{ product, tag, name, description?, type: "redis"|"memcached"|"in-memory", envs: [{slug, connection_url}] }]
+  caches.create  [product_tag, data: { name: string, tag: string, description?: string, expiry: number }]
+  ← expiry is in SECONDS (e.g. 3600 = 1 hour, 86400 = 1 day). No type or envs — Ductape manages the store.
   caches.update  [product_tag, cache_tag, data: { name?: string, description?: string, expiry?: number }]
   caches.fetch   [product_tag, cache_tag]
   caches.list    [product_tag]
@@ -1630,17 +1631,22 @@ DUCTAPE SESSIONS
 A session is a named JWT schema on a product. It defines:
   - tag / name        — unique identifier and display name
   - expiry + period   — how long each issued JWT is valid (duration, not an absolute date)
-  - selector          — the dot-path of the field inside the data object that is the PRIMARY
-                        user identifier (e.g. "playerId"). This field becomes the lookup key
-                        for revoke, list, and analytics. It MUST exist in the schema.
-  - schema            — the complete shape of data that will be embedded in the JWT payload.
-                        Each field is declared as { type, required?, description? }.
-                        This is a TYPE DECLARATION, not sample data. The actual values
-                        are passed at runtime when calling sessions.start.
-
-IMPORTANT — schema field format: { fieldName: { type, required?, description? } }
-  type values: "string" | "number" | "boolean" | "object" | "array"
-  Do NOT use the shorthand { fieldName: "string" } — pass the full object form.
+  - selector          — MUST be in the format "$Session{fieldName}" where fieldName is the key
+                        in the schema that is the PRIMARY user identifier (e.g. "$Session{playerId}").
+                        Plain dot-paths like "playerId" are REJECTED by the validator.
+                        This field becomes the lookup key for revoke, list, and analytics.
+  - schema            — SAMPLE DATA showing example values for each field embedded in the JWT.
+                        This is NOT a type declaration. Use actual example values.
+                        The value at the selector path must be a primitive (string/number/boolean),
+                        not an object or array.
+
+IMPORTANT — schema is sample data, not type declarations:
+  CORRECT:   schema: { playerId: "player_abc123", username: "Alice", role: "player" }
+  INCORRECT: schema: { playerId: { type: "string", required: true } }   ← WILL FAIL
+
+IMPORTANT — selector must be "$Session{fieldName}" format:
+  CORRECT:   selector: "$Session{playerId}"
+  INCORRECT: selector: "playerId"   ← WILL FAIL with "Selector should be in the format $Session{...}{key}"
 
 Example (game product — player identity in JWT):
   ductape_execute("sessions.create", [product_tag, {
@@ -1648,12 +1654,12 @@ Example (game product — player identity in JWT):
     name: "Player Session",
     expiry: 24,
     period: "hours",
-    selector: "playerId",               // primary identifier — must be in schema below
+    selector: "$Session{playerId}",     // $Session{} wrapper required
     schema: {
-      playerId:  { type: "string",  required: true,  description: "Unique player ID" },
-      username:  { type: "string",  required: true,  description: "Player display name" },
-      role:      { type: "string",  required: false, description: "admin | player | guest" },
-      accountId: { type: "string",  required: false, description: "Linked account ID" },
+      playerId:  "player_abc123",       // sample value — primitive required at selector path
+      username:  "ShadowBlade",
+      role:      "player",
+      accountId: "acct_xyz",
     },
   }])
 
@@ -1662,7 +1668,7 @@ Runtime — create a session (sign a JWT):
     to discover the exact data field names accepted for this session tag.
   ductape_execute("sessions.start", [{ product, env, tag: "player-session",
     data: {
-      playerId:  "player_abc123",   // must match selector — used as the revocation/lookup key
+      playerId:  "player_abc123",   // must match selector path — used as the revocation/lookup key
       username:  "ShadowBlade",
       role:      "player",
       accountId: "acct_xyz",
@@ -1699,10 +1705,13 @@ DUCTAPE CACHES
 
 Caches are product-level Redis (or in-memory) stores for temporary key-value data with optional TTL.
 
-Registration (admin — ductape_cli):
+Registration (admin — ductape_cli or SDK):
   ductape_cli("resources caches create -f cache.json")
-  File: { name, tag, type: "redis"|"memcached"|"in-memory",
-          envs: [{ slug, connection_url }] }
+  File: { name, tag, description?, expiry: <seconds> }
+  No type or envs — Ductape manages the store infrastructure.
+  expiry is in SECONDS: 3600 = 1 hour, 86400 = 1 day, 604800 = 1 week.
+
+  SDK: ductape_execute("caches.create", [product_tag, { name, tag, description?, expiry: 3600 }])
 
 Operations:
   caches.set   [{ product, cache, key, value: string, expiry?: string (ISO 8601), env }]
@@ -1960,6 +1969,9 @@ Provision (create a NEW resource in the cloud):
   type field: "messageBrokers" (exact — not "messagebrokers" or "events")
 
   GCP Pub/Sub — creates a new Pub/Sub topic in GCP, stores credentials in secrets:
+    Cost: GCP Pub/Sub is usage-based — no upfront cost, no tier selection required.
+    You pay per GB of data published/subscribed (first 10 GB/month free).
+    It is safe to provision without user approval of a fixed monthly cost.
     [{"cloud":"gcp-snd","service":"pubsub","type":"messageBrokers",
       "product":"my-product","component":"notifications-broker","env":"snd",
       "topicName":"my-product-notifications-snd"},
@@ -1969,6 +1981,9 @@ Provision (create a NEW resource in the cloud):
     If topicName is omitted a timestamped name is generated — always supply it explicitly.
 
   AWS SQS — creates a new SQS queue per env:
+    Cost: SQS is usage-based — no upfront cost, no tier selection required.
+    First 1 million requests/month free; $0.40 per million after that.
+    It is safe to provision without user approval of a fixed monthly cost.
     [{"cloud":"aws-snd","service":"sqs","type":"messageBrokers",
       "product":"my-product","component":"notifications-broker","env":"snd",
       "queueName":"my-product-notifications-snd"},
@@ -1977,6 +1992,11 @@ Provision (create a NEW resource in the cloud):
       "queueName":"my-product-notifications-prd"}]
 
   Azure Service Bus — creates a namespace + queue per env:
+    Cost: Azure Service Bus has TIERED pricing — confirm the tier with the user before provisioning.
+    Basic:    queues only, ~$0.05/million operations. No topics/subscriptions.
+    Standard: queues + topics, ~$10/month base + $0.10/million operations.
+    Premium:  dedicated capacity, starts ~$677/month. Not needed for standard workloads.
+    DO NOT provision Azure Service Bus without confirming the tier with the user.
     [{"cloud":"azure-snd","service":"servicebus","type":"messageBrokers",
       "product":"my-product","component":"notifications-broker","env":"snd",
       "namespaceName":"myproduct-snd","queueName":"notifications"},

package/package.json

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

package/src/index.ts

@@ -166,9 +166,9 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   webhooks.events.list   [app_tag, webhook_tag]
 
 ━━━ MODULE: sessions ━━━
-  sessions.create        [product_tag, data: { tag: string, name: string, description?: string, expiry: number, period: "seconds"|"minutes"|"hours"|"days", selector: string, schema: { fieldName: { type: "string"|"number"|"boolean"|"object"|"array", required?: boolean, description?: string } } }]
-  ← selector is the dot-path of the primary identifier field (e.g. "playerId"); it MUST exist in schema.
-  ← schema declares the shape of data encrypted in the JWT; actual values are passed at runtime via sessions.start.
+  sessions.create        [product_tag, data: { tag: string, name: string, description?: string, expiry: number, period: "seconds"|"minutes"|"hours"|"days", selector: string, schema: Record<string, unknown> }]
+  ← selector MUST be in the format "$Session{fieldName}" (e.g. "$Session{playerId}"). Plain dot-paths are rejected.
+  ← schema is SAMPLE DATA — actual example values, not type declarations. The value at the selector path must be a primitive (string|number|boolean), not an object.
   sessions.update        [product_tag, session_tag, data: { name?: string, description?: string, expiry?: number, period?: "seconds"|"minutes"|"hours"|"days", selector?: string, schema?: object }]
   sessions.fetch         [product_tag, session_tag]
   sessions.list          [product_tag]
@@ -598,7 +598,8 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   features.compare [executionId1: string, executionId2: string]
 
 ━━━ MODULE: caches ━━━
-  caches.create  [{ product, tag, name, description?, type: "redis"|"memcached"|"in-memory", envs: [{slug, connection_url}] }]
+  caches.create  [product_tag, data: { name: string, tag: string, description?: string, expiry: number }]
+  ← expiry is in SECONDS (e.g. 3600 = 1 hour, 86400 = 1 day). No type or envs — Ductape manages the store.
   caches.update  [product_tag, cache_tag, data: { name?: string, description?: string, expiry?: number }]
   caches.fetch   [product_tag, cache_tag]
   caches.list    [product_tag]
@@ -1694,17 +1695,22 @@ DUCTAPE SESSIONS
 A session is a named JWT schema on a product. It defines:
   - tag / name        — unique identifier and display name
   - expiry + period   — how long each issued JWT is valid (duration, not an absolute date)
-  - selector          — the dot-path of the field inside the data object that is the PRIMARY
-                        user identifier (e.g. "playerId"). This field becomes the lookup key
-                        for revoke, list, and analytics. It MUST exist in the schema.
-  - schema            — the complete shape of data that will be embedded in the JWT payload.
-                        Each field is declared as { type, required?, description? }.
-                        This is a TYPE DECLARATION, not sample data. The actual values
-                        are passed at runtime when calling sessions.start.
-
-IMPORTANT — schema field format: { fieldName: { type, required?, description? } }
-  type values: "string" | "number" | "boolean" | "object" | "array"
-  Do NOT use the shorthand { fieldName: "string" } — pass the full object form.
+  - selector          — MUST be in the format "$Session{fieldName}" where fieldName is the key
+                        in the schema that is the PRIMARY user identifier (e.g. "$Session{playerId}").
+                        Plain dot-paths like "playerId" are REJECTED by the validator.
+                        This field becomes the lookup key for revoke, list, and analytics.
+  - schema            — SAMPLE DATA showing example values for each field embedded in the JWT.
+                        This is NOT a type declaration. Use actual example values.
+                        The value at the selector path must be a primitive (string/number/boolean),
+                        not an object or array.
+
+IMPORTANT — schema is sample data, not type declarations:
+  CORRECT:   schema: { playerId: "player_abc123", username: "Alice", role: "player" }
+  INCORRECT: schema: { playerId: { type: "string", required: true } }   ← WILL FAIL
+
+IMPORTANT — selector must be "$Session{fieldName}" format:
+  CORRECT:   selector: "$Session{playerId}"
+  INCORRECT: selector: "playerId"   ← WILL FAIL with "Selector should be in the format $Session{...}{key}"
 
 Example (game product — player identity in JWT):
   ductape_execute("sessions.create", [product_tag, {
@@ -1712,12 +1718,12 @@ Example (game product — player identity in JWT):
     name: "Player Session",
     expiry: 24,
     period: "hours",
-    selector: "playerId",               // primary identifier — must be in schema below
+    selector: "$Session{playerId}",     // $Session{} wrapper required
     schema: {
-      playerId:  { type: "string",  required: true,  description: "Unique player ID" },
-      username:  { type: "string",  required: true,  description: "Player display name" },
-      role:      { type: "string",  required: false, description: "admin | player | guest" },
-      accountId: { type: "string",  required: false, description: "Linked account ID" },
+      playerId:  "player_abc123",       // sample value — primitive required at selector path
+      username:  "ShadowBlade",
+      role:      "player",
+      accountId: "acct_xyz",
     },
   }])
 
@@ -1726,7 +1732,7 @@ Runtime — create a session (sign a JWT):
     to discover the exact data field names accepted for this session tag.
   ductape_execute("sessions.start", [{ product, env, tag: "player-session",
     data: {
-      playerId:  "player_abc123",   // must match selector — used as the revocation/lookup key
+      playerId:  "player_abc123",   // must match selector path — used as the revocation/lookup key
       username:  "ShadowBlade",
       role:      "player",
       accountId: "acct_xyz",
@@ -1764,10 +1770,13 @@ DUCTAPE CACHES
 
 Caches are product-level Redis (or in-memory) stores for temporary key-value data with optional TTL.
 
-Registration (admin — ductape_cli):
+Registration (admin — ductape_cli or SDK):
   ductape_cli("resources caches create -f cache.json")
-  File: { name, tag, type: "redis"|"memcached"|"in-memory",
-          envs: [{ slug, connection_url }] }
+  File: { name, tag, description?, expiry: <seconds> }
+  No type or envs — Ductape manages the store infrastructure.
+  expiry is in SECONDS: 3600 = 1 hour, 86400 = 1 day, 604800 = 1 week.
+
+  SDK: ductape_execute("caches.create", [product_tag, { name, tag, description?, expiry: 3600 }])
 
 Operations:
   caches.set   [{ product, cache, key, value: string, expiry?: string (ISO 8601), env }]
@@ -2029,6 +2038,9 @@ Provision (create a NEW resource in the cloud):
   type field: "messageBrokers" (exact — not "messagebrokers" or "events")
 
   GCP Pub/Sub — creates a new Pub/Sub topic in GCP, stores credentials in secrets:
+    Cost: GCP Pub/Sub is usage-based — no upfront cost, no tier selection required.
+    You pay per GB of data published/subscribed (first 10 GB/month free).
+    It is safe to provision without user approval of a fixed monthly cost.
     [{"cloud":"gcp-snd","service":"pubsub","type":"messageBrokers",
       "product":"my-product","component":"notifications-broker","env":"snd",
       "topicName":"my-product-notifications-snd"},
@@ -2038,6 +2050,9 @@ Provision (create a NEW resource in the cloud):
     If topicName is omitted a timestamped name is generated — always supply it explicitly.
 
   AWS SQS — creates a new SQS queue per env:
+    Cost: SQS is usage-based — no upfront cost, no tier selection required.
+    First 1 million requests/month free; $0.40 per million after that.
+    It is safe to provision without user approval of a fixed monthly cost.
     [{"cloud":"aws-snd","service":"sqs","type":"messageBrokers",
       "product":"my-product","component":"notifications-broker","env":"snd",
       "queueName":"my-product-notifications-snd"},
@@ -2046,6 +2061,11 @@ Provision (create a NEW resource in the cloud):
       "queueName":"my-product-notifications-prd"}]
 
   Azure Service Bus — creates a namespace + queue per env:
+    Cost: Azure Service Bus has TIERED pricing — confirm the tier with the user before provisioning.
+    Basic:    queues only, ~$0.05/million operations. No topics/subscriptions.
+    Standard: queues + topics, ~$10/month base + $0.10/million operations.
+    Premium:  dedicated capacity, starts ~$677/month. Not needed for standard workloads.
+    DO NOT provision Azure Service Bus without confirming the tier with the user.
     [{"cloud":"azure-snd","service":"servicebus","type":"messageBrokers",
       "product":"my-product","component":"notifications-broker","env":"snd",
       "namespaceName":"myproduct-snd","queueName":"notifications"},