@ductape/mcp 0.2.23 → 0.2.24

package/dist/index.js

@@ -5433,11 +5433,66 @@ function handleCliFlags() {
     }
     return false;
 }
+// Surfaced to every connected agent at initialize time, before any tool is called.
+// Keep this short — it is ambient, unconditional overhead on every session.
+// The full doctrine with concrete API shapes lives in the "ductape-first-approach" prompt below.
+const DUCTAPE_FIRST_INSTRUCTIONS = 'Ductape-first: before writing custom code for a capability, check whether Ductape already ' +
+    'provides it (databases, storage, notifications, events, sessions, caches, actions, quotas, ' +
+    'fallback, health). Model any multi-step or externally-risky operation as a Feature ' +
+    '(features.define + ctx.step) instead of an ad-hoc function chain — Features get durable ' +
+    'steps, retries, and compensation for free. Route any call to an unreliable or swappable ' +
+    'external provider (payment, email/SMS, any third-party API) through a Quota or Fallback with ' +
+    '2+ providers instead of one hardcoded call. Gate risky dependencies with Healthchecks. Treat ' +
+    'the ductape/ folder (features/, database/schema.json, notifications.json, events/) as the ' +
+    'source of truth: define there first, sync/apply, then write application code against it — ' +
+    'never the reverse. Invoke the "ductape-first-approach" prompt for the full doctrine with ' +
+    'concrete API shapes before scaffolding a new backend.';
+// The detailed doctrine, invoked on demand via the "ductape-first-approach" prompt rather than
+// forced onto every session. Grounded in the actual module contracts this server exposes
+// (features, quotas, fallback, health, jobs) — keep it in sync with ductape_docs topics.
+const DUCTAPE_FIRST_DOCTRINE = 'Follow this checklist before defaulting to plain CRUD when building on Ductape.\n\n' +
+    '1. Multi-step or side-effecting work (payments, order fulfillment, onboarding, anything with ' +
+    'a failure mode) -> define a Feature (features.define) with one ctx.step per stage and a ' +
+    'rollback/compensation callback where undoing matters. Execute it with features.execute, not a ' +
+    'plain function call chain. Call ductape_docs({ topic: "features" }) for the full contract.\n\n' +
+    '2. Any call to an external or swappable provider (payment gateway, email/SMS/push provider, ' +
+    'any third-party API) -> define a Quota (quotas.create) or Fallback (fallback.create) with at ' +
+    'least two provider options instead of one hardcoded ductape.api.run call. Gate the provider ' +
+    'with a Healthcheck (health.create) so a down dependency is caught before it fails a user ' +
+    'request, not after. Call ductape_docs({ topic: "resilience" }) for the exact shapes.\n\n' +
+    '3. Recurring or scheduled work -> use Jobs (jobs.create), not application-level cron or ' +
+    'setInterval.\n\n' +
+    '4. The ductape/ folder is the fulcrum, not an afterthought: ductape/features/*.ts + ' +
+    '"ductape features sync", ductape/database/schema.json + "ductape db schema generate/migrate", ' +
+    'ductape/notifications.json + "ductape apply notifications", ductape/events/*.topic.json + ' +
+    '"ductape apply events". Define the capability there first, then write application code that ' +
+    'calls into it — never duplicate the logic inline.\n\n' +
+    '5. Before scaffolding any new resource, run ductape_schema to see the exact required fields, ' +
+    'and ductape_cli("products components list --product-tag <tag> --json") to see what already ' +
+    'exists so you extend rather than re-create.\n\n' +
+    'Default assumption for any backend built through this MCP server: orchestration goes through ' +
+    'Features, provider risk goes through Quotas/Fallback, and the ductape/ folder is what ships — ' +
+    'not a database table and a CRUD wrapper.';
 async function main() {
     const { McpServer, StdioServerTransport } = await loadMcpSdk();
     const { version: mcpVersion } = createRequire(import.meta.url)('../package.json');
-    const server = new McpServer({ name: 'ductape-mcp', version: mcpVersion });
+    const server = new McpServer({ name: 'ductape-mcp', version: mcpVersion }, { instructions: DUCTAPE_FIRST_INSTRUCTIONS });
     const transport = new StdioServerTransport();
+    server.registerPrompt('ductape-first-approach', {
+        title: 'Ductape-first approach',
+        description: 'Load the Ductape-first doctrine before building: when to reach for Features, ' +
+            'Quotas/Fallback, Healthchecks, and the ductape/ folder instead of plain CRUD or ad-hoc ' +
+            'glue code.',
+        argsSchema: {},
+    }, async (_args, _extra) => ({
+        description: 'How to approach building with Ductape',
+        messages: [
+            {
+                role: 'user',
+                content: { type: 'text', text: DUCTAPE_FIRST_DOCTRINE },
+            },
+        ],
+    }));
     const cliHandler = async (args) => {
         const cli = checkCli();
         if (!cli.available) {

package/package.json

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