@ductape/mcp 0.1.0

package/dist/proxy-client.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Client for the Ductape backend SDK proxy using Publishable Key.
+ */
+export declare const API_BASE_URL = "https://api.ductape.app";
+export type SDKModule = 'product' | 'app' | 'databases' | 'graph' | 'webhooks' | 'notifications' | 'messageBrokers' | 'storage' | 'vector' | 'caches' | 'sessions' | 'quotas' | 'actions' | 'features' | 'jobs' | 'logs' | 'resilience' | 'health' | 'fallback' | 'secrets';
+/**
+ * Execute an SDK operation via the backend proxy using a Publishable Key.
+ */
+export declare function executeViaProxy<T = unknown>(publishable_key: string, module: SDKModule, method: string, params?: unknown[]): Promise<T>;
+export interface IGenerateExecutablePayloadRequest {
+    workspace_id: string;
+    user_id: string;
+    public_key: string;
+    product_tag: string;
+    env_slug: string;
+    operation_family: string;
+    method: string;
+    targets?: Record<string, unknown>;
+    include_session?: boolean;
+    include_cache?: boolean;
+    schema_mode?: 'strict' | 'best_effort';
+    input_hint?: Record<string, unknown>;
+}
+export interface IGenerateExecutablePayloadResponse {
+    payload: Record<string, unknown>;
+    meta: Record<string, unknown>;
+}
+export declare function generateExecutablePayload<T = IGenerateExecutablePayloadResponse>(request: IGenerateExecutablePayloadRequest): Promise<T>;
+//# sourceMappingURL=proxy-client.d.ts.map

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

@@ -0,0 +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,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,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,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,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;AAQD,wBAAsB,yBAAyB,CAAC,CAAC,GAAG,kCAAkC,EACpF,OAAO,EAAE,iCAAiC,GACzC,OAAO,CAAC,CAAC,CAAC,CAmBZ"}

package/dist/proxy-client.js

@@ -0,0 +1,49 @@
+/**
+ * Client for the Ductape backend SDK proxy using Publishable Key.
+ */
+export const API_BASE_URL = 'https://api.ductape.app';
+/**
+ * Execute an SDK operation via the backend proxy using a Publishable Key.
+ */
+export async function executeViaProxy(publishable_key, module, method, params = []) {
+    const url = `${API_BASE_URL.replace(/\/$/, '')}/proxy/v1/sdk-proxy/execute`;
+    const res = await fetch(url, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+            publishable_key,
+            module,
+            method,
+            params,
+        }),
+    });
+    const body = (await res.json());
+    if (!res.ok) {
+        throw new Error(body.message ?? `Proxy request failed: ${res.status}`);
+    }
+    if (typeof body.status === 'boolean' && !body.status) {
+        throw new Error(body.message ?? 'SDK operation failed');
+    }
+    return body.data?.data;
+}
+export async function generateExecutablePayload(request) {
+    const url = `${API_BASE_URL.replace(/\/$/, '')}/integrations/v1/payloads/generate`;
+    const res = await fetch(url, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            'x-access-key': request.public_key,
+        },
+        body: JSON.stringify(request),
+    });
+    const body = (await res.json());
+    if (!res.ok) {
+        throw new Error(body.message ?? `Payload generation request failed: ${res.status}`);
+    }
+    if (typeof body.status === 'boolean' && !body.status) {
+        throw new Error(body.message ?? 'Payload generation failed');
+    }
+    return body.data;
+}

package/docs/TOOLS.md

@@ -0,0 +1,204 @@
+# 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
+
+---
+
+## 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.
+
+### Arguments
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `module` | string | SDK module name (see **Modules** below). |
+| `method` | string | Method name for that module (see **Allowed methods per module**). |
+| `params` | array | Arguments for the method, in the same order as the SDK signature. |
+
+### Example
+
+- **Database query:**  
+  `{ "module": "databases", "method": "query", "params": [{ "product": "my-product", "database": "mongo-db", "env": "prd", "query": "{}" }] }`
+
+- **List storage buckets:**  
+  `{ "module": "storage", "method": "list", "params": [] }`
+
+- **Vector search:**  
+  `{ "module": "vector", "method": "findSimilar", "params": ["namespace", "vector", { "topK": 10 }] }`
+
+### Response
+
+Returns the SDK method result as JSON. On error, the tool returns an error message (e.g. validation or proxy failure).
+
+---
+
+## Tool: `ductape_generate_payload`
+
+Generates canonical executable payload templates from backend route `/integrations/v1/payloads/generate`.
+Use this when the MCP agent needs payload + metadata context before writing SDK code snippets for engineers.
+
+### Arguments
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `workspace_id` | string | Workspace ID |
+| `user_id` | string | User ID |
+| `public_key` | string | Workspace public key (also sent as x-access-key) |
+| `product_tag` | string | Product tag (e.g. `ductape:my-product`) |
+| `env_slug` | string | Environment slug (`prd`, `stg`, etc.) |
+| `operation_family` | string | Executable family (`action`, `workflow`, `database`, `graph`, `vector`, `storage`, `notification`, `messaging`) |
+| `method` | string | Execution method (`run`, `dispatch`, `find`, `insert`, `send`, etc.) |
+| `targets` | object | Optional component targeting payload |
+| `schema_mode` | enum | `strict` or `best_effort` |
+| `include_session` | boolean | Include session tags/context |
+| `include_cache` | boolean | Include cache tags/context |
+| `input_hint` | object | Optional schema/input hint used in payload generation |
+
+### Response
+
+Returns JSON object:
+
+- `payload`: canonical executable payload template
+- `meta`: schema context, validation info, warnings, and inferred tags
+
+---
+
+## Tool: `ductape_generate_snippet`
+
+Builds on `ductape_generate_payload` and returns both:
+
+- `payload` (canonical payload/meta from backend)
+- `snippet` (ready SDK example code)
+
+### Arguments
+
+Same arguments as `ductape_generate_payload`, plus:
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `language` | enum | `typescript` or `python` |
+
+### Response
+
+Returns JSON object:
+
+- `payload`: backend payload generation response
+- `snippet`: executable code sample string
+
+---
+
+## Modules
+
+The following modules are available. Each module supports only the methods listed for it; any other method will be rejected by the proxy.
+
+- `product` – Product, environments, apps, webhooks, health
+- `app` – App, environments, variables, constants, actions, auths, webhooks
+- `databases` – Connect, query, CRUD, schema, migrations, actions
+- `graph` – Connect, nodes, relationships, traversal, schema, actions, transactions
+- `webhooks` – Create, list, events, enable, trigger
+- `notifications` – Messages, templates, dispatch, send
+- `messageBrokers` – Brokers, topics, publish, subscribe, messages
+- `storage` – Buckets, upload, download, list files, signed URLs
+- `vector` – Indexes, upsert, query, similar, namespaces, actions
+- `caches` – Create, get, set, del, ttl, keys
+- `sessions` – Create, start, verify, refresh, revoke
+- `quotas` – Create, check, consume, reset, usage
+- `actions` – Create, list, dispatch, run
+- `features` – Feature flags, isEnabled, run
+- `jobs` – Create, list, cancel, pause, resume, retry
+- `logs` – Query, fetch, list, stream
+- `resilience` – Quotas and fallbacks sub-modules
+- `health` – Define, create, status, check, run
+- `fallback` – Define, create, run, dispatch
+- `secrets` – Create, list, resolve, revoke, validate
+
+---
+
+## Allowed methods per module
+
+Only these methods can be called for each module. Method names are case-sensitive.
+
+### product
+
+`create`, `fetch`, `update`, `init`, `updateValidation`, `environments.create`, `environments.list`, `environments.fetch`, `environments.update`, `apps.connect`, `apps.add`, `apps.list`, `apps.fetch`, `apps.update`, `apps.webhooks.list`, `apps.webhooks.enable`, `apps.webhooks.generateLink`, `apps.health.create`, `apps.health.update`, `apps.health.fetch`, `apps.health.list`
+
+### app
+
+`create`, `fetch`, `update`, `init`, `environments.create`, `environments.list`, `environments.fetch`, `environments.update`, `variables.create`, `variables.list`, `variables.fetch`, `variables.update`, `constants.create`, `constants.list`, `constants.fetch`, `constants.update`, `actions.create`, `actions.list`, `actions.fetch`, `actions.update`, `actions.delete`, `auths.create`, `auths.list`, `auths.fetch`, `auths.update`, `webhooks.create`, `webhooks.list`, `webhooks.fetch`, `webhooks.update`, `webhooks.events.create`, `webhooks.events.list`, `webhooks.events.fetch`, `webhooks.events.update`
+
+### databases
+
+`connect`, `testConnection`, `disconnect`, `closeAll`, `getCurrentContext`, `connection`, `create`, `register`, `list`, `fetch`, `update`, `updateLocalConfig`, `query`, `insert`, `updateRecords`, `delete`, `upsert`, `count`, `sum`, `avg`, `min`, `max`, `aggregate`, `beginTransaction`, `schema.create`, `schema.drop`, `schema.addField`, `schema.dropField`, `schema.renameField`, `schema.modifyField`, `schema.createIndex`, `schema.dropIndex`, `schema.addConstraint`, `schema.dropConstraint`, `schema.rename`, `schema.exists`, `schema.list`, `schema.describe`, `schema.indexes`, `migration.create`, `migration.update`, `migration.fetch`, `migration.list`, `migration.delete`, `migration.run`, `migration.rollback`, `migration.history`, `migration.status`, `action.create`, `action.update`, `action.fetch`, `action.list`, `action.delete`, `action.dispatch`, `dispatch`, `getAdapter`, `getService`
+
+### graph
+
+`connect`, `testConnection`, `disconnect`, `disconnectAll`, `getCurrentContext`, `create`, `fetchAll`, `fetch`, `update`, `delete`, `createNode`, `findNodes`, `findNodeById`, `updateNode`, `deleteNode`, `mergeNode`, `addLabels`, `removeLabels`, `setLabels`, `createRelationship`, `findRelationships`, `findRelationshipById`, `updateRelationship`, `deleteRelationship`, `mergeRelationship`, `traverse`, `shortestPath`, `allPaths`, `getNeighborhood`, `findConnectedComponents`, `countNodes`, `countRelationships`, `getStatistics`, `fullTextSearch`, `vectorSearch`, `query`, `schema.createNodeIndex`, `schema.createNodeConstraint`, `schema.createRelationshipIndex`, `schema.listIndexes`, `schema.listConstraints`, `schema.dropIndex`, `schema.dropConstraint`, `schema.listLabels`, `schema.listRelationshipTypes`, `action.create`, `action.list`, `action.fetch`, `action.update`, `action.delete`, `action.dispatch`, `executeTransaction`, `beginTransaction`, `commitTransaction`, `rollbackTransaction`, `dispatch`, `execute`, `getService`
+
+### webhooks
+
+`create`, `createWithEvents`, `list`, `fetch`, `update`, `enable`, `generateLink`, `trigger`, `events.create`, `events.list`, `events.fetch`, `events.update`
+
+### notifications
+
+`getMessages`, `create`, `list`, `fetch`, `update`, `delete`, `templates.create`, `templates.list`, `templates.fetch`, `templates.update`, `templates.delete`, `messages.create`, `messages.list`, `messages.fetch`, `messages.update`, `dispatch`, `send`
+
+### messageBrokers
+
+`create`, `list`, `fetch`, `update`, `delete`, `topics.create`, `topics.list`, `topics.fetch`, `topics.update`, `topics.delete`, `publish`, `subscribe`, `dispatch`, `testConnection`, `messages.query`, `messages.getProducers`, `messages.getConsumers`, `messages.getDeadLetters`, `messages.getStats`, `messages.getDashboard`
+
+### storage
+
+`create`, `list`, `fetch`, `update`, `delete`, `upload`, `download`, `remove`, `listFiles`, `getSignedUrl`, `dispatch`, `stats`, `testConnection`
+
+### vector
+
+`create`, `list`, `fetch`, `update`, `delete`, `connect`, `disconnect`, `disconnectAll`, `testConnection`, `query`, `upsert`, `upsertOne`, `fetchVectors`, `fetchOne`, `deleteVectors`, `deleteByIds`, `deleteAll`, `findSimilar`, `updateVector`, `updateMetadata`, `listVectors`, `listAllVectors`, `listNamespaces`, `deleteNamespace`, `describeIndex`, `getStats`, `createIndex`, `deleteIndex`, `listIndexes`, `count`, `exists`, `supportsFeature`, `getService`, `actions.create`, `actions.update`, `actions.fetch`, `actions.fetchAll`, `actions.delete`, `actions.execute`
+
+### caches
+
+`create`, `list`, `fetch`, `update`, `delete`, `get`, `set`, `del`, `has`, `clear`, `ttl`, `expire`, `keys`, `fetchValues`, `fetchRemote`, `dispatch`
+
+### sessions
+
+`create`, `update`, `list`, `fetch`, `delete`, `users`, `start`, `verify`, `refresh`, `revoke`, `listActive`, `revokeAll`, `updateData`, `extendSession`, `fetchUsers`, `fetchUserDetails`, `fetchDashboard`, `fetchUserDashboard`
+
+### quotas
+
+`create`, `list`, `fetch`, `update`, `delete`, `check`, `consume`, `reset`, `getUsage`
+
+### actions
+
+`create`, `list`, `fetch`, `update`, `delete`, `dispatch`, `run`, `import`
+
+### features
+
+`create`, `list`, `fetch`, `update`, `delete`, `isEnabled`, `dispatch`, `run`
+
+### jobs
+
+`create`, `list`, `fetch`, `update`, `delete`, `get`, `listJobs`, `cancel`, `cancelMany`, `pause`, `pauseMany`, `resume`, `resumeMany`, `retry`, `retryMany`, `reschedule`, `getHistory`, `getStats`, `setWebhook`, `getService`
+
+### logs
+
+`query`, `fetch`, `list`, `stream`
+
+### resilience
+
+`quotas.create`, `quotas.list`, `quotas.fetch`, `quotas.update`, `quotas.delete`, `quotas.check`, `quotas.consume`, `quotas.reset`, `fallbacks.create`, `fallbacks.list`, `fallbacks.fetch`, `fallbacks.update`, `fallbacks.delete`, `fallbacks.execute`
+
+### health
+
+`define`, `create`, `list`, `fetch`, `update`, `delete`, `status`, `check`, `run`
+
+### fallback
+
+`define`, `create`, `list`, `fetch`, `update`, `delete`, `run`, `dispatch`
+
+### secrets
+
+`create`, `list`, `fetch`, `update`, `delete`, `exists`, `revoke`, `resolve`, `validate`, `getService`
+
+---
+
+For method signatures and parameter shapes, see the Ductape SDK documentation or the SDK source (`sdk/ts/src/`). The proxy validates that `module` and `method` are in the lists above before executing.

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@ductape/mcp",
+  "version": "0.1.0",
+  "description": "MCP server that exposes Ductape SDK operations via the backend proxy",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "ductape-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts"
+  },
+  "keywords": [
+    "mcp",
+    "ductape",
+    "sdk",
+    "proxy"
+  ],
+  "license": "UNLICENSED",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@modelcontextprotocol/server": "^2.0.0-alpha.2",
+    "crypto-js": "^4.2.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/crypto-js": "^4.2.0",
+    "@types/node": "^25.6.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.3.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}