@formmy.app/mcp-server 0.2.0 → 0.4.0

package/dist/index.js

@@ -7,7 +7,7 @@ import { registerDocumentTools } from "./tools/documents.js";
 import { registerConversationTools } from "./tools/conversations.js";
 const server = new McpServer({
     name: "formmy",
-    version: "0.1.0",
+    version: "0.3.0",
 });
 registerAgentTools(server);
 registerChatTools(server);

package/dist/sdk-client.d.ts

@@ -29,8 +29,26 @@ export declare function updateDocument(documentId: string, data: {
 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 listConversationEstados(agentId: 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 createOrder(conversationId: string, data: {
+    folio?: string;
+    cliente?: string;
+    tel?: string;
+    total?: number;
+    estatus?: string;
+    status?: "ABIERTA" | "CERRADA";
+    notas?: string;
+    cotizacionUrl?: string;
+    direccionEntrega?: {
+        label?: string;
+        direccion?: string;
+        cp?: string;
+        ciudad?: string;
+        mapsUrl?: 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

@@ -124,6 +124,9 @@ export async function listConversations(agentId) {
 export async function getConversation(conversationId) {
     return sdkFetch("conversations.get", { params: { conversationId } });
 }
+export async function listConversationEstados(agentId) {
+    return sdkFetch("conversations.estados", { params: { agentId } });
+}
 // --- 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,
@@ -159,6 +162,9 @@ export async function addConversationTag(conversationId, label, color, comment)
 export async function removeConversationTag(conversationId, tagLabel) {
     return bridgeFetch("remove_tag", { conversationId, tagLabel });
 }
+export async function createOrder(conversationId, data) {
+    return bridgeFetch("create_order", { conversationId, ...data });
+}
 // --- Sharing ---
 export async function shareAgent(agentId, email, role) {
     return sdkFetch("agents.share", {

package/dist/tools/conversations.js

@@ -13,7 +13,13 @@ export function registerConversationTools(server) {
         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.", {
+    server.tool("list_conversation_estados", "List the valid CRM estados (kanban columns) configured for this agent. ALWAYS call this before set_conversation_status so you move leads within the defined set instead of inventing new labels/colors. Returns an array of { label, color }. Pick the closest matching estado and reuse its exact label and color.", {
+        agentId: z.string().describe("Agent ID or slug"),
+    }, async ({ agentId }) => {
+        const result = await sdk.listConversationEstados(agentId);
+        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. Prefer reusing a label/color from list_conversation_estados. 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)"),
@@ -37,4 +43,40 @@ export function registerConversationTools(server) {
         const result = await sdk.removeConversationTag(conversationId, tagLabel);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
+    server.tool("create_order", "Record an order (cotización/pedido) for a conversation in Formmy, mirroring what is sent to Kommo. It shows in the contact panel's Órdenes accordion, moves the kanban card when `estatus` matches a CRM estado (call list_conversation_estados first), and bumps the conversation to the top. Does NOT replace the Kommo push — call it IN ADDITION. Use when an order/quote is confirmed or its status changes; only the most recent order drives the card and the board value.", {
+        conversationId: z.string().describe("Conversation ID"),
+        folio: z.string().optional().describe("Order folio/number, e.g. '260521-007'"),
+        cliente: z.string().optional().describe("Customer name"),
+        tel: z.string().optional().describe("Contact phone"),
+        total: z
+            .number()
+            .optional()
+            .describe("Order total / budget as a number, e.g. 783"),
+        estatus: z
+            .string()
+            .optional()
+            .describe("Free-form status; match a CRM estado label (list_conversation_estados) so the card moves to that column, e.g. 'Pago a contra entrega'"),
+        status: z
+            .enum(["ABIERTA", "CERRADA"])
+            .optional()
+            .describe("Order lifecycle (default ABIERTA). Use CERRADA when delivered/closed."),
+        notas: z.string().optional().describe("Special instructions / internal notes"),
+        cotizacionUrl: z
+            .string()
+            .optional()
+            .describe("URL to the quote PDF deployed on EasyBits"),
+        direccionEntrega: z
+            .object({
+            label: z.string().optional(),
+            direccion: z.string().optional(),
+            cp: z.string().optional(),
+            ciudad: z.string().optional(),
+            mapsUrl: z.string().optional(),
+        })
+            .optional()
+            .describe("Delivery address snapshot { label, direccion, cp, ciudad, mapsUrl }"),
+    }, async ({ conversationId, ...data }) => {
+        const result = await sdk.createOrder(conversationId, data);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@formmy.app/mcp-server",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "MCP server for managing Formmy agents via Claude Code",
   "type": "module",
   "main": "dist/index.js",

package/src/index.ts

@@ -8,7 +8,7 @@ import { registerConversationTools } from "./tools/conversations.js";
 
 const server = new McpServer({
   name: "formmy",
-  version: "0.1.0",
+  version: "0.3.0",
 });
 
 registerAgentTools(server);

package/src/sdk-client.ts

@@ -184,6 +184,10 @@ export async function getConversation(conversationId: string) {
   return sdkFetch("conversations.get", { params: { conversationId } });
 }
 
+export async function listConversationEstados(agentId: string) {
+  return sdkFetch("conversations.estados", { params: { agentId } });
+}
+
 // --- 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,
@@ -192,7 +196,7 @@ export async function getConversation(conversationId: string) {
 const BRIDGE_SECRET = process.env.NANOCLAW_WEBHOOK_SECRET || "";
 
 async function bridgeFetch(
-  intent: "set_estado" | "add_tag" | "remove_tag",
+  intent: "set_estado" | "add_tag" | "remove_tag" | "create_order",
   body: Record<string, unknown>,
 ): Promise<unknown> {
   if (!BRIDGE_SECRET) {
@@ -240,6 +244,29 @@ export async function removeConversationTag(
   return bridgeFetch("remove_tag", { conversationId, tagLabel });
 }
 
+export async function createOrder(
+  conversationId: string,
+  data: {
+    folio?: string;
+    cliente?: string;
+    tel?: string;
+    total?: number;
+    estatus?: string;
+    status?: "ABIERTA" | "CERRADA";
+    notas?: string;
+    cotizacionUrl?: string;
+    direccionEntrega?: {
+      label?: string;
+      direccion?: string;
+      cp?: string;
+      ciudad?: string;
+      mapsUrl?: string;
+    };
+  },
+) {
+  return bridgeFetch("create_order", { conversationId, ...data });
+}
+
 // --- Sharing ---
 
 export async function shareAgent(

package/src/tools/conversations.ts

@@ -27,9 +27,21 @@ export function registerConversationTools(server: McpServer) {
     }
   );
 
+  server.tool(
+    "list_conversation_estados",
+    "List the valid CRM estados (kanban columns) configured for this agent. ALWAYS call this before set_conversation_status so you move leads within the defined set instead of inventing new labels/colors. Returns an array of { label, color }. Pick the closest matching estado and reuse its exact label and color.",
+    {
+      agentId: z.string().describe("Agent ID or slug"),
+    },
+    async ({ agentId }) => {
+      const result = await sdk.listConversationEstados(agentId);
+      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.",
+    "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. Prefer reusing a label/color from list_conversation_estados. 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'"),
@@ -68,4 +80,48 @@ export function registerConversationTools(server: McpServer) {
       return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     }
   );
+
+  server.tool(
+    "create_order",
+    "Record an order (cotización/pedido) for a conversation in Formmy, mirroring what is sent to Kommo. It shows in the contact panel's Órdenes accordion, moves the kanban card when `estatus` matches a CRM estado (call list_conversation_estados first), and bumps the conversation to the top. Does NOT replace the Kommo push — call it IN ADDITION. Use when an order/quote is confirmed or its status changes; only the most recent order drives the card and the board value.",
+    {
+      conversationId: z.string().describe("Conversation ID"),
+      folio: z.string().optional().describe("Order folio/number, e.g. '260521-007'"),
+      cliente: z.string().optional().describe("Customer name"),
+      tel: z.string().optional().describe("Contact phone"),
+      total: z
+        .number()
+        .optional()
+        .describe("Order total / budget as a number, e.g. 783"),
+      estatus: z
+        .string()
+        .optional()
+        .describe(
+          "Free-form status; match a CRM estado label (list_conversation_estados) so the card moves to that column, e.g. 'Pago a contra entrega'",
+        ),
+      status: z
+        .enum(["ABIERTA", "CERRADA"])
+        .optional()
+        .describe("Order lifecycle (default ABIERTA). Use CERRADA when delivered/closed."),
+      notas: z.string().optional().describe("Special instructions / internal notes"),
+      cotizacionUrl: z
+        .string()
+        .optional()
+        .describe("URL to the quote PDF deployed on EasyBits"),
+      direccionEntrega: z
+        .object({
+          label: z.string().optional(),
+          direccion: z.string().optional(),
+          cp: z.string().optional(),
+          ciudad: z.string().optional(),
+          mapsUrl: z.string().optional(),
+        })
+        .optional()
+        .describe("Delivery address snapshot { label, direccion, cp, ciudad, mapsUrl }"),
+    },
+    async ({ conversationId, ...data }) => {
+      const result = await sdk.createOrder(conversationId, data);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+  );
 }