neuron-mcp-server 1.0.0 → 1.1.0

package/src/tools/blog.ts

@@ -0,0 +1,264 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { api, jsonResult, errorResult } from "../client.js";
+
+/**
+ * Block content vocabulary. The backend (backend/src/lib/blog-blocks.ts) is the
+ * authoritative validator — it rejects malformed blocks with a 400 — so here we
+ * keep a permissive shape and describe the vocabulary richly for the model.
+ */
+const BLOCKS_SCHEMA = z.array(z.record(z.any()));
+
+const BLOCKS_DESCRIPTION = [
+  "Structured layout blocks, rendered top-to-bottom as styled components. Each block is an object with a `type` and its fields:",
+  "- hero: { type:'hero', title, kicker?, subtitle?, imageUrl?, align?:'left'|'center', ctaLabel?, ctaHref? }",
+  "- richText: { type:'richText', markdown }  (full GFM markdown)",
+  "- callout: { type:'callout', variant:'info'|'tip'|'warning'|'success'|'danger', title?, markdown }",
+  "- columns: { type:'columns', ratio?:'1-1'|'1-2'|'2-1', columns:[ [block,...], [block,...] ] }  (exactly 2 columns of leaf blocks; no nested columns)",
+  "- codeCard: { type:'codeCard', language?, filename?, code }",
+  "- imageGrid: { type:'imageGrid', columns?:1|2|3|4, images:[{ url, alt?, caption? }] }",
+  "- quote: { type:'quote', quote, attribution? }",
+  "- embed: { type:'embed', provider:'youtube'|'loom'|'vimeo'|'generic', url, title? }  (paste the normal share URL)",
+  "- cta: { type:'cta', headline, body?, buttonLabel, buttonHref, secondaryLabel?, secondaryHref?, accent?:'#hex' }",
+  "- divider: { type:'divider' }",
+  "- html: { type:'html', html, sandboxed?, height? }  (custom HTML. Default is sanitized + indexable, no scripts. Set sandboxed:true to run scripts inside an isolated iframe — NOT indexed by search.)",
+  "Build magazine-style posts by composing these, e.g. a hero, then richText, then a columns block, a callout, a codeCard, and a closing cta.",
+].join("\n");
+
+export function registerBlogTools(server: McpServer): void {
+  // Create blog post
+  server.registerTool(
+    "neuron_create_blog_post",
+    {
+      title: "Create Blog Post",
+      description: "Create a new blog post. Body can be authored two ways: (1) `content` as markdown (GFM) + inline raw HTML, or (2) `blocks` — a structured array of typed layout blocks rendered as styled components (heroes, columns, callouts, code cards, embeds, CTAs, sanitized custom HTML). Prefer `blocks` for rich, magazine-style layouts; use `content` for simple prose. If both are given, `blocks` renders and `content` is kept as a fallback.",
+      inputSchema: z.object({
+        title: z.string().describe("Title of the blog post (max 500 characters)"),
+        content: z.string().optional().describe("Optional markdown body (GFM + inline raw HTML). Used when `blocks` is not provided, and kept as a fallback when it is. Rich options: ![alt](url), <video src controls>, <iframe> embeds (16:9), <details><summary>, <mark>, <kbd>."),
+        blocks: BLOCKS_SCHEMA.optional().describe(BLOCKS_DESCRIPTION),
+        excerpt: z.string().optional().describe("Short summary or preview text for the blog post"),
+        authorType: z
+          .enum(["user", "organization"])
+          .describe("Whether the post is authored by an individual user or the organization"),
+        coverImageUrl: z.string().optional().describe("URL of the cover image displayed at the top of the post"),
+        tags: z
+          .array(z.string())
+          .optional()
+          .describe("List of tag names or slugs to categorize the post"),
+        status: z
+          .enum(["draft", "published"])
+          .default("draft")
+          .describe("Initial publication status of the post (default: 'draft')"),
+        seoTitle: z
+          .string()
+          .optional()
+          .describe("Custom SEO title override for search engine results"),
+        seoDescription: z
+          .string()
+          .optional()
+          .describe("Meta description for search engine result snippets"),
+        seoKeywords: z
+          .array(z.string())
+          .optional()
+          .describe("List of SEO keywords for search engine optimization"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("POST", "blog/posts", {
+          title: params.title,
+          content: params.content,
+          blocks: params.blocks,
+          excerpt: params.excerpt,
+          authorType: params.authorType,
+          coverImageUrl: params.coverImageUrl,
+          tags: params.tags,
+          status: params.status,
+          seoTitle: params.seoTitle,
+          seoDescription: params.seoDescription,
+          seoKeywords: params.seoKeywords,
+        });
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // List blog posts
+  server.registerTool(
+    "neuron_list_blog_posts",
+    {
+      title: "List Blog Posts",
+      description: "Retrieve a paginated list of blog posts with optional filtering by status, author type, author ID, or tag.",
+      inputSchema: z.object({
+        status: z
+          .enum(["draft", "published", "hidden"])
+          .optional()
+          .describe("Filter posts by publication status"),
+        authorType: z
+          .enum(["user", "organization"])
+          .optional()
+          .describe("Filter posts by author type"),
+        authorId: z
+          .string()
+          .optional()
+          .describe("Filter posts by author identifier (UUID)"),
+        tag: z.string().optional().describe("Filter posts by tag slug (e.g., 'announcements')"),
+        page: z.number().default(1).describe("Page number for pagination (default: 1)"),
+        limit: z.number().default(20).describe("Number of results per page (default: 20)"),
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("GET", "blog/posts", undefined, {
+          status: params.status,
+          authorType: params.authorType,
+          authorId: params.authorId,
+          tag: params.tag,
+          page: params.page,
+          limit: params.limit,
+        });
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // Get blog post
+  server.registerTool(
+    "neuron_get_blog_post",
+    {
+      title: "Get Blog Post",
+      description: "Retrieve a single blog post by its URL-friendly slug, including full content and metadata.",
+      inputSchema: z.object({
+        slug: z.string().describe("URL-friendly slug of the blog post (e.g., 'my-first-post')"),
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("GET", `blog/posts/${params.slug}`);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // Update blog post
+  server.registerTool(
+    "neuron_update_blog_post",
+    {
+      title: "Update Blog Post",
+      description: "Update an existing blog post's content, metadata, status, or SEO fields. Only provided fields are changed.",
+      inputSchema: z.object({
+        id: z.string().describe("Unique identifier (UUID) of the blog post to update"),
+        title: z.string().optional().describe("New title for the blog post"),
+        content: z.string().optional().describe("New markdown body (GFM + inline raw HTML). Supports ![alt](url), <video>, <iframe> embeds, <details>/<summary>, <mark>, <kbd>."),
+        blocks: BLOCKS_SCHEMA.nullable().optional().describe(`${BLOCKS_DESCRIPTION}\n\nPass null to clear blocks and revert to the markdown \`content\`. Omit to leave existing blocks unchanged.`),
+        excerpt: z.string().optional().describe("New short summary or preview text"),
+        tags: z
+          .array(z.string())
+          .optional()
+          .describe("Replace the post's tags with this list of tag names (created if missing). Empty array clears all tags; omit to leave tags unchanged."),
+        coverImageUrl: z.string().optional().describe("New URL for the cover image"),
+        status: z
+          .enum(["draft", "published", "hidden"])
+          .optional()
+          .describe("New publication status for the post"),
+        seoTitle: z.string().optional().describe("New custom SEO title override"),
+        seoDescription: z.string().optional().describe("New meta description for search engines"),
+        seoKeywords: z
+          .array(z.string())
+          .optional()
+          .describe("New list of SEO keywords"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const { id, ...body } = params;
+        const result = await api("PUT", `blog/posts/${id}`, body);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // Delete blog post
+  server.registerTool(
+    "neuron_delete_blog_post",
+    {
+      title: "Delete Blog Post",
+      description: "Permanently delete a blog post by its ID. This action cannot be undone.",
+      inputSchema: z.object({
+        id: z.string().describe("Unique identifier (UUID) of the blog post to delete"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        await api("DELETE", `blog/posts/${params.id}`);
+        return { content: [{ type: "text" as const, text: "Post deleted successfully" }] };
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // Publish post
+  server.registerTool(
+    "neuron_publish_blog_post",
+    {
+      title: "Publish Blog Post",
+      description: "Publish a blog post, making it publicly visible. The post must be in 'draft' status.",
+      inputSchema: z.object({
+        id: z.string().describe("Unique identifier (UUID) of the blog post to publish"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("POST", `blog/posts/${params.id}/publish`);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+}

package/src/tools/bot-api-keys.ts

@@ -0,0 +1,87 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { api, jsonResult, errorResult } from "../client.js";
+
+export function registerBotApiKeyTools(server: McpServer): void {
+  // Create API Key
+  server.registerTool(
+    "neuron_create_api_key",
+    {
+      title: "Create API Key",
+      description: "Create a new API key for programmatic access to a specific bot. Store the key securely as it cannot be retrieved later.",
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+      },
+      inputSchema: z.object({
+        botId: z.string().describe("Unique identifier (UUID) of the bot to create the API key for"),
+        name: z.string().describe("Descriptive name for the API key to identify its purpose (e.g., 'Production CRM Integration')"),
+        expiresAt: z.string().optional().describe("ISO 8601 date-time when the key should expire (e.g., '2026-12-31T23:59:59Z'). Key never expires if omitted."),
+      }),
+    },
+    async (params) => {
+      try {
+        const { botId, ...keyData } = params;
+        const result = await api("POST", `bots/${botId}/api-keys`, keyData);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // List API Keys
+  server.registerTool(
+    "neuron_list_api_keys",
+    {
+      title: "List API Keys",
+      description: "Retrieve all API keys associated with a specific bot, including their names, creation dates, expiration status, and revocation status.",
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+      inputSchema: z.object({
+        botId: z.string().describe("Unique identifier (UUID) of the bot whose API keys to retrieve"),
+      }),
+    },
+    async (params) => {
+      try {
+        const result = await api("GET", `bots/${params.botId}/api-keys`);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // Revoke API Key
+  server.registerTool(
+    "neuron_revoke_api_key",
+    {
+      title: "Revoke API Key",
+      description: "Permanently revoke an API key to immediately invalidate it and prevent further programmatic access. This action cannot be undone.",
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+      inputSchema: z.object({
+        botId: z.string().describe("Unique identifier (UUID) of the bot that owns the API key"),
+        keyId: z.string().describe("Unique identifier (UUID) of the API key to revoke"),
+      }),
+    },
+    async (params) => {
+      try {
+        const result = await api("DELETE", `bots/${params.botId}/api-keys/${params.keyId}`);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+}

package/src/tools/bot-api.ts

@@ -0,0 +1,193 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { api, jsonResult, errorResult } from "../client.js";
+
+export function registerBotApiTools(server: McpServer): void {
+  // Bot API Chat
+  server.registerTool(
+    "neuron_bot_api_chat",
+    {
+      title: "Bot API Chat",
+      description: "Send a message to a bot via the API and receive a streaming or complete AI-generated response. Requires a valid API key with 'nrn_' prefix.",
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+      },
+      inputSchema: z.object({
+        apiKey: z.string().describe("Bot API key with 'nrn_' prefix for authentication"),
+        message: z.string().describe("The message text to send to the bot"),
+        contactPhone: z.string().describe("Phone number of the contact sending the message (E.164 format, e.g., '+2348012345678')"),
+        contactName: z.string().optional().describe("Display name of the contact for conversation context"),
+      }),
+    },
+    async (params) => {
+      try {
+        const { apiKey, ...chatData } = params;
+        const result = await api(
+          "POST",
+          "bot-api/chat",
+          chatData,
+          undefined,
+          { Authorization: `Bearer ${apiKey}` }
+        );
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // Bot API Send
+  server.registerTool(
+    "neuron_bot_api_send",
+    {
+      title: "Bot API Send",
+      description: "Send an outbound message through the bot API to a specified phone number. Supports text and media messages. Requires a valid API key.",
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+      },
+      inputSchema: z.object({
+        apiKey: z.string().describe("Bot API key with 'nrn_' prefix for authentication"),
+        to: z.string().describe("Recipient's phone number (E.164 format, e.g., '+2348012345678')"),
+        message: z.string().describe("The message text to send to the recipient"),
+        messageType: z.string().optional().describe("Type of message to send: 'text', 'image', 'video', 'audio', or 'document' (default: 'text')"),
+        mediaUrl: z.string().optional().describe("Public URL of the media file to attach (required for non-text message types)"),
+        channelId: z.string().optional().describe("Unique identifier (UUID) of a specific WhatsApp channel to send from. Uses the bot's primary channel if omitted."),
+        sendAt: z.string().optional().describe("ISO 8601 date-time for scheduled delivery (e.g., '2025-12-31T10:00:00Z'). Message sends immediately if omitted."),
+      }),
+    },
+    async (params) => {
+      try {
+        const { apiKey, ...sendData } = params;
+        const result = await api(
+          "POST",
+          "bot-api/send",
+          sendData,
+          undefined,
+          { Authorization: `Bearer ${apiKey}` }
+        );
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // Bot API List Conversations
+  server.registerTool(
+    "neuron_bot_api_list_conversations",
+    {
+      title: "Bot API List Conversations",
+      description: "Retrieve a paginated list of conversations managed by the bot. Supports filtering by conversation status. Requires a valid API key.",
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+      inputSchema: z.object({
+        apiKey: z.string().describe("Bot API key with 'nrn_' prefix for authentication"),
+        status: z.string().optional().describe("Filter by conversation status: 'active', 'closed', or 'pending'"),
+        page: z.number().positive().optional().describe("Page number for pagination (default: 1)"),
+        limit: z.number().positive().optional().describe("Number of conversations per page (default: 20)"),
+      }),
+    },
+    async (params) => {
+      try {
+        const { apiKey, status, page, limit } = params;
+        const queryParams: Record<string, string> = {};
+        if (status) queryParams.status = status;
+        if (page) queryParams.page = page.toString();
+        if (limit) queryParams.limit = limit.toString();
+
+        const result = await api(
+          "GET",
+          "bot-api/conversations",
+          undefined,
+          queryParams,
+          { Authorization: `Bearer ${apiKey}` }
+        );
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // Bot API Get Messages
+  server.registerTool(
+    "neuron_bot_api_get_messages",
+    {
+      title: "Bot API Get Messages",
+      description: "Retrieve message history for a specific conversation with cursor-based pagination. Requires a valid API key.",
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+      inputSchema: z.object({
+        apiKey: z.string().describe("Bot API key with 'nrn_' prefix for authentication"),
+        conversationId: z.string().describe("Unique identifier (UUID) of the conversation to retrieve messages from"),
+        before: z.string().optional().describe("Cursor for pagination — retrieve messages created before this message ID or ISO 8601 timestamp"),
+        limit: z.number().positive().optional().describe("Maximum number of messages to return (default: 50)"),
+      }),
+    },
+    async (params) => {
+      try {
+        const { apiKey, conversationId, before, limit } = params;
+        const queryParams: Record<string, string> = {};
+        if (before) queryParams.before = before;
+        if (limit) queryParams.limit = limit.toString();
+
+        const result = await api(
+          "GET",
+          `bot-api/conversations/${conversationId}/messages`,
+          undefined,
+          queryParams,
+          { Authorization: `Bearer ${apiKey}` }
+        );
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // Bot API Get Bot
+  server.registerTool(
+    "neuron_bot_api_get_bot",
+    {
+      title: "Bot API Get Bot",
+      description: "Retrieve configuration and status information about the bot associated with the provided API key.",
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+      inputSchema: z.object({
+        apiKey: z.string().describe("Bot API key with 'nrn_' prefix for authentication"),
+      }),
+    },
+    async (params) => {
+      try {
+        const result = await api(
+          "GET",
+          "bot-api/bot",
+          undefined,
+          undefined,
+          { Authorization: `Bearer ${params.apiKey}` }
+        );
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+}