@formmy.app/mcp-server 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerAgentTools } from "./tools/agents.js";
+import { registerChatTools } from "./tools/chat.js";
+import { registerDocumentTools } from "./tools/documents.js";
+import { registerConversationTools } from "./tools/conversations.js";
+const server = new McpServer({
+    name: "formmy",
+    version: "0.1.0",
+});
+registerAgentTools(server);
+registerChatTools(server);
+registerDocumentTools(server);
+registerConversationTools(server);
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/sdk-client.d.ts

@@ -0,0 +1,36 @@
+/**
+ * HTTP client for Formmy SDK API
+ * Wraps all calls to /api/v2/sdk with proper auth
+ */
+export declare function listAgents(): Promise<unknown>;
+export declare function getAgent(agentId: string): Promise<unknown>;
+export declare function createAgent(data: {
+    name: string;
+    instructions?: string;
+    welcomeMessage?: string;
+    model?: string;
+}): Promise<unknown>;
+export declare function updateAgent(agentId: string, data: {
+    name?: string;
+    instructions?: string;
+    customInstructions?: string;
+    welcomeMessage?: string;
+    model?: string;
+}): Promise<unknown>;
+export declare function chatWithAgent(agentId: string, message: string, sessionId?: string): Promise<string>;
+export declare function addDocument(agentId: string, title: string, content: string): Promise<unknown>;
+export declare function listDocuments(agentId: string): Promise<unknown>;
+export declare function getDocument(documentId: string): Promise<unknown>;
+export declare function searchDocuments(agentId: string, query: string): Promise<unknown>;
+export declare function updateDocument(documentId: string, data: {
+    title?: string;
+    content?: string;
+}): Promise<unknown>;
+export declare function deleteDocument(documentId: string): Promise<unknown>;
+export declare function listConversations(agentId: string): Promise<unknown>;
+export declare function getConversation(conversationId: string): Promise<unknown>;
+export declare function setConversationStatus(conversationId: string, label: string, color: string): Promise<unknown>;
+export declare function addConversationTag(conversationId: string, label: string, color: string, comment?: string): Promise<unknown>;
+export declare function removeConversationTag(conversationId: string, tagLabel: string): Promise<unknown>;
+export declare function shareAgent(agentId: string, email: string, role?: string): Promise<unknown>;
+export declare function connectIntegration(agentId: string, integration: string, config: Record<string, string>): Promise<unknown>;

package/dist/sdk-client.js

@@ -0,0 +1,177 @@
+/**
+ * HTTP client for Formmy SDK API
+ * Wraps all calls to /api/v2/sdk with proper auth
+ */
+const API_URL = process.env.FORMMY_API_URL || "https://formmy.app";
+const SECRET_KEY = process.env.FORMMY_SECRET_KEY || "";
+if (!SECRET_KEY) {
+    console.error("[formmy-mcp] FORMMY_SECRET_KEY is required");
+}
+async function sdkFetch(intent, options = {}) {
+    const { method = "GET", params = {}, body } = options;
+    const url = new URL(`${API_URL}/api/v2/sdk`);
+    url.searchParams.set("intent", intent);
+    for (const [k, v] of Object.entries(params)) {
+        url.searchParams.set(k, v);
+    }
+    const headers = {
+        "X-Secret-Key": SECRET_KEY,
+    };
+    if (body) {
+        headers["Content-Type"] = "application/json";
+    }
+    const res = await fetch(url.toString(), {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    const data = await res.json();
+    if (!res.ok) {
+        const msg = data.error || `SDK error ${res.status}`;
+        throw new Error(msg);
+    }
+    return data;
+}
+// --- Agents ---
+export async function listAgents() {
+    return sdkFetch("agents.list");
+}
+export async function getAgent(agentId) {
+    return sdkFetch("agents.get", { params: { agentId } });
+}
+export async function createAgent(data) {
+    return sdkFetch("agents.create", { method: "POST", body: data });
+}
+export async function updateAgent(agentId, data) {
+    return sdkFetch("agents.update", {
+        method: "POST",
+        params: { agentId },
+        body: data,
+    });
+}
+// --- Chat ---
+export async function chatWithAgent(agentId, message, sessionId) {
+    const sid = sessionId || `mcp_${Date.now()}`;
+    const res = await fetch(`${API_URL}/api/v2/sdk?intent=chat&agentId=${agentId}`, {
+        method: "POST",
+        headers: {
+            "X-Secret-Key": SECRET_KEY,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+            id: sid,
+            message: {
+                parts: [{ type: "text", text: message }],
+            },
+        }),
+    });
+    if (!res.ok) {
+        const err = await res.json().catch(() => ({}));
+        throw new Error(err.error || `Chat error ${res.status}`);
+    }
+    // Streaming response — collect all text chunks
+    const text = await res.text();
+    // The SDK returns SSE-style data stream, extract text parts
+    const lines = text.split("\n");
+    const parts = [];
+    for (const line of lines) {
+        if (line.startsWith("0:")) {
+            // Vercel AI SDK text token format: 0:"text content"
+            try {
+                parts.push(JSON.parse(line.slice(2)));
+            }
+            catch {
+                // skip malformed
+            }
+        }
+    }
+    return parts.join("") || text;
+}
+// --- Documents ---
+export async function addDocument(agentId, title, content) {
+    return sdkFetch("documents.create", {
+        method: "POST",
+        params: { agentId },
+        body: { title, content },
+    });
+}
+export async function listDocuments(agentId) {
+    return sdkFetch("documents.list", { params: { agentId } });
+}
+export async function getDocument(documentId) {
+    return sdkFetch("documents.get", { params: { documentId } });
+}
+export async function searchDocuments(agentId, query) {
+    return sdkFetch("documents.search", { params: { agentId, query } });
+}
+export async function updateDocument(documentId, data) {
+    return sdkFetch("documents.update", {
+        method: "PUT",
+        params: { documentId },
+        body: data,
+    });
+}
+export async function deleteDocument(documentId) {
+    return sdkFetch("documents.delete", {
+        method: "DELETE",
+        params: { documentId },
+    });
+}
+// --- Conversations ---
+export async function listConversations(agentId) {
+    return sdkFetch("conversations.list", { params: { agentId } });
+}
+export async function getConversation(conversationId) {
+    return sdkFetch("conversations.get", { params: { conversationId } });
+}
+// --- Agent bridge mutations (NANOCLAW_WEBHOOK_SECRET auth) ---
+// Pega a /api/v1/agents/conversations, no a /api/v2/sdk. Usa Bearer con el
+// mismo secret que ya autentica el puente Formmy ↔ NanoClaw bidireccional,
+// para no introducir env nuevas en el droplet de sofi-0.
+const BRIDGE_SECRET = process.env.NANOCLAW_WEBHOOK_SECRET || "";
+async function bridgeFetch(intent, body) {
+    if (!BRIDGE_SECRET) {
+        throw new Error("NANOCLAW_WEBHOOK_SECRET no está configurado en el entorno");
+    }
+    const url = new URL(`${API_URL}/api/v1/agents/conversations`);
+    url.searchParams.set("intent", intent);
+    const res = await fetch(url.toString(), {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${BRIDGE_SECRET}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify(body),
+    });
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok) {
+        const msg = data.error || `Bridge error ${res.status}`;
+        throw new Error(msg);
+    }
+    return data;
+}
+export async function setConversationStatus(conversationId, label, color) {
+    return bridgeFetch("set_estado", { conversationId, label, color });
+}
+export async function addConversationTag(conversationId, label, color, comment) {
+    return bridgeFetch("add_tag", { conversationId, label, color, comment });
+}
+export async function removeConversationTag(conversationId, tagLabel) {
+    return bridgeFetch("remove_tag", { conversationId, tagLabel });
+}
+// --- Sharing ---
+export async function shareAgent(agentId, email, role) {
+    return sdkFetch("agents.share", {
+        method: "POST",
+        params: { agentId },
+        body: { email, role },
+    });
+}
+// --- Integrations ---
+export async function connectIntegration(agentId, integration, config) {
+    return sdkFetch("integrations.connect", {
+        method: "POST",
+        params: { agentId },
+        body: { integration, config },
+    });
+}

package/dist/tools/agents.d.ts

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

package/dist/tools/agents.js

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import * as sdk from "../sdk-client.js";
+export function registerAgentTools(server) {
+    server.tool("list_agents", "List all Formmy agents for the authenticated user", {}, async () => {
+        const result = await sdk.listAgents();
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool("get_agent", "Get details of a specific Formmy agent", { agentId: z.string().describe("Agent ID or slug") }, async ({ agentId }) => {
+        const result = await sdk.getAgent(agentId);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool("create_agent", "Create a new Formmy agent/chatbot", {
+        name: z.string().describe("Agent name"),
+        instructions: z.string().optional().describe("System prompt / instructions"),
+        welcomeMessage: z.string().optional().describe("Welcome message shown to users"),
+        model: z.string().optional().describe("AI model (e.g. gpt-4o-mini, gpt-4.1-mini, claude-3-5-haiku-latest)"),
+    }, async (params) => {
+        const result = await sdk.createAgent(params);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool("update_agent", "Update an existing Formmy agent", {
+        agentId: z.string().describe("Agent ID or slug"),
+        name: z.string().optional().describe("New name"),
+        instructions: z.string().optional().describe("New system prompt"),
+        customInstructions: z.string().optional().describe("Additional custom instructions"),
+        welcomeMessage: z.string().optional().describe("New welcome message"),
+        model: z.string().optional().describe("New AI model"),
+    }, async ({ agentId, ...data }) => {
+        const result = await sdk.updateAgent(agentId, data);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool("share_agent", "Share a Formmy agent with another user by email. Creates a permission so they can see and manage the agent.", {
+        agentId: z.string().describe("Agent ID or slug"),
+        email: z.string().describe("Email of the user to share with"),
+        role: z.enum(["VIEWER", "EDITOR", "ADMIN"]).optional().describe("Role to grant (default: VIEWER)"),
+    }, async ({ agentId, email, role }) => {
+        const result = await sdk.shareAgent(agentId, email, role);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool("connect_integration", "Connect an external service (e.g. EasyBits DB) to a Formmy agent. The agent gets tools to interact with the service at chat time.", {
+        agentId: z.string().describe("Agent ID or slug"),
+        integration: z.string().describe("Integration name (e.g. 'easybits')"),
+        config: z.record(z.string()).describe("Integration config (e.g. { apiKey, dbId })"),
+    }, async ({ agentId, integration, config }) => {
+        const result = await sdk.connectIntegration(agentId, integration, config);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+}

package/dist/tools/chat.d.ts

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

package/dist/tools/chat.js

@@ -0,0 +1,12 @@
+import { z } from "zod";
+import * as sdk from "../sdk-client.js";
+export function registerChatTools(server) {
+    server.tool("chat_with_agent", "Send a message to a Formmy agent and get the full response (non-streaming)", {
+        agentId: z.string().describe("Agent ID or slug"),
+        message: z.string().describe("Message to send"),
+        sessionId: z.string().optional().describe("Session ID for conversation continuity"),
+    }, async ({ agentId, message, sessionId }) => {
+        const response = await sdk.chatWithAgent(agentId, message, sessionId);
+        return { content: [{ type: "text", text: response }] };
+    });
+}

package/dist/tools/conversations.d.ts

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

package/dist/tools/conversations.js

@@ -0,0 +1,40 @@
+import { z } from "zod";
+import * as sdk from "../sdk-client.js";
+export function registerConversationTools(server) {
+    server.tool("list_conversations", "List conversations for a Formmy agent", {
+        agentId: z.string().describe("Agent ID or slug"),
+    }, async ({ agentId }) => {
+        const result = await sdk.listConversations(agentId);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool("get_conversation", "Get a conversation with its messages", {
+        conversationId: z.string().describe("Conversation ID"),
+    }, async ({ conversationId }) => {
+        const result = await sdk.getConversation(conversationId);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool("set_conversation_status", "Set the CRM status (estado) of a conversation. Use when the user signals a clear state change: payment confirmed → 'Pago confirmado' (#10B981), needs human → 'Solo operador' (#3B82F6), in progress → 'Atendiendo' (#F59E0B), resolved → 'Atendido' (#10B981). label is free-form text; color must be a hex string. The operator sees the new chip in the conversations list immediately.", {
+        conversationId: z.string().describe("Conversation ID"),
+        label: z.string().describe("Status label, e.g. 'Pago confirmado', 'Solo operador'"),
+        color: z.string().describe("Hex color, e.g. '#10B981' (green), '#3B82F6' (blue), '#F59E0B' (amber), '#EF4444' (red)"),
+    }, async ({ conversationId, label, color }) => {
+        const result = await sdk.setConversationStatus(conversationId, label, color);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool("add_conversation_tag", "Add a CRM tag to a conversation. Use to mark categorical attributes the operator should see at a glance: 'VIP', 'lead', 'urgente', 'cotización', etc. label is free-form; color is hex. Optional comment is internal note (not shown to the client). Returns the updated tag list.", {
+        conversationId: z.string().describe("Conversation ID"),
+        label: z.string().describe("Tag label, e.g. 'VIP', 'lead', 'urgente'"),
+        color: z.string().describe("Hex color, e.g. '#A855F7' (purple/VIP), '#10B981' (green/lead), '#EF4444' (red/urgente)"),
+        comment: z.string().optional().describe("Optional internal note about why this tag was applied"),
+    }, async ({ conversationId, label, color, comment }) => {
+        const result = await sdk.addConversationTag(conversationId, label, color, comment);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool("remove_conversation_tag", "Remove a CRM tag from a conversation by its label. Case-insensitive match.", {
+        conversationId: z.string().describe("Conversation ID"),
+        tagLabel: z.string().describe("Label of the tag to remove"),
+    }, async ({ conversationId, tagLabel }) => {
+        const result = await sdk.removeConversationTag(conversationId, tagLabel);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+}

package/dist/tools/documents.d.ts

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

package/dist/tools/documents.js

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import * as sdk from "../sdk-client.js";
+export function registerDocumentTools(server) {
+    server.tool("add_document", "Add a RAG document/knowledge base entry to a Formmy agent", {
+        agentId: z.string().describe("Agent ID or slug"),
+        title: z.string().describe("Document title"),
+        content: z.string().describe("Document content (text, markdown, etc.)"),
+    }, async ({ agentId, title, content }) => {
+        const result = await sdk.addDocument(agentId, title, content);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool("list_documents", "List all RAG documents for a Formmy agent", {
+        agentId: z.string().describe("Agent ID or slug"),
+    }, async ({ agentId }) => {
+        const result = await sdk.listDocuments(agentId);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool("get_document", "Get a specific RAG document with its full content", {
+        documentId: z.string().describe("Document ID"),
+    }, async ({ documentId }) => {
+        const result = await sdk.getDocument(documentId);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool("search_documents", "Semantic search across an agent's RAG documents", {
+        agentId: z.string().describe("Agent ID or slug"),
+        query: z.string().describe("Search query"),
+    }, async ({ agentId, query }) => {
+        const result = await sdk.searchDocuments(agentId, query);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool("update_document", "Update an existing RAG document's title or content", {
+        documentId: z.string().describe("Document ID"),
+        title: z.string().optional().describe("New title"),
+        content: z.string().optional().describe("New content"),
+    }, async ({ documentId, ...data }) => {
+        const result = await sdk.updateDocument(documentId, data);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool("delete_document", "Delete a RAG document from an agent", {
+        documentId: z.string().describe("Document ID"),
+    }, async ({ documentId }) => {
+        const result = await sdk.deleteDocument(documentId);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@formmy.app/mcp-server",
+  "version": "0.2.0",
+  "description": "MCP server for managing Formmy agents via Claude Code",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "formmy-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3",
+    "@types/node": "^22.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerAgentTools } from "./tools/agents.js";
+import { registerChatTools } from "./tools/chat.js";
+import { registerDocumentTools } from "./tools/documents.js";
+import { registerConversationTools } from "./tools/conversations.js";
+
+const server = new McpServer({
+  name: "formmy",
+  version: "0.1.0",
+});
+
+registerAgentTools(server);
+registerChatTools(server);
+registerDocumentTools(server);
+registerConversationTools(server);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/src/sdk-client.ts

@@ -0,0 +1,269 @@
+/**
+ * HTTP client for Formmy SDK API
+ * Wraps all calls to /api/v2/sdk with proper auth
+ */
+
+const API_URL = process.env.FORMMY_API_URL || "https://formmy.app";
+const SECRET_KEY = process.env.FORMMY_SECRET_KEY || "";
+
+if (!SECRET_KEY) {
+  console.error("[formmy-mcp] FORMMY_SECRET_KEY is required");
+}
+
+async function sdkFetch(
+  intent: string,
+  options: {
+    method?: "GET" | "POST" | "PUT" | "DELETE";
+    params?: Record<string, string>;
+    body?: unknown;
+  } = {}
+): Promise<unknown> {
+  const { method = "GET", params = {}, body } = options;
+
+  const url = new URL(`${API_URL}/api/v2/sdk`);
+  url.searchParams.set("intent", intent);
+  for (const [k, v] of Object.entries(params)) {
+    url.searchParams.set(k, v);
+  }
+
+  const headers: Record<string, string> = {
+    "X-Secret-Key": SECRET_KEY,
+  };
+  if (body) {
+    headers["Content-Type"] = "application/json";
+  }
+
+  const res = await fetch(url.toString(), {
+    method,
+    headers,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+
+  const data = await res.json();
+
+  if (!res.ok) {
+    const msg = (data as { error?: string }).error || `SDK error ${res.status}`;
+    throw new Error(msg);
+  }
+
+  return data;
+}
+
+// --- Agents ---
+
+export async function listAgents() {
+  return sdkFetch("agents.list");
+}
+
+export async function getAgent(agentId: string) {
+  return sdkFetch("agents.get", { params: { agentId } });
+}
+
+export async function createAgent(data: {
+  name: string;
+  instructions?: string;
+  welcomeMessage?: string;
+  model?: string;
+}) {
+  return sdkFetch("agents.create", { method: "POST", body: data });
+}
+
+export async function updateAgent(
+  agentId: string,
+  data: {
+    name?: string;
+    instructions?: string;
+    customInstructions?: string;
+    welcomeMessage?: string;
+    model?: string;
+  }
+) {
+  return sdkFetch("agents.update", {
+    method: "POST",
+    params: { agentId },
+    body: data,
+  });
+}
+
+// --- Chat ---
+
+export async function chatWithAgent(
+  agentId: string,
+  message: string,
+  sessionId?: string
+) {
+  const sid = sessionId || `mcp_${Date.now()}`;
+  const res = await fetch(`${API_URL}/api/v2/sdk?intent=chat&agentId=${agentId}`, {
+    method: "POST",
+    headers: {
+      "X-Secret-Key": SECRET_KEY,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      id: sid,
+      message: {
+        parts: [{ type: "text", text: message }],
+      },
+    }),
+  });
+
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({}));
+    throw new Error((err as { error?: string }).error || `Chat error ${res.status}`);
+  }
+
+  // Streaming response — collect all text chunks
+  const text = await res.text();
+  // The SDK returns SSE-style data stream, extract text parts
+  const lines = text.split("\n");
+  const parts: string[] = [];
+  for (const line of lines) {
+    if (line.startsWith("0:")) {
+      // Vercel AI SDK text token format: 0:"text content"
+      try {
+        parts.push(JSON.parse(line.slice(2)));
+      } catch {
+        // skip malformed
+      }
+    }
+  }
+  return parts.join("") || text;
+}
+
+// --- Documents ---
+
+export async function addDocument(
+  agentId: string,
+  title: string,
+  content: string
+) {
+  return sdkFetch("documents.create", {
+    method: "POST",
+    params: { agentId },
+    body: { title, content },
+  });
+}
+
+export async function listDocuments(agentId: string) {
+  return sdkFetch("documents.list", { params: { agentId } });
+}
+
+export async function getDocument(documentId: string) {
+  return sdkFetch("documents.get", { params: { documentId } });
+}
+
+export async function searchDocuments(agentId: string, query: string) {
+  return sdkFetch("documents.search", { params: { agentId, query } });
+}
+
+export async function updateDocument(
+  documentId: string,
+  data: { title?: string; content?: string }
+) {
+  return sdkFetch("documents.update", {
+    method: "PUT",
+    params: { documentId },
+    body: data,
+  });
+}
+
+export async function deleteDocument(documentId: string) {
+  return sdkFetch("documents.delete", {
+    method: "DELETE",
+    params: { documentId },
+  });
+}
+
+// --- Conversations ---
+
+export async function listConversations(agentId: string) {
+  return sdkFetch("conversations.list", { params: { agentId } });
+}
+
+export async function getConversation(conversationId: string) {
+  return sdkFetch("conversations.get", { params: { conversationId } });
+}
+
+// --- Agent bridge mutations (NANOCLAW_WEBHOOK_SECRET auth) ---
+// Pega a /api/v1/agents/conversations, no a /api/v2/sdk. Usa Bearer con el
+// mismo secret que ya autentica el puente Formmy ↔ NanoClaw bidireccional,
+// para no introducir env nuevas en el droplet de sofi-0.
+
+const BRIDGE_SECRET = process.env.NANOCLAW_WEBHOOK_SECRET || "";
+
+async function bridgeFetch(
+  intent: "set_estado" | "add_tag" | "remove_tag",
+  body: Record<string, unknown>,
+): Promise<unknown> {
+  if (!BRIDGE_SECRET) {
+    throw new Error("NANOCLAW_WEBHOOK_SECRET no está configurado en el entorno");
+  }
+  const url = new URL(`${API_URL}/api/v1/agents/conversations`);
+  url.searchParams.set("intent", intent);
+  const res = await fetch(url.toString(), {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${BRIDGE_SECRET}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(body),
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    const msg = (data as { error?: string }).error || `Bridge error ${res.status}`;
+    throw new Error(msg);
+  }
+  return data;
+}
+
+export async function setConversationStatus(
+  conversationId: string,
+  label: string,
+  color: string,
+) {
+  return bridgeFetch("set_estado", { conversationId, label, color });
+}
+
+export async function addConversationTag(
+  conversationId: string,
+  label: string,
+  color: string,
+  comment?: string,
+) {
+  return bridgeFetch("add_tag", { conversationId, label, color, comment });
+}
+
+export async function removeConversationTag(
+  conversationId: string,
+  tagLabel: string,
+) {
+  return bridgeFetch("remove_tag", { conversationId, tagLabel });
+}
+
+// --- Sharing ---
+
+export async function shareAgent(
+  agentId: string,
+  email: string,
+  role?: string
+) {
+  return sdkFetch("agents.share", {
+    method: "POST",
+    params: { agentId },
+    body: { email, role },
+  });
+}
+
+// --- Integrations ---
+
+export async function connectIntegration(
+  agentId: string,
+  integration: string,
+  config: Record<string, string>
+) {
+  return sdkFetch("integrations.connect", {
+    method: "POST",
+    params: { agentId },
+    body: { integration, config },
+  });
+}

package/src/tools/agents.ts

@@ -0,0 +1,85 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import * as sdk from "../sdk-client.js";
+
+export function registerAgentTools(server: McpServer) {
+  server.tool(
+    "list_agents",
+    "List all Formmy agents for the authenticated user",
+    {},
+    async () => {
+      const result = await sdk.listAgents();
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    "get_agent",
+    "Get details of a specific Formmy agent",
+    { agentId: z.string().describe("Agent ID or slug") },
+    async ({ agentId }) => {
+      const result = await sdk.getAgent(agentId);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    "create_agent",
+    "Create a new Formmy agent/chatbot",
+    {
+      name: z.string().describe("Agent name"),
+      instructions: z.string().optional().describe("System prompt / instructions"),
+      welcomeMessage: z.string().optional().describe("Welcome message shown to users"),
+      model: z.string().optional().describe("AI model (e.g. gpt-4o-mini, gpt-4.1-mini, claude-3-5-haiku-latest)"),
+    },
+    async (params) => {
+      const result = await sdk.createAgent(params);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    "update_agent",
+    "Update an existing Formmy agent",
+    {
+      agentId: z.string().describe("Agent ID or slug"),
+      name: z.string().optional().describe("New name"),
+      instructions: z.string().optional().describe("New system prompt"),
+      customInstructions: z.string().optional().describe("Additional custom instructions"),
+      welcomeMessage: z.string().optional().describe("New welcome message"),
+      model: z.string().optional().describe("New AI model"),
+    },
+    async ({ agentId, ...data }) => {
+      const result = await sdk.updateAgent(agentId, data);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    "share_agent",
+    "Share a Formmy agent with another user by email. Creates a permission so they can see and manage the agent.",
+    {
+      agentId: z.string().describe("Agent ID or slug"),
+      email: z.string().describe("Email of the user to share with"),
+      role: z.enum(["VIEWER", "EDITOR", "ADMIN"]).optional().describe("Role to grant (default: VIEWER)"),
+    },
+    async ({ agentId, email, role }) => {
+      const result = await sdk.shareAgent(agentId, email, role);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    "connect_integration",
+    "Connect an external service (e.g. EasyBits DB) to a Formmy agent. The agent gets tools to interact with the service at chat time.",
+    {
+      agentId: z.string().describe("Agent ID or slug"),
+      integration: z.string().describe("Integration name (e.g. 'easybits')"),
+      config: z.record(z.string()).describe("Integration config (e.g. { apiKey, dbId })"),
+    },
+    async ({ agentId, integration, config }) => {
+      const result = await sdk.connectIntegration(agentId, integration, config);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+}

package/src/tools/chat.ts

@@ -0,0 +1,19 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import * as sdk from "../sdk-client.js";
+
+export function registerChatTools(server: McpServer) {
+  server.tool(
+    "chat_with_agent",
+    "Send a message to a Formmy agent and get the full response (non-streaming)",
+    {
+      agentId: z.string().describe("Agent ID or slug"),
+      message: z.string().describe("Message to send"),
+      sessionId: z.string().optional().describe("Session ID for conversation continuity"),
+    },
+    async ({ agentId, message, sessionId }) => {
+      const response = await sdk.chatWithAgent(agentId, message, sessionId);
+      return { content: [{ type: "text", text: response }] };
+    }
+  );
+}

package/src/tools/conversations.ts

@@ -0,0 +1,71 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import * as sdk from "../sdk-client.js";
+
+export function registerConversationTools(server: McpServer) {
+  server.tool(
+    "list_conversations",
+    "List conversations for a Formmy agent",
+    {
+      agentId: z.string().describe("Agent ID or slug"),
+    },
+    async ({ agentId }) => {
+      const result = await sdk.listConversations(agentId);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    "get_conversation",
+    "Get a conversation with its messages",
+    {
+      conversationId: z.string().describe("Conversation ID"),
+    },
+    async ({ conversationId }) => {
+      const result = await sdk.getConversation(conversationId);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    "set_conversation_status",
+    "Set the CRM status (estado) of a conversation. Use when the user signals a clear state change: payment confirmed → 'Pago confirmado' (#10B981), needs human → 'Solo operador' (#3B82F6), in progress → 'Atendiendo' (#F59E0B), resolved → 'Atendido' (#10B981). label is free-form text; color must be a hex string. The operator sees the new chip in the conversations list immediately.",
+    {
+      conversationId: z.string().describe("Conversation ID"),
+      label: z.string().describe("Status label, e.g. 'Pago confirmado', 'Solo operador'"),
+      color: z.string().describe("Hex color, e.g. '#10B981' (green), '#3B82F6' (blue), '#F59E0B' (amber), '#EF4444' (red)"),
+    },
+    async ({ conversationId, label, color }) => {
+      const result = await sdk.setConversationStatus(conversationId, label, color);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    "add_conversation_tag",
+    "Add a CRM tag to a conversation. Use to mark categorical attributes the operator should see at a glance: 'VIP', 'lead', 'urgente', 'cotización', etc. label is free-form; color is hex. Optional comment is internal note (not shown to the client). Returns the updated tag list.",
+    {
+      conversationId: z.string().describe("Conversation ID"),
+      label: z.string().describe("Tag label, e.g. 'VIP', 'lead', 'urgente'"),
+      color: z.string().describe("Hex color, e.g. '#A855F7' (purple/VIP), '#10B981' (green/lead), '#EF4444' (red/urgente)"),
+      comment: z.string().optional().describe("Optional internal note about why this tag was applied"),
+    },
+    async ({ conversationId, label, color, comment }) => {
+      const result = await sdk.addConversationTag(conversationId, label, color, comment);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    "remove_conversation_tag",
+    "Remove a CRM tag from a conversation by its label. Case-insensitive match.",
+    {
+      conversationId: z.string().describe("Conversation ID"),
+      tagLabel: z.string().describe("Label of the tag to remove"),
+    },
+    async ({ conversationId, tagLabel }) => {
+      const result = await sdk.removeConversationTag(conversationId, tagLabel);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+}

package/src/tools/documents.ts

@@ -0,0 +1,82 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import * as sdk from "../sdk-client.js";
+
+export function registerDocumentTools(server: McpServer) {
+  server.tool(
+    "add_document",
+    "Add a RAG document/knowledge base entry to a Formmy agent",
+    {
+      agentId: z.string().describe("Agent ID or slug"),
+      title: z.string().describe("Document title"),
+      content: z.string().describe("Document content (text, markdown, etc.)"),
+    },
+    async ({ agentId, title, content }) => {
+      const result = await sdk.addDocument(agentId, title, content);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    "list_documents",
+    "List all RAG documents for a Formmy agent",
+    {
+      agentId: z.string().describe("Agent ID or slug"),
+    },
+    async ({ agentId }) => {
+      const result = await sdk.listDocuments(agentId);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    "get_document",
+    "Get a specific RAG document with its full content",
+    {
+      documentId: z.string().describe("Document ID"),
+    },
+    async ({ documentId }) => {
+      const result = await sdk.getDocument(documentId);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    "search_documents",
+    "Semantic search across an agent's RAG documents",
+    {
+      agentId: z.string().describe("Agent ID or slug"),
+      query: z.string().describe("Search query"),
+    },
+    async ({ agentId, query }) => {
+      const result = await sdk.searchDocuments(agentId, query);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    "update_document",
+    "Update an existing RAG document's title or content",
+    {
+      documentId: z.string().describe("Document ID"),
+      title: z.string().optional().describe("New title"),
+      content: z.string().optional().describe("New content"),
+    },
+    async ({ documentId, ...data }) => {
+      const result = await sdk.updateDocument(documentId, data);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    "delete_document",
+    "Delete a RAG document from an agent",
+    {
+      documentId: z.string().describe("Document ID"),
+    },
+    async ({ documentId }) => {
+      const result = await sdk.deleteDocument(documentId);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["dist", "node_modules"]
+}