neuron-mcp-server 1.0.0 → 1.1.0

package/src/tools/tools.ts

@@ -0,0 +1,255 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { api, jsonResult, errorResult } from "../client.js";
+
+/**
+ * Register bot integration tools (HTTP APIs, webhooks the bot can call)
+ */
+export function registerToolsTools(server: McpServer): void {
+  // 1. Create Tool
+  server.registerTool(
+    "neuron_create_tool",
+    {
+      title: "Create Tool",
+      description: "Create a custom API tool that the bot can invoke during conversations to fetch external data or trigger actions.",
+      inputSchema: z.object({
+        botId: z.string().describe("Unique identifier (UUID) of the bot to create the tool for"),
+        name: z.string().describe("Human-readable name for the tool"),
+        description: z.string().min(1).max(1000).describe("Description of what the tool does and when the bot should use it"),
+        type: z.enum(["http_api", "webhook", "mcp"]).describe("Type of the tool integration"),
+        config: z.object({
+          endpoint: z.string().optional().describe("Target HTTP endpoint URL for http_api tools"),
+          method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]).optional().describe("HTTP method to use"),
+          headers: z.record(z.string()).optional().describe("HTTP headers to include with each request as key-value pairs"),
+          bodyTemplate: z.string().optional().describe("Handlebars template for the request body, populated with conversation context"),
+          parametersSchema: z.record(z.unknown()).optional().describe("JSON Schema describing the parameters the tool accepts"),
+          mcpServerUrl: z.string().optional().describe("MCP server URL for mcp-type tools"),
+          webhookUrl: z.string().optional().describe("Webhook URL for webhook-type tools"),
+          asyncConfig: z.object({
+            pollingEndpoint: z.string().optional().describe("URL template with {{jobId}} placeholder for polling job status"),
+            pollingIntervalMs: z.number().min(500).max(30000).optional().describe("Milliseconds between poll requests (default: 2000)"),
+            maxPollingMs: z.number().min(5000).max(300000).optional().describe("Maximum time to poll before timeout (default: 120000)"),
+            jobIdPath: z.string().optional().describe("Dot-notation path to extract job ID from initial response (e.g. 'id', 'request_id')"),
+            statusPath: z.string().optional().describe("Dot-notation path to status field in poll response (e.g. 'status')"),
+            completedStatuses: z.array(z.string()).optional().describe("Status values indicating completion (e.g. ['COMPLETED', 'succeeded'])"),
+            failedStatuses: z.array(z.string()).optional().describe("Status values indicating failure (e.g. ['FAILED', 'failed', 'canceled'])"),
+            resultPath: z.string().optional().describe("Dot-notation path to extract final result from completed response (e.g. 'output')"),
+          }).optional().describe("Configuration for async submit-poll-download APIs like fal.ai and Replicate"),
+        }).describe("Tool configuration specifying the endpoint and request details"),
+        authType: z.enum(["none", "api_key", "bearer", "basic", "oauth2"]).optional().describe("Authentication type for the endpoint"),
+        rateLimit: z.number().optional().describe("Maximum number of requests per minute allowed for this tool"),
+        timeoutMs: z.number().optional().describe("Request timeout in milliseconds (default: 30000)"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+      },
+    },
+    async (args) => {
+      const { botId, ...body } = args;
+      const response = await api("POST", `/tools/bot/${botId}`, body);
+
+      if (response.success) {
+        return jsonResult(response.data);
+      } else {
+        return errorResult(response.error || "Failed to create tool");
+      }
+    }
+  );
+
+  // 2. List Tools
+  server.registerTool(
+    "neuron_list_tools",
+    {
+      title: "List Tools",
+      description: "Retrieve all custom API tool integrations configured for a specific bot, including their endpoints and configuration.",
+      inputSchema: z.object({
+        botId: z.string().describe("Unique identifier (UUID) of the bot to list tools for"),
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+      },
+    },
+    async (args) => {
+      const response = await api("GET", `/tools/bot/${args.botId}`);
+
+      if (response.success) {
+        return jsonResult(response.data);
+      } else {
+        return errorResult(response.error || "Failed to list tools");
+      }
+    }
+  );
+
+  // 3. Update Tool
+  server.registerTool(
+    "neuron_update_tool",
+    {
+      title: "Update Tool",
+      description: "Modify an existing custom API tool's configuration, including its endpoint, authentication, or request template.",
+      inputSchema: z.object({
+        id: z.string().describe("Unique identifier (UUID) of the tool to update"),
+        name: z.string().optional().describe("Updated human-readable name for the tool"),
+        description: z.string().optional().describe("Updated description of the tool's purpose"),
+        type: z.enum(["http_api", "webhook", "mcp"]).optional().describe("Updated type of the tool integration"),
+        config: z.object({
+          endpoint: z.string().optional().describe("Updated target HTTP endpoint URL"),
+          method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]).optional().describe("Updated HTTP method"),
+          headers: z.record(z.string()).optional().describe("Updated HTTP headers as key-value pairs"),
+          bodyTemplate: z.string().optional().describe("Updated Handlebars template for the request body"),
+          parametersSchema: z.record(z.unknown()).optional().describe("Updated JSON Schema for tool parameters"),
+          mcpServerUrl: z.string().optional().describe("Updated MCP server URL"),
+          webhookUrl: z.string().optional().describe("Updated webhook URL"),
+          asyncConfig: z.object({
+            pollingEndpoint: z.string().optional().describe("URL template with {{jobId}} placeholder for polling job status"),
+            pollingIntervalMs: z.number().min(500).max(30000).optional().describe("Milliseconds between poll requests (default: 2000)"),
+            maxPollingMs: z.number().min(5000).max(300000).optional().describe("Maximum time to poll before timeout (default: 120000)"),
+            jobIdPath: z.string().optional().describe("Dot-notation path to extract job ID from initial response"),
+            statusPath: z.string().optional().describe("Dot-notation path to status field in poll response"),
+            completedStatuses: z.array(z.string()).optional().describe("Status values indicating completion"),
+            failedStatuses: z.array(z.string()).optional().describe("Status values indicating failure"),
+            resultPath: z.string().optional().describe("Dot-notation path to extract final result from completed response"),
+          }).optional().describe("Configuration for async submit-poll-download APIs"),
+        }).optional().describe("Updated tool configuration"),
+        authType: z.enum(["none", "api_key", "bearer", "basic", "oauth2"]).optional().describe("Updated authentication type"),
+        rateLimit: z.number().optional().describe("Updated maximum requests per minute"),
+        timeoutMs: z.number().optional().describe("Updated request timeout in milliseconds"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+      },
+    },
+    async (args) => {
+      const { id, ...body } = args;
+      const response = await api("PUT", `/tools/${id}`, body);
+
+      if (response.success) {
+        return jsonResult(response.data);
+      } else {
+        return errorResult(response.error || "Failed to update tool");
+      }
+    }
+  );
+
+  // 4. Delete Tool
+  server.registerTool(
+    "neuron_delete_tool",
+    {
+      title: "Delete Tool",
+      description: "Permanently remove a custom API tool integration from a bot. The bot will no longer be able to invoke this tool in conversations.",
+      inputSchema: z.object({
+        id: z.string().describe("Unique identifier (UUID) of the tool to delete"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: true,
+      },
+    },
+    async (args) => {
+      const response = await api("DELETE", `/tools/${args.id}`);
+
+      if (response.success) {
+        return jsonResult(response.data || { message: "Tool deleted successfully" });
+      } else {
+        return errorResult(response.error || "Failed to delete tool");
+      }
+    }
+  );
+
+  // 5. Test Tool
+  server.registerTool(
+    "neuron_test_tool",
+    {
+      title: "Test Tool",
+      description: "Execute a dry-run test of a custom API tool with sample arguments to verify the endpoint responds correctly.",
+      inputSchema: z.object({
+        id: z.string().describe("Unique identifier (UUID) of the tool to test"),
+        args: z.record(z.any()).describe("Sample arguments object to pass to the tool for testing"),
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+      },
+    },
+    async (args) => {
+      const { id, args: testArgs } = args;
+      const response = await api("POST", `/tools/${id}/test`, { args: testArgs });
+
+      if (response.success) {
+        return jsonResult(response.data);
+      } else {
+        return errorResult(response.error || "Tool test failed");
+      }
+    }
+  );
+
+  // 6. Add Tool Secret
+  server.registerTool(
+    "neuron_add_tool_secret",
+    {
+      title: "Add Tool Secret",
+      description: "Store or update a secret credential (API key, token, etc.) for a custom tool integration. Secrets are encrypted at rest.",
+      inputSchema: z.object({
+        id: z.string().describe("Unique identifier (UUID) of the tool to add the secret to"),
+        key: z.string().describe("Secret key name used in templates (e.g., 'API_KEY', 'AUTH_TOKEN')"),
+        value: z.string().describe("Secret value to store securely (will be encrypted)"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+      },
+    },
+    async (args) => {
+      const { id, ...body } = args;
+      const response = await api("POST", `/tools/${id}/secrets`, body);
+
+      if (response.success) {
+        return jsonResult(response.data || { message: "Secret added successfully" });
+      } else {
+        return errorResult(response.error || "Failed to add tool secret");
+      }
+    }
+  );
+
+  // 7. Remove Tool Secret
+  server.registerTool(
+    "neuron_remove_tool_secret",
+    {
+      title: "Remove Tool Secret",
+      description: "Permanently delete a stored secret from a custom tool integration. The tool will lose access to this credential.",
+      inputSchema: z.object({
+        id: z.string().describe("Unique identifier (UUID) of the tool to remove the secret from"),
+        key: z.string().describe("Secret key name to remove (e.g., 'API_KEY', 'AUTH_TOKEN')"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: true,
+      },
+    },
+    async (args) => {
+      const response = await api("DELETE", `/tools/${args.id}/secrets/${args.key}`);
+
+      if (response.success) {
+        return jsonResult(response.data || { message: "Secret removed successfully" });
+      } else {
+        return errorResult(response.error || "Failed to remove tool secret");
+      }
+    }
+  );
+}

package/src/tools/wallets.ts

@@ -0,0 +1,107 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { api, jsonResult, errorResult } from "../client.js";
+
+export function registerWalletTools(server: McpServer): void {
+  server.registerTool(
+    "neuron_wallet_balance",
+    {
+      title: "Wallet Balance",
+      description: "Retrieve the current wallet balance for the organization, including available and pending amounts.",
+      inputSchema: z.object({}),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async () => {
+      try {
+        const result = await api("GET", "/wallets");
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  server.registerTool(
+    "neuron_wallet_transactions",
+    {
+      title: "Wallet Transactions",
+      description: "Retrieve the wallet transaction history for the organization, with optional filtering by transaction type.",
+      inputSchema: z.object({
+        type: z.string().optional().describe("Filter by transaction type: 'credit' or 'debit'"),
+        page: z.number().int().positive().optional().describe("Page number for pagination (default: 1)"),
+        limit: z.number().int().positive().optional().describe("Number of transactions per page (default: 20)"),
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("GET", "/wallets/transactions", undefined, params);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  server.registerTool(
+    "neuron_fund_wallet",
+    {
+      title: "Fund Wallet",
+      description:
+        "Initialize a wallet funding transaction via Paystack. Returns a checkout URL to complete the payment in a browser.",
+      inputSchema: z.object({
+        amount: z.number().int().positive().describe("Amount to fund in the smallest currency unit — kobo for NGN (e.g., 500000 = NGN 5,000)"),
+        email: z.string().email().describe("Email address to receive the payment receipt"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("POST", "/wallets/fund", params);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  server.registerTool(
+    "neuron_verify_wallet_funding",
+    {
+      title: "Verify Wallet Funding",
+      description: "Verify a wallet funding transaction using the Paystack payment reference to confirm the payment was successful.",
+      inputSchema: z.object({
+        reference: z.string().describe("Paystack payment reference returned from the checkout session"),
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("POST", "/wallets/fund/verify", params);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+}

package/src/tools/webhooks.ts

@@ -0,0 +1,166 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { api, jsonResult, errorResult } from "../client.js";
+
+/**
+ * Register webhook tools (inbound webhooks that trigger bot actions)
+ */
+export function registerWebhooksTools(server: McpServer): void {
+  // 1. Create Webhook
+  server.registerTool(
+    "neuron_create_webhook",
+    {
+      title: "Create Webhook",
+      description: "Register a new inbound webhook endpoint that triggers bot actions when called by an external service.",
+      inputSchema: z.object({
+        botId: z.string().describe("Unique identifier (UUID) of the bot to create the webhook for"),
+        name: z.string().describe("Human-readable name for the webhook"),
+        slug: z.string().optional().describe("URL-friendly slug for the webhook endpoint (auto-generated if omitted)"),
+        eventType: z.string().optional().describe("Type of event this webhook handles (e.g., 'order.created', 'payment.received')"),
+        processingPrompt: z.string().optional().describe("Prompt instructions to guide bot processing of incoming webhook data"),
+        isActive: z.boolean().optional().describe("Whether the webhook is active and accepting requests (default: true)"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+      },
+    },
+    async (args) => {
+      const { botId, ...body } = args;
+      const response = await api("POST", `/webhooks/bot/${botId}`, body);
+
+      if (response.success) {
+        return jsonResult(response.data);
+      } else {
+        return errorResult(response.error || "Failed to create webhook");
+      }
+    }
+  );
+
+  // 2. List Webhooks
+  server.registerTool(
+    "neuron_list_webhooks",
+    {
+      title: "List Webhooks",
+      description: "Retrieve all inbound webhooks configured for a specific bot, including their status and configuration.",
+      inputSchema: z.object({
+        botId: z.string().describe("Unique identifier (UUID) of the bot to list webhooks for"),
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+      },
+    },
+    async (args) => {
+      const response = await api("GET", `/webhooks/bot/${args.botId}`);
+
+      if (response.success) {
+        return jsonResult(response.data);
+      } else {
+        return errorResult(response.error || "Failed to list webhooks");
+      }
+    }
+  );
+
+  // 3. Update Webhook
+  server.registerTool(
+    "neuron_update_webhook",
+    {
+      title: "Update Webhook",
+      description: "Modify an existing inbound webhook's configuration, such as its name, event type, or processing prompt.",
+      inputSchema: z.object({
+        id: z.string().describe("Unique identifier (UUID) of the webhook to update"),
+        name: z.string().optional().describe("Updated human-readable name of the webhook"),
+        eventType: z.string().optional().describe("Updated event type this webhook handles"),
+        processingPrompt: z.string().optional().describe("Updated prompt instructions for processing webhook data"),
+        isActive: z.boolean().optional().describe("Whether the webhook should be active and accepting requests"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+      },
+    },
+    async (args) => {
+      const { id, ...body } = args;
+      const response = await api("PUT", `/webhooks/${id}`, body);
+
+      if (response.success) {
+        return jsonResult(response.data);
+      } else {
+        return errorResult(response.error || "Failed to update webhook");
+      }
+    }
+  );
+
+  // 4. Delete Webhook
+  server.registerTool(
+    "neuron_delete_webhook",
+    {
+      title: "Delete Webhook",
+      description: "Permanently remove an inbound webhook from a bot. External services will no longer be able to trigger this endpoint.",
+      inputSchema: z.object({
+        id: z.string().describe("Unique identifier (UUID) of the webhook to delete"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: true,
+      },
+    },
+    async (args) => {
+      const response = await api("DELETE", `/webhooks/${args.id}`);
+
+      if (response.success) {
+        return jsonResult(response.data || { message: "Webhook deleted successfully" });
+      } else {
+        return errorResult(response.error || "Failed to delete webhook");
+      }
+    }
+  );
+
+  // 5. Get Webhook Logs
+  server.registerTool(
+    "neuron_get_webhook_logs",
+    {
+      title: "Get Webhook Logs",
+      description: "Retrieve execution logs for an inbound webhook to monitor incoming requests and debug processing issues.",
+      inputSchema: z.object({
+        id: z.string().describe("Unique identifier (UUID) of the webhook to get logs for"),
+        page: z.number().optional().describe("Page number for pagination (default: 1)"),
+        limit: z.number().optional().describe("Number of log entries per page (default: 20)"),
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+      },
+    },
+    async (args) => {
+      const { id, page, limit } = args;
+      const params: Record<string, string> = {};
+
+      if (page !== undefined) {
+        params.page = String(page);
+      }
+      if (limit !== undefined) {
+        params.limit = String(limit);
+      }
+
+      const response = await api("GET", `/webhooks/${id}/logs`, undefined, params);
+
+      if (response.success) {
+        return jsonResult(response.data);
+      } else {
+        return errorResult(response.error || "Failed to get webhook logs");
+      }
+    }
+  );
+}