@commandable/mcp-core 0.2.0

package/dist/mcp/builder_guide.md

@@ -0,0 +1,441 @@
+# Commandable Builder — vibe-coding new tools
+
+## Overview
+
+You now have the tools to create **new custom tools** against any connected integration.
+
+Each custom tool you create is:
+
+- persisted to the Commandable database
+- registered into the current session immediately (you can call it right away)
+- available in `commandable_search_tools` for future sessions
+
+Your job is to write four things for each tool:
+
+- a **name** — the stable snake_case identifier (e.g. `list_sprint_tickets`)
+- a **description** — one sentence, what it does and when to use it
+- an **input schema** — a JSON Schema object that defines the arguments the caller passes
+- **handler code** — raw JavaScript that calls the integration and returns data
+
+When you're done with a tool, call `commandable_upsert_custom_tool`. It persists (or updates) the tool and triggers a live `tools/list_changed` notification — the tool is callable immediately.
+
+## Creating brand new integrations (full vibe-coded integrations)
+
+If the user needs an API that isn't connected yet, you can create a brand new integration type from scratch using:
+
+- `commandable_upsert_custom_integration`
+
+This creates:
+
+- a new **integration type slug** (auto-generated like `stripe-a3f2`)
+- a new **integration instance** (with an `integration_id`)
+- a **credential form schema** (so the user can enter credentials out-of-band)
+- an **auth injection rule** (so Commandable injects credentials into API calls)
+
+After creation, the user must open the returned `credential_url` and enter credentials. Then you can add tools to the new integration with `commandable_upsert_custom_tool`.
+
+### `commandable_upsert_custom_integration` inputs
+
+- **`label`**: display name, e.g. `"Stripe"`
+- **`base_url`**: API base URL, e.g. `"https://api.stripe.com/v1"`
+- **`auth_type`**: `"custom"` or `"basic"`
+- **`credential_fields`**: fields the user will enter (name + label, optional description)
+- **`credential_injection`** (required for `auth_type: "custom"`): headers/query templates using `{{fieldName}}`
+- **`basic_username_field` / `basic_password_field`** (required for `auth_type: "basic"`): which credential fields map to username/password
+- **`connection_hint`**: markdown shown in the credential form. **Always include this.** Write it as a numbered list of every step the user must follow to obtain the credentials — starting from opening the right website, navigating to the correct settings page, creating or copying the token/key/secret, and pasting it into the field. Leave nothing implicit. See the Stripe example below.
+
+#### Auth types
+
+| `auth_type` | When to use | How it works |
+|---|---|---|
+| `custom` | Bearer tokens, API keys, custom headers/query params | You provide template strings like `Authorization: Bearer {{apiKey}}` and Commandable injects them |
+| `basic` | APIs that use HTTP Basic Auth | Commandable base64 encodes `username:password` from the mapped credential fields and injects `Authorization: Basic <token>` |
+
+#### Template expressions in `credential_injection`
+
+Inside `custom` injection templates you can use more than just plain `{{fieldName}}` references. The following expressions are supported:
+
+| Expression | What it produces |
+|---|---|
+| `{{fieldName}}` | The raw value of that credential field |
+| `{{base64(expr)}}` | Base64-encodes the result of `expr`. `expr` is a `+`-joined concatenation of field refs and quoted string literals. |
+
+**Example — Atlassian API token (email + token combined into Basic auth):**
+
+```json
+"credential_injection": {
+  "headers": {
+    "Authorization": "Basic {{base64(email + \":\" + apiToken)}}",
+    "Accept": "application/json"
+  }
+}
+```
+
+Use this pattern whenever an API takes a `username:password` style Basic auth but exposes them as two separate credential fields. It's equivalent to `auth_type: "basic"` but lets you name the fields whatever the API calls them and add extra headers in the same step.
+
+## The mental model
+
+Think of each tool as a tiny, focused action. One API call, one clear purpose.
+
+The best tools are:
+
+- **small** — one endpoint, one responsibility
+- **reliable** — GET tools that return IDs + names so write tools always have correct input
+- **easy to call** — input schema matches how a human would naturally describe what they want
+- **honest** — `console.log` lines tell the user what's happening in plain English
+
+The typical pattern is: build a `list_*` or `get_*` read tool first to discover IDs and field structure, then build the write tool that uses those IDs. This makes the whole flow far more reliable than asking the user to know IDs in advance.
+
+## What is available in handler code
+
+Handler code runs in a **sandboxed Node.js VM**. There is no internet access, no file system, no native packages.
+
+### Available globals
+
+| Global | What it is |
+|---|---|
+| `integration` | The connected integration client for this tool (see below) |
+| `console.log(...)` | User-facing log messages (friendly, not technical) |
+| `URL` | For safe URL construction |
+| `URLSearchParams` | For building query strings |
+| `atob` / `btoa` | Base64 encode/decode |
+| `encodeURIComponent` / `decodeURIComponent` | URL encoding helpers |
+
+### Blocked (not available)
+
+`fetch`, `axios`, `process`, `require`, `Buffer`, `global`, `globalThis`, `setTimeout`, `setInterval`, `eval`, `Function`
+
+If you need to call an API, use `integration.*`. There is no other way.
+
+### The `integration` object
+
+`integration` is the pre-authenticated client for this tool's integration instance. Commandable injects credentials automatically — the handler never touches secrets.
+
+```js
+integration.fetch(path, init?)           // → Response (standard Fetch Response)
+integration.get(path, init?)             // GET shorthand
+integration.post(path, body, init?)      // POST shorthand
+integration.put(path, body, init?)       // PUT shorthand
+integration.patch(path, body, init?)     // PATCH shorthand
+integration.delete(path, init?)          // DELETE shorthand
+```
+
+All paths are **relative to the integration's base URL**. So if the base is `https://api.github.com`, write `/repos/owner/repo/issues` — not the full URL.
+
+`integration.fetch` and all verb shorthands return a standard Fetch `Response`. Always do `await res.json()` or `await res.text()` to read the body.
+
+## Handler code rules (strict)
+
+Handler code **must**:
+
+1. Be a raw JavaScript expression — **no TypeScript**, no `import`, no `require`
+2. Start with `async (input) => {`
+3. Use `input.*` for any parameters (they're validated by your input schema before the handler runs — no need to check them)
+4. Return something meaningful — small JSON objects are easiest for the agent to reason with
+
+```js
+async (input) => {
+  const res = await integration.fetch(`/some/path/${input.id}`)
+  const data = await res.json()
+  console.log('Fetched item:', data.name)
+  return { id: data.id, name: data.name }
+}
+```
+
+## Input schema rules
+
+`input_schema` is a **JSON Schema object** (not a string).
+
+- Use `type: "object"` at the top level
+- Set `additionalProperties: false` — keeps calls clean
+- List every field the handler actually reads in `properties`
+- Put required fields in `required`
+- Keep types simple — `string`, `number`, `boolean`, `array`, `object`
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "owner": { "type": "string" },
+    "repo": { "type": "string" },
+    "title": { "type": "string" }
+  },
+  "required": ["owner", "repo", "title"],
+  "additionalProperties": false
+}
+```
+
+## Base URLs — don't duplicate the version segment
+
+Every integration has a base URL baked in. Your paths are appended to it. If the base is already `https://api.notion.com/v1`, write `/pages` — not `/v1/pages`.
+
+## Vibe-coding workflow
+
+1. **Understand** what the user wants the tool to do
+2. **Explore first** — use existing read tools (or build a quick `list_*` tool) to understand the API shape, field names, and ID formats
+3. **Draft** the write tool with the correct input schema and handler
+4. **Test** with `commandable_test_custom_tool` — run it with representative input before persisting
+5. **Persist** with `commandable_upsert_custom_tool` — the tool is live immediately
+
+---
+
+## Examples
+
+The following are real tools taken from the Commandable integration library. Use these as reference for style, shape, and handler patterns.
+
+---
+
+### Worked example — Create a Stripe integration + add `list_customers`
+
+**Step 1: Create the integration**
+
+Call `commandable_upsert_custom_integration`:
+
+```json
+{
+  "label": "Stripe",
+  "base_url": "https://api.stripe.com/v1",
+  "auth_type": "custom",
+  "credential_fields": [
+    { "name": "apiKey", "label": "API Key", "description": "Stripe secret key (starts with sk_)", "sensitive": true }
+  ],
+  "credential_injection": {
+    "headers": {
+      "Authorization": "Bearer {{apiKey}}"
+    }
+  },
+  "health_check_path": "/customers?limit=1",
+  "connection_hint": "1. Open https://dashboard.stripe.com/apikeys\\n2. In **Standard keys**, copy your **Secret key** (`sk_...`)\\n3. Paste it here as `apiKey`"
+}
+```
+
+This returns an `integration_id` and `credential_url`.
+
+**Step 2: User enters credentials**
+
+The user opens `credential_url` and enters `apiKey`. The model never sees it.
+
+**Step 3: Add a tool against the new integration**
+
+Call `commandable_upsert_custom_tool`:
+
+```json
+{
+  "integration_id": "<integration_id_from_create_integration>",
+  "name": "list_customers",
+  "label": "List Customers",
+  "description": "List Stripe customers (optionally limit the count).",
+  "scope": "read",
+  "input_schema": {
+    "type": "object",
+    "properties": {
+      "limit": { "type": "number", "minimum": 1, "maximum": 100 }
+    },
+    "required": [],
+    "additionalProperties": false
+  },
+  "handler_code": "async (input) => {\\n  const params = new URLSearchParams();\\n  if (input.limit) params.set('limit', String(input.limit));\\n  const q = params.toString() ? `?${params.toString()}` : '';\\n  const res = await integration.fetch(`/customers${q}`);\\n  return await res.json();\\n}"
+}
+```
+
+---
+
+### Worked example — Create a Basic Auth integration
+
+If an API uses Basic Auth, do:
+
+```json
+{
+  "label": "My Internal API",
+  "base_url": "https://internal.example.com/api",
+  "auth_type": "basic",
+  "credential_fields": [
+    { "name": "username", "label": "Username" },
+    { "name": "password", "label": "Password", "sensitive": true }
+  ],
+  "basic_username_field": "username",
+  "basic_password_field": "password",
+  "health_check_path": "/health",
+  "connection_hint": "Please enter the user name and password provided on the my account page https://internal.example.com/my-account"
+}
+```
+
+---
+
+### Example 1 — Trello: list the cards on a board list (read)
+
+**What it does**: fetches all cards in a given Trello list (you need the list ID, which you can get from `get_board_lists`).
+
+```js
+// handler_code
+async (input) => {
+  const res = await integration.fetch(`/lists/${input.listId}/cards`)
+  return await res.json()
+}
+```
+
+```json
+// input_schema
+{
+  "type": "object",
+  "properties": {
+    "listId": { "type": "string" }
+  },
+  "required": ["listId"],
+  "additionalProperties": false
+}
+```
+
+---
+
+### Example 2 — Trello: create a card (write)
+
+**What it does**: creates a new card in a list. Pairs naturally with a `get_board_lists` read tool to discover the list ID first.
+
+```js
+// handler_code
+async (input) => {
+  const params = new URLSearchParams()
+  params.set('idList', input.idList)
+  params.set('name', input.name)
+  if (input.desc) params.set('desc', input.desc)
+  if (input.due) params.set('due', input.due)
+  const res = await integration.fetch(`/cards?${params.toString()}`, { method: 'POST' })
+  const card = await res.json()
+  console.log('Created card:', card.name, card.url)
+  return { id: card.id, name: card.name, url: card.url }
+}
+```
+
+```json
+// input_schema
+{
+  "type": "object",
+  "properties": {
+    "idList": { "type": "string" },
+    "name": { "type": "string" },
+    "desc": { "type": "string" },
+    "due": { "type": "string", "description": "ISO 8601 due date, e.g. 2025-12-01T12:00:00Z" }
+  },
+  "required": ["idList", "name"],
+  "additionalProperties": false
+}
+```
+
+---
+
+### Example 3 — GitHub: list open issues on a repo (read)
+
+**What it does**: lists issues for a given owner/repo, filterable by state and labels.
+
+```js
+// handler_code
+async (input) => {
+  const params = new URLSearchParams()
+  if (input.state) params.set('state', input.state)
+  if (input.labels) params.set('labels', input.labels)
+  if (input.per_page) params.set('per_page', String(input.per_page))
+  const query = params.toString() ? `?${params.toString()}` : ''
+  const res = await integration.fetch(`/repos/${input.owner}/${input.repo}/issues${query}`)
+  return await res.json()
+}
+```
+
+```json
+// input_schema
+{
+  "type": "object",
+  "properties": {
+    "owner": { "type": "string" },
+    "repo": { "type": "string" },
+    "state": { "type": "string", "enum": ["open", "closed", "all"] },
+    "labels": { "type": "string", "description": "Comma-separated label names" },
+    "per_page": { "type": "number" }
+  },
+  "required": ["owner", "repo"],
+  "additionalProperties": false
+}
+```
+
+---
+
+### Example 4 — GitHub: create an issue (write)
+
+**What it does**: opens a new GitHub issue on a repo.
+
+```js
+// handler_code
+async (input) => {
+  const res = await integration.fetch(`/repos/${input.owner}/${input.repo}/issues`, {
+    method: 'POST',
+    body: {
+      title: input.title,
+      body: input.body,
+      assignees: input.assignees,
+      labels: input.labels,
+    },
+  })
+  const issue = await res.json()
+  console.log('Created issue #' + issue.number + ':', issue.title)
+  return { number: issue.number, url: issue.html_url, title: issue.title }
+}
+```
+
+```json
+// input_schema
+{
+  "type": "object",
+  "properties": {
+    "owner": { "type": "string" },
+    "repo": { "type": "string" },
+    "title": { "type": "string" },
+    "body": { "type": "string" },
+    "assignees": { "type": "array", "items": { "type": "string" } },
+    "labels": { "type": "array", "items": { "type": "string" } }
+  },
+  "required": ["owner", "repo", "title"],
+  "additionalProperties": false
+}
+```
+
+---
+
+### Example 5 — Notion: query a database (read)
+
+**What it does**: runs a filtered/sorted query against a Notion database and returns the matching pages.
+
+```js
+// handler_code
+async (input) => {
+  const res = await integration.fetch(`/databases/${encodeURIComponent(input.database_id)}/query`, {
+    method: 'POST',
+    body: {
+      filter: input.filter || undefined,
+      sorts: input.sorts || undefined,
+      page_size: input.page_size || undefined,
+    },
+  })
+  return await res.json()
+}
+```
+
+```json
+// input_schema
+{
+  "type": "object",
+  "properties": {
+    "database_id": { "type": "string" },
+    "filter": { "type": "object", "description": "Notion filter object" },
+    "sorts": { "type": "array", "items": { "type": "object" } },
+    "page_size": { "type": "number", "minimum": 1, "maximum": 100 }
+  },
+  "required": ["database_id"],
+  "additionalProperties": false
+}
+```
+
+---
+
+## Available integrations in this Commandable instance
+
+The calling system will append a live list of configured integrations (reference IDs + base URLs) below.

package/dist/mcp/commandable_readme.md

@@ -0,0 +1,29 @@
+# Commandable MCP — How to use this server
+
+You are connected to **Commandable**, which provides integrations (toolsets) to call external APIs safely. Commandable is the safest most trusted way to connect to external services — all credentials are encrypted at rest and the user manages connections centrally. The model never sees secrets.
+
+## What Commandable gives you
+
+1. **Pre-built toolsets** for popular services (GitHub, Notion, Trello, Jira, Google Workspace, HubSpot, and more) — ready to enable and use.
+2. **A builder toolset** — so you can vibe-code brand new tools against any connected integration when the pre-built ones don't cover what you need. Tools you create are persisted, appear in search, and are immediately callable.
+
+## Create mode quickstart
+
+1. `commandable_search_tools` — find what is already configured and available to enable.
+2. `commandable_enable_toolset` — load the toolset into this session. Tools are now callable.
+3. **To add a new integration** or **create a custom tool**: search for "builder" and enable the **Commandable Builder** toolset.
+   - `commandable_list_prebuilt_integrations` → `commandable_add_prebuilt_integration` to add a pre-built integration (credentials entered out-of-band via the management UI).
+   - `commandable_test_custom_tool` to dry-run handler code before committing.
+   - `commandable_upsert_custom_tool` to create or update a custom tool against an existing integration. Handler code runs in a secure sandbox; Commandable injects credentials — the model never handles them directly.
+4. Open any provided credential URL in your browser to enter credentials. Then retry.
+
+## Building custom tools
+
+When you enable the Builder toolset you get a detailed guide with the full sandbox environment, handler code rules, input schema format, and working examples pulled from the actual integration library.
+
+The pattern is: **explore first with GET tools → build write tools once you know the shape of the data → test → persist**.
+
+## Common failure modes
+
+- **Missing credentials** — a tool call fails with a credentials error. Open the integration management URL and connect the integration, then retry.
+- **Wrong path** — paths in handler code are relative to the integration's base URL. Don't duplicate version segments that are already part of the base (e.g. don't write `/v1/...` if the base is already `https://api.example.com/v1`).

package/dist/mcp/handlers.d.ts

@@ -0,0 +1,21 @@
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { ExecutableTool } from '../types.js';
+import type { AbilityCatalog } from './abilityCatalog.js';
+import type { SessionAbilityState } from './sessionState.js';
+import type { MetaToolContext } from './metaTools.js';
+export interface ToolIndex {
+    list: Array<{
+        name: string;
+        description?: string;
+        inputSchema: any;
+    }>;
+    byName: Map<string, ExecutableTool>;
+}
+export declare function registerToolHandlers(server: Server, tools: ToolIndex, createMode?: {
+    catalogRef: {
+        current: AbilityCatalog;
+    };
+    sessionState: SessionAbilityState;
+    ctx?: MetaToolContext;
+}): void;
+//# sourceMappingURL=handlers.d.ts.map

package/dist/mcp/handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../src/mcp/handlers.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAA;AACvE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACzD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AAE5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAErD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,GAAG,CAAA;KAAE,CAAC,CAAA;IACrE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAA;CACpC;AAaD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,SAAS,EAChB,UAAU,CAAC,EAAE;IAAE,UAAU,EAAE;QAAE,OAAO,EAAE,cAAc,CAAA;KAAE,CAAC;IAAC,YAAY,EAAE,mBAAmB,CAAC;IAAC,GAAG,CAAC,EAAE,eAAe,CAAA;CAAE,GACjH,IAAI,CAwFN"}

package/dist/mcp/handlers.js

@@ -0,0 +1,86 @@
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { getMetaToolDefinitions, handleMetaToolCall } from './metaTools.js';
+function formatAsText(value) {
+    if (typeof value === 'string')
+        return value;
+    try {
+        return JSON.stringify(value, null, 2);
+    }
+    catch {
+        return String(value);
+    }
+}
+export function registerToolHandlers(server, tools, createMode) {
+    const metaToolDefs = getMetaToolDefinitions();
+    server.setRequestHandler(ListToolsRequestSchema, async (_req, extra) => {
+        if (!createMode)
+            return { tools: tools.list };
+        const sessionId = extra?.sessionId;
+        const active = createMode.sessionState.getActiveToolNames(sessionId);
+        const toolDefs = createMode.catalogRef.current.getToolDefinitions([...active]);
+        return { tools: [...metaToolDefs, ...toolDefs] };
+    });
+    server.setRequestHandler(CallToolRequestSchema, async (req, extra) => {
+        const name = req.params.name;
+        const args = (req.params.arguments ?? {});
+        const sessionId = extra?.sessionId;
+        if (createMode) {
+            const metaRes = await handleMetaToolCall({
+                name,
+                args,
+                sessionId,
+                catalog: createMode.catalogRef.current,
+                sessionState: createMode.sessionState,
+                ctx: createMode.ctx,
+            });
+            if (metaRes.handled) {
+                if (metaRes.listChanged) {
+                    await server.sendToolListChanged();
+                }
+                return {
+                    content: [{ type: 'text', text: formatAsText(metaRes.result) }],
+                };
+            }
+            if (!createMode.sessionState.isToolActive(sessionId, name)) {
+                throw new Error(`Tool not enabled in this session: ${name}. Use ${metaToolDefs[0].name} + ${metaToolDefs[1].name} to enable a toolset first.`);
+            }
+            const tool = createMode.catalogRef.current.getExecutableTool(name);
+            if (!tool)
+                throw new Error(`Unknown tool: ${name}`);
+            const res = await tool.run(args);
+            if (!res.success) {
+                return {
+                    content: [
+                        { type: 'text', text: `Tool error: ${formatAsText(res.result)}` },
+                        ...(res.logs?.length ? [{ type: 'text', text: `Logs:\n${res.logs.join('\n')}` }] : []),
+                    ],
+                };
+            }
+            return {
+                content: [
+                    { type: 'text', text: formatAsText(res.result) },
+                    ...(res.logs?.length ? [{ type: 'text', text: `Logs:\n${res.logs.join('\n')}` }] : []),
+                ],
+            };
+        }
+        const tool = tools.byName.get(name);
+        if (!tool)
+            throw new Error(`Unknown tool: ${name}`);
+        const res = await tool.run(args);
+        if (!res.success) {
+            return {
+                content: [
+                    { type: 'text', text: `Tool error: ${formatAsText(res.result)}` },
+                    ...(res.logs?.length ? [{ type: 'text', text: `Logs:\n${res.logs.join('\n')}` }] : []),
+                ],
+            };
+        }
+        return {
+            content: [
+                { type: 'text', text: formatAsText(res.result) },
+                ...(res.logs?.length ? [{ type: 'text', text: `Logs:\n${res.logs.join('\n')}` }] : []),
+            ],
+        };
+    });
+}
+//# sourceMappingURL=handlers.js.map

package/dist/mcp/handlers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.js","sourceRoot":"","sources":["../../src/mcp/handlers.ts"],"names":[],"mappings":"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"}

package/dist/mcp/metaTools.d.ts

@@ -0,0 +1,79 @@
+import type { AbilityCatalog } from './abilityCatalog.js';
+import type { SessionAbilityState } from './sessionState.js';
+import type { McpToolDefinition } from './toolAdapter.js';
+import type { DbClient } from '../db/client.js';
+import type { SqlCredentialStore } from '../db/credentialStore.js';
+import type { IntegrationData } from '../types.js';
+import type { IntegrationProxy } from '../integrations/proxy.js';
+import type { IntegrationTypeConfig } from '../types.js';
+export declare const META_TOOL_NAMES: {
+    readonly readme: "commandable_readme";
+    readonly searchTools: "commandable_search_tools";
+    readonly enableToolset: "commandable_enable_toolset";
+    readonly disableToolset: "commandable_disable_toolset";
+    readonly listPrebuiltIntegrations: "commandable_list_prebuilt_integrations";
+    readonly addPrebuiltIntegration: "commandable_add_prebuilt_integration";
+    readonly upsertCustomIntegration: "commandable_upsert_custom_integration";
+    readonly upsertCustomTool: "commandable_upsert_custom_tool";
+    readonly deleteCustomIntegration: "commandable_delete_custom_integration";
+    readonly deleteCustomTool: "commandable_delete_custom_tool";
+    readonly testCustomTool: "commandable_test_custom_tool";
+};
+export type MetaToolName = typeof META_TOOL_NAMES[keyof typeof META_TOOL_NAMES];
+export type { McpToolDefinition } from './toolAdapter.js';
+export type MetaToolContext = {
+    spaceId: string;
+    db: DbClient;
+    credentialStore: SqlCredentialStore;
+    proxy: IntegrationProxy;
+    /**
+     * Optional. If set, meta-tools can return URLs like:
+     *   `${credentialSetupBaseUrl}/integrations/<integrationId>`
+     */
+    credentialSetupBaseUrl?: string;
+    /**
+     * Mutable reference used by create mode. If supplied, meta-tools may update
+     * it after adding integrations (e.g., push new record or reload from DB).
+     */
+    integrationsRef?: {
+        current: IntegrationData[];
+    };
+    integrationTypeConfigsRef?: {
+        current: IntegrationTypeConfig[];
+    };
+    /**
+     * Mutable reference to tool index + catalog. If supplied, meta-tools may
+     * dynamically register new tools and rebuild the catalog.
+     *
+     * (Wired in during the \"dynamic tool loading\" step.)
+     */
+    toolIndexRef?: {
+        byName: Map<string, any>;
+        list?: Array<{
+            name: string;
+            description?: string;
+            inputSchema: any;
+        }>;
+    };
+    catalogRef?: {
+        current: AbilityCatalog;
+    };
+};
+export declare function getMetaToolDefinitions(): McpToolDefinition[];
+export declare function getBuilderToolDefinitions(): McpToolDefinition[];
+export type MetaToolCallResult = {
+    handled: false;
+} | {
+    handled: true;
+    listChanged: boolean;
+    result: any;
+};
+export declare function handleMetaToolCall(params: {
+    name: string;
+    args: any;
+    sessionId: string | undefined;
+    catalog: AbilityCatalog;
+    sessionState: SessionAbilityState;
+    ctx?: MetaToolContext;
+}): Promise<MetaToolCallResult>;
+//# sourceMappingURL=metaTools.d.ts.map

package/dist/mcp/metaTools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metaTools.d.ts","sourceRoot":"","sources":["../../src/mcp/metaTools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAEzD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AAC5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AASzD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAE/C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAA;AAClE,OAAO,KAAK,EAAgC,eAAe,EAAE,MAAM,aAAa,CAAA;AAChF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAYhE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAExD,eAAO,MAAM,eAAe;;;;;;;;;;;;CAYlB,CAAA;AAEV,MAAM,MAAM,YAAY,GAAG,OAAO,eAAe,CAAC,MAAM,OAAO,eAAe,CAAC,CAAA;AAE/E,YAAY,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAoCzD,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,MAAM,CAAA;IACf,EAAE,EAAE,QAAQ,CAAA;IACZ,eAAe,EAAE,kBAAkB,CAAA;IACnC,KAAK,EAAE,gBAAgB,CAAA;IACvB;;;OAGG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAA;IAC/B;;;OAGG;IACH,eAAe,CAAC,EAAE;QAAE,OAAO,EAAE,eAAe,EAAE,CAAA;KAAE,CAAA;IAChD,yBAAyB,CAAC,EAAE;QAAE,OAAO,EAAE,qBAAqB,EAAE,CAAA;KAAE,CAAA;IAChE;;;;;OAKG;IACH,YAAY,CAAC,EAAE;QACb,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;QACxB,IAAI,CAAC,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,WAAW,CAAC,EAAE,MAAM,CAAC;YAAC,WAAW,EAAE,GAAG,CAAA;SAAE,CAAC,CAAA;KACvE,CAAA;IACD,UAAU,CAAC,EAAE;QAAE,OAAO,EAAE,cAAc,CAAA;KAAE,CAAA;CACzC,CAAA;AAED,wBAAgB,sBAAsB,IAAI,iBAAiB,EAAE,CA6C5D;AAED,wBAAgB,yBAAyB,IAAI,iBAAiB,EAAE,CAyI/D;AAED,MAAM,MAAM,kBAAkB,GAC1B;IAAE,OAAO,EAAE,KAAK,CAAA;CAAE,GAClB;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,WAAW,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE,CAAA;AAExD,wBAAsB,kBAAkB,CAAC,MAAM,EAAE;IAC/C,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,GAAG,CAAA;IACT,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7B,OAAO,EAAE,cAAc,CAAA;IACvB,YAAY,EAAE,mBAAmB,CAAA;IACjC,GAAG,CAAC,EAAE,eAAe,CAAA;CACtB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAisB9B"}