caddie-mcp 0.1.0

package/dist/tools/caddie.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerCaddieTools(s: McpServer): void;

package/dist/tools/caddie.js

@@ -0,0 +1,148 @@
+import { z } from "zod";
+import { request, parseJsonParam, truncateResponse, getApiKey, getServerUrl } from "../client.js";
+import { consumeCaddieStream } from "../sse-client.js";
+import { definitionSchema, validateWorkflowId, validateRunId, auditLog } from "./shared.js";
+import { formatCaddieBlocksForCLI } from "./parse-caddie-blocks.js";
+/** Format a Caddie workflow response with incomplete fields, validation errors, and next steps. */
+function formatWorkflowResponse(done, header, nextSteps) {
+    const parts = [header];
+    parts.push(JSON.stringify(done.data.workflow, null, 2));
+    if (done.data.incompleteFields?.length) {
+        parts.push(`\nIncomplete fields that need user input:\n- ${done.data.incompleteFields.join("\n- ")}`);
+    }
+    if (done.data.validationErrors?.length) {
+        parts.push("\nValidation errors:");
+        for (const err of done.data.validationErrors) {
+            parts.push(`- ${err.nodeId ? `[${err.nodeId}] ` : ""}${err.message}`);
+        }
+    }
+    parts.push(`\nNext steps:\n${nextSteps}`);
+    return truncateResponse(parts.join("\n"));
+}
+export function registerCaddieTools(s) {
+    s.registerTool("b3os_build_workflow", {
+        description: `Build or modify a workflow using Caddie, the B3OS AI agent. Describe what you want
+in natural language and Caddie will generate or update the workflow definition.
+
+Use this when you need to:
+- Create a new workflow from a description ("monitor ETH price and alert on Telegram")
+- Modify an existing workflow ("add a filter node before the swap action")
+- Get help designing complex logic (branching, loops, error handling)
+
+If workflowId is provided, Caddie loads the existing workflow and modifies it.
+If definition is provided, Caddie uses it as the starting point.
+Otherwise, Caddie creates a new workflow from scratch.
+
+Returns the workflow definition JSON (ready for b3os_create_workflow or b3os_update_workflow)
+along with any incomplete fields that still need user input and validation errors.`,
+        inputSchema: {
+            message: z.string().describe("Natural language description of what to build or change"),
+            workflowId: z.string().optional().describe("Existing workflow ID to modify (e.g. 'wf_abc123')"),
+            definition: definitionSchema.optional().describe("Starting definition to modify (alternative to workflowId)"),
+        },
+    }, async ({ message, workflowId, definition }) => {
+        try {
+            if (workflowId)
+                validateWorkflowId(workflowId);
+            auditLog("CADDIE_BUILD", workflowId ? `workflow ${workflowId}` : "new workflow");
+            const apiKey = getApiKey();
+            const serverUrl = getServerUrl();
+            const parsedDefinition = definition
+                ? parseJsonParam(definition, "definition")
+                : undefined;
+            const done = await consumeCaddieStream(apiKey, serverUrl, {
+                message,
+                workflowId,
+                definition: parsedDefinition,
+            });
+            if (done.data.type === "workflow" && done.data.workflow) {
+                const text = formatWorkflowResponse(done, "Caddie generated a workflow definition:\n", "1. Review the definition and fill in any incomplete fields\n2. Use b3os_validate_workflow to check for errors\n3. Use b3os_create_workflow or b3os_update_workflow to save it");
+                return { content: [{ type: "text", text }] };
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: formatCaddieBlocksForCLI(done.data.message || "Caddie did not return a workflow or message."),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: `Caddie build failed: ${err instanceof Error ? err.message : err}` }],
+            };
+        }
+    });
+    s.registerTool("b3os_debug_run", {
+        description: `Debug a failed or stuck workflow run using Caddie, the B3OS AI agent.
+Provide a run ID and Caddie will analyze the execution state, identify what went wrong,
+and suggest fixes — potentially returning a corrected workflow definition.
+
+Use this when:
+- A run failed and you want to understand why
+- A run is stuck in "running" or "waiting" status
+- You need help fixing a workflow based on runtime errors
+
+Caddie receives the full run context (status, timing, execution state per node)
+and provides a diagnosis with actionable next steps.`,
+        inputSchema: {
+            runId: z.string().describe("Run ID to debug (e.g. 'run_abc123')"),
+            message: z.string().optional().describe("Additional context or specific question about the failure"),
+        },
+    }, async ({ runId, message }) => {
+        try {
+            validateRunId(runId);
+            auditLog("CADDIE_DEBUG", `run ${runId}`);
+            // Fetch run details
+            const run = await request(`/v1/runs/${runId}`);
+            if (!run)
+                throw new Error(`Run ${runId} not found`);
+            // Build debug prompt with run context
+            const contextParts = [];
+            contextParts.push(`Debug this workflow run:`);
+            contextParts.push(`- Run ID: ${run.id}`);
+            contextParts.push(`- Status: ${run.status}`);
+            contextParts.push(`- Workflow ID: ${run.workflowId}`);
+            contextParts.push(`- Workflow Version: ${run.workflowVersion}`);
+            if (run.startedAt)
+                contextParts.push(`- Started: ${run.startedAt}`);
+            if (run.finishedAt)
+                contextParts.push(`- Finished: ${run.finishedAt}`);
+            if (run.triggerSource)
+                contextParts.push(`- Trigger: ${run.triggerSource}`);
+            if (run.executionState) {
+                // Truncate to avoid blowing Caddie's token budget on large execution states
+                const stateJson = JSON.stringify(run.executionState, null, 2);
+                contextParts.push(`\nExecution state:\n${stateJson.length > 30_000 ? stateJson.slice(0, 30_000) + "\n...(truncated)" : stateJson}`);
+            }
+            if (message) {
+                contextParts.push(`\nUser context: ${message}`);
+            }
+            const debugPrompt = contextParts.join("\n");
+            const apiKey = getApiKey();
+            const serverUrl = getServerUrl();
+            const done = await consumeCaddieStream(apiKey, serverUrl, {
+                message: debugPrompt,
+                workflowId: run.workflowId,
+            });
+            if (done.data.type === "workflow" && done.data.workflow) {
+                const text = formatWorkflowResponse(done, `Caddie diagnosed run ${runId} and produced a fixed definition:\n`, `1. Review the fixed definition\n2. Use b3os_validate_workflow to verify\n3. Use b3os_update_workflow to save it to workflow ${run.workflowId}`);
+                return { content: [{ type: "text", text }] };
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: formatCaddieBlocksForCLI(done.data.message || `Caddie analyzed run ${runId} but did not return a diagnosis.`, "b3os_debug_run"),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: `Caddie debug failed: ${err instanceof Error ? err.message : err}` }],
+            };
+        }
+    });
+}

package/dist/tools/catalog.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerCatalogTools(s: McpServer): void;

package/dist/tools/catalog.js

@@ -0,0 +1,151 @@
+import { z } from "zod";
+import { request, truncateResponse } from "../client.js";
+import { ACTION_TYPE_RE } from "./shared.js";
+export function registerCatalogTools(s) {
+    s.registerTool("b3os_list_actions", {
+        description: `Browse the B3OS action catalog. Returns all available actions that can be used as
+workflow nodes. Filter by tags (e.g. "defi", "social", "data").
+
+For keyword search, use b3os_search_actions instead — it's faster and more relevant.`,
+        inputSchema: {
+            tags: z.string().optional().describe("Filter by tags (comma-separated)"),
+            limit: z
+                .number()
+                .optional()
+                .describe("Max actions to return (default: 50). Use b3os_search_actions for targeted results."),
+        },
+    }, async ({ tags, limit }) => {
+        const params = { summary: "true" };
+        if (tags)
+            params.tags = tags;
+        const actions = await request("/v1/actions", { params, noAuth: true });
+        const allActions = actions || [];
+        const safeLimit = limit ?? 50;
+        const truncated = allActions.length > safeLimit;
+        const items = (truncated ? allActions.slice(0, safeLimit) : allActions).map(a => ({
+            type: a.type,
+            name: a.name,
+            description: a.description,
+            category: a.category,
+            tags: a.tags,
+            requiresGas: a.requiresGas,
+            connector: a.connector?.type,
+        }));
+        const note = truncated
+            ? `\n\nShowing ${safeLimit} of ${allActions.length}. Use b3os_search_actions for targeted results.`
+            : "";
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(items, null, 2) + note,
+                },
+            ],
+        };
+    });
+    s.registerTool("b3os_search_actions", {
+        description: `Search for B3OS actions by keyword. Uses hybrid search (keyword + semantic) to
+find the most relevant actions for your workflow. Returns top matches with name,
+description, category, and tags.
+
+Use this FIRST when building a workflow to find the right action types. Then use
+b3os_get_action to get the full payload/result schemas for the actions you choose.
+
+Examples: "send slack message", "swap tokens", "fetch token price", "google sheets"`,
+        inputSchema: {
+            query: z.string().min(1).describe("Search query (e.g. 'send slack message', 'token price')"),
+            limit: z.number().optional().describe("Max results (default: 10)"),
+        },
+    }, async ({ query, limit }) => {
+        const safeLimit = Math.min(limit || 10, 50);
+        const params = {
+            q: query,
+            types: "action",
+            limit: String(safeLimit),
+        };
+        try {
+            const results = await request("/v1/search", { params });
+            const hits = results?.results || [];
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: hits.length > 0
+                            ? JSON.stringify(hits.map(h => ({
+                                type: h.id,
+                                name: h.name,
+                                description: h.description,
+                                category: h.category,
+                                tags: h.tags,
+                            })), null, 2)
+                            : `No actions found for "${query}". Try broader terms or use b3os_list_actions to browse all.`,
+                    },
+                ],
+            };
+        }
+        catch {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Search unavailable — use b3os_list_actions to browse the full catalog instead.`,
+                    },
+                ],
+            };
+        }
+    });
+    s.registerTool("b3os_get_action", {
+        description: `Get full details of a specific action, including its payload schema (input fields)
+and result schema (output fields). Use the 'type' field from search results
+(e.g. "coingecko-get-token-price", "send-erc20-token", "slack-send-message").
+
+Read the payload schema to understand what fields to set in the node's payload,
+and the result schema to understand what data flows to downstream nodes.`,
+        inputSchema: { type: z.string().describe("Action type identifier (e.g. 'coingecko-get-token-price')") },
+    }, async ({ type }) => {
+        if (!ACTION_TYPE_RE.test(type)) {
+            throw new Error(`Invalid action type format: "${type}". Use b3os_search_actions to find valid types.`);
+        }
+        const action = await request(`/v1/actions/${type}`, { noAuth: true });
+        if (!action)
+            throw new Error(`Action "${type}" not found`);
+        return { content: [{ type: "text", text: truncateResponse(JSON.stringify(action, null, 2)) }] };
+    });
+    s.registerTool("b3os_list_triggers", {
+        description: `Browse available trigger types. Triggers start workflow execution — schedules (cron),
+webhooks, blockchain events, manual triggers, etc. Filter by tags.`,
+        inputSchema: { tags: z.string().optional().describe("Filter by tags (comma-separated)") },
+    }, async ({ tags }) => {
+        const params = { summary: "true" };
+        if (tags)
+            params.tags = tags;
+        const triggers = await request("/v1/triggers", { params, noAuth: true });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify((triggers || []).map(t => ({
+                        type: t.type,
+                        name: t.name,
+                        description: t.description,
+                        tags: t.tags,
+                        connector: t.connector?.type,
+                    })), null, 2),
+                },
+            ],
+        };
+    });
+    s.registerTool("b3os_get_trigger", {
+        description: `Get full details of a specific trigger type, including its payload schema.
+Use the 'type' field from b3os_list_triggers (e.g. "cronjob", "webhook").`,
+        inputSchema: { type: z.string().describe("Trigger type identifier (e.g. 'cronjob')") },
+    }, async ({ type }) => {
+        if (!ACTION_TYPE_RE.test(type)) {
+            throw new Error(`Invalid trigger type format: "${type}". Use b3os_list_triggers to browse valid types.`);
+        }
+        const trigger = await request(`/v1/triggers/${type}`, { noAuth: true });
+        if (!trigger)
+            throw new Error(`Trigger "${type}" not found`);
+        return { content: [{ type: "text", text: truncateResponse(JSON.stringify(trigger, null, 2)) }] };
+    });
+}

package/dist/tools/connectors.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerConnectorTools(s: McpServer): void;

package/dist/tools/connectors.js

@@ -0,0 +1,200 @@
+import { z } from "zod";
+import { ApiError, request, truncateResponse } from "../client.js";
+import { validateOrgId } from "./shared.js";
+export function registerConnectorTools(s) {
+    s.registerTool("b3os_list_wallets", {
+        description: `List wallets for the organization. Wallets are blockchain addresses managed by B3OS
+(HSM-backed). Useful for workflows that send tokens or interact with DeFi protocols.
+
+Requires orgId — call b3os_whoami first to get it.`,
+        inputSchema: { orgId: z.string().describe("Organization ID from b3os_whoami") },
+    }, async ({ orgId }) => {
+        validateOrgId(orgId);
+        const allWallets = [];
+        const limit = 50;
+        const maxPages = 20;
+        const deadline = Date.now() + 30_000;
+        let offset = 0;
+        for (let page = 0; page < maxPages; page++) {
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                break;
+            const data = await request(`/v1/organizations/${orgId}/wallets`, {
+                params: { limit: String(limit), offset: String(offset) },
+                timeout: Math.max(remaining, 1000),
+            });
+            const items = data?.items || [];
+            allWallets.push(...items);
+            if (!data?.hasMore || items.length === 0)
+                break;
+            offset += items.length;
+        }
+        const text = JSON.stringify(allWallets.map(w => ({
+            id: w.id,
+            name: w.name,
+            address: w.address,
+            isDefault: w.isDefault,
+        })), null, 2);
+        return { content: [{ type: "text", text: truncateResponse(text) }] };
+    });
+    s.registerTool("b3os_list_connectors", {
+        description: `List configured connectors (OAuth integrations) for the organization. Connectors are
+credentials for external services — Slack, Discord, Google Sheets, wallets, etc.
+
+Use this to discover which connectors are available before building workflows. The
+connector ID is needed for workflow nodes that interact with external services:
+  "connector": { "type": "slack", "id": "conn_abc123" }
+
+Without this tool, you'd have to use placeholder connector references.`,
+    }, async () => {
+        const data = await request("/v1/connectors", {
+            params: { limit: "100" },
+        });
+        const connectors = data?.items || [];
+        if (connectors.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "No connectors configured yet.\n\nConnectors link workflows to external services (Slack, Telegram, Gmail, wallets, etc.). Set up your first connector at: https://b3os.org/connectors",
+                    },
+                ],
+            };
+        }
+        const text = JSON.stringify(connectors.map(c => ({
+            id: c.id,
+            name: c.name,
+            type: c.type,
+            provider: c.provider,
+        })), null, 2);
+        return { content: [{ type: "text", text: truncateResponse(text) }] };
+    });
+    s.registerTool("b3os_list_telegram_chats", {
+        description: `List verified Telegram chats (DMs, groups, channels) for a connector. Use this to
+discover available chatId values before building workflows with send-telegram-message.
+
+Returns chatId, chatTitle, chatType (private/group/supergroup/channel), and chatUsername.
+Filter by connectorId to see chats for a specific Telegram bot.
+
+Call b3os_list_connectors first to find telegram-bot connector IDs.`,
+        inputSchema: {
+            connectorId: z.string().optional().describe("Filter by telegram-bot connector ID (from b3os_list_connectors)"),
+            query: z.string().optional().describe("Search query to filter chats by title or username"),
+        },
+    }, async ({ connectorId, query }) => {
+        const params = { limit: "50", offset: "0" };
+        if (connectorId)
+            params.connector_id = connectorId;
+        if (query)
+            params.query = query;
+        const data = await request("/v1/telegram-bot/chats", { params });
+        const chats = data?.items || [];
+        if (chats.length === 0) {
+            const hint = connectorId
+                ? `No Telegram chats found for connector ${connectorId}. Make sure:\n1. The Telegram bot is running\n2. Users have sent /start to the bot\n3. The bot has been added to any target groups`
+                : "No Telegram chats found. Set up a telegram-bot connector at https://b3os.org/connectors first, then send /start to the bot in Telegram.";
+            return { content: [{ type: "text", text: hint }] };
+        }
+        const text = JSON.stringify(chats.map(c => ({
+            chatId: c.chatId,
+            chatTitle: c.chatTitle,
+            chatType: c.chatType,
+            chatUsername: c.chatUsername,
+            connectorId: c.connectorId,
+            connectorName: c.connectorName,
+        })), null, 2);
+        return { content: [{ type: "text", text: truncateResponse(text) }] };
+    });
+    s.registerTool("b3os_list_slack_channels", {
+        description: `List Slack channels available to a connector. Use this to discover channel IDs
+before building workflows with slack-send-message or slack-post-message.
+
+Returns channel id, name, type (public/private), and member count.
+Requires a slack connector ID — call b3os_list_connectors first.`,
+        inputSchema: {
+            connectorId: z.string().describe("Slack connector ID (from b3os_list_connectors)"),
+        },
+    }, async ({ connectorId }) => {
+        const seen = new Set();
+        const allChannels = [];
+        const maxPages = 3;
+        let cursor;
+        for (let page = 0; page < maxPages; page++) {
+            let data;
+            try {
+                const inputs = { limit: 1000 };
+                if (cursor)
+                    inputs.cursor = cursor;
+                data = await request("/v1/actions/slack-list-channels/test", {
+                    method: "POST",
+                    body: {
+                        inputs,
+                        connector: { id: connectorId, type: "slack" },
+                    },
+                });
+            }
+            catch (err) {
+                if (err instanceof ApiError && err.status === 400) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Slack connector "${connectorId}" not found. Run b3os_list_connectors to see available connectors, or set up a new Slack connector at: https://b3os.org/connectors`,
+                            },
+                        ],
+                    };
+                }
+                // Surface transient errors instead of silently returning empty results
+                const msg = err instanceof Error ? err.message : String(err);
+                return {
+                    content: [{ type: "text", text: `Failed to fetch Slack channels: ${msg}` }],
+                };
+            }
+            const ret = data?.result?.data?.ret;
+            if (!ret || typeof ret !== "object")
+                break;
+            const channels = ret.channels;
+            let newCount = 0;
+            if (Array.isArray(channels)) {
+                for (const ch of channels) {
+                    if (ch &&
+                        typeof ch.id === "string" &&
+                        typeof ch.name === "string" &&
+                        !ch.is_archived &&
+                        ch.num_members > 0 &&
+                        !seen.has(ch.id)) {
+                        seen.add(ch.id);
+                        allChannels.push({
+                            id: ch.id,
+                            name: ch.name,
+                            is_private: ch.is_private || ch.is_group,
+                            num_members: ch.num_members,
+                        });
+                        newCount++;
+                    }
+                }
+            }
+            const nextCursor = ret.next_cursor;
+            if (!nextCursor || typeof nextCursor !== "string" || newCount === 0)
+                break;
+            cursor = nextCursor;
+        }
+        if (allChannels.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `No Slack channels found for connector ${connectorId}. Make sure the B3OS Slack app has been added to channels in your workspace.`,
+                    },
+                ],
+            };
+        }
+        const text = JSON.stringify(allChannels.map(c => ({
+            id: c.id,
+            name: c.name,
+            type: c.is_private ? "private" : "public",
+            members: c.num_members,
+        })), null, 2);
+        return { content: [{ type: "text", text: truncateResponse(text) }] };
+    });
+}

package/dist/tools/database.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerDatabaseTools(s: McpServer): void;

package/dist/tools/database.js

@@ -0,0 +1,66 @@
+import { z } from "zod";
+import { request, truncateResponse } from "../client.js";
+import { validateOrgId } from "./shared.js";
+export function registerDatabaseTools(s) {
+    s.registerTool("b3os_list_tables", {
+        description: `List all tables in the organization's database.
+
+Each org gets one auto-provisioned database. Use this to discover existing tables
+before creating new ones or writing queries. Requires orgId from b3os_whoami.`,
+        inputSchema: { orgId: z.string().describe("Organization ID from b3os_whoami") },
+    }, async ({ orgId }) => {
+        validateOrgId(orgId);
+        const data = await request(`/v1/organizations/${orgId}/database/tables`);
+        const tables = data?.tables || [];
+        if (tables.length === 0) {
+            return { content: [{ type: "text", text: "No tables found. The database is empty." }] };
+        }
+        return {
+            content: [{ type: "text", text: tables.map(t => t.name).join("\n") }],
+        };
+    });
+    s.registerTool("b3os_get_table_schema", {
+        description: `Get the column definitions for a specific table in the org's database.
+
+Returns each column's name, type, constraints (NOT NULL, PRIMARY KEY), and default value.
+Use this to understand table structure before writing queries.`,
+        inputSchema: {
+            orgId: z.string().describe("Organization ID from b3os_whoami"),
+            tableName: z.string().describe("Table name to inspect"),
+        },
+    }, async ({ orgId, tableName }) => {
+        validateOrgId(orgId);
+        const data = await request(`/v1/organizations/${orgId}/database/tables/${encodeURIComponent(tableName)}`);
+        const columns = data?.columns || [];
+        const text = JSON.stringify(columns, null, 2);
+        return { content: [{ type: "text", text }] };
+    });
+    s.registerTool("b3os_query_database", {
+        description: `Execute SQL against the organization's database (SQLite-compatible).
+
+Supported statements: SELECT, INSERT, UPDATE, DELETE, CREATE TABLE, ALTER TABLE, DROP TABLE.
+Use parameterized queries with ? placeholders to prevent SQL injection.
+
+Returns:
+- SELECT: { rows: [...], rowsAffected: 0 }
+- INSERT/UPDATE/DELETE: { rows: [], rowsAffected: N, lastRowId: N }
+
+Examples:
+- SELECT * FROM budgets WHERE workflow_id = ?  (params: ["my-workflow"])
+- CREATE TABLE budgets (workflow_id TEXT PRIMARY KEY, spent REAL DEFAULT 0)
+- INSERT INTO budgets (workflow_id, spent) VALUES (?, ?)  (params: ["wf1", 10.5])`,
+        inputSchema: {
+            orgId: z.string().describe("Organization ID from b3os_whoami"),
+            sql: z.string().describe("SQL statement to execute"),
+            params: z.array(z.any()).optional().describe("Parameterized query values (for ? placeholders)"),
+        },
+    }, async ({ orgId, sql, params }) => {
+        validateOrgId(orgId);
+        const data = await request(`/v1/organizations/${orgId}/database/query`, {
+            method: "POST",
+            body: { sql, params: params || [] },
+        });
+        const text = JSON.stringify(data, null, 2);
+        return { content: [{ type: "text", text: truncateResponse(text) }] };
+    });
+}

package/dist/tools/lookups.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerLookupTools(s: McpServer): void;