@velaro/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,73 @@
+# @velaro/mcp-server
+
+Connect Claude, Claude Code, and other AI agents directly to your Velaro account via the [Model Context Protocol](https://modelcontextprotocol.io).
+
+## Quick Start
+
+```bash
+npx @velaro/mcp-server
+```
+
+Set your MCP key (create one in Velaro Settings > API > MCP Keys):
+
+```bash
+VELARO_MCP_KEY=vel_live_... npx @velaro/mcp-server
+```
+
+## Claude Code Setup
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "velaro": {
+      "command": "npx",
+      "args": ["@velaro/mcp-server"],
+      "env": {
+        "VELARO_MCP_KEY": "vel_live_..."
+      }
+    }
+  }
+}
+```
+
+## Claude Desktop Setup
+
+Add to `~/.claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "velaro": {
+      "command": "npx",
+      "args": ["@velaro/mcp-server"],
+      "env": {
+        "VELARO_MCP_KEY": "vel_live_..."
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `kb_list_topics` | List all KB topics |
+| `kb_search_articles` | Search articles by term, topic, or publish status |
+| `kb_get_article` | Get full article content by ID |
+| `kb_create_article` | Create a new article |
+| `kb_update_article` | Update an existing article |
+| `kb_delete_article` | Delete an article |
+
+## Auth
+
+- `VELARO_MCP_KEY=vel_live_...` — service key (create in Settings > API > MCP Keys)
+- `VELARO_JWT=<token>` — short-lived JWT from `velaro login` (dev use only)
+
+## Staging / Custom API
+
+```bash
+VELARO_ADMIN_API=https://velaro-admin-staging.azurewebsites.net VELARO_MCP_KEY=vel_live_... npx @velaro/mcp-server
+```

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@velaro/mcp-server",
+  "version": "0.1.0",
+  "description": "Velaro MCP server — connect Claude and other AI agents directly to your Velaro KB and account.",
+  "type": "module",
+  "bin": {
+    "velaro-mcp": "server.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "scripts": {
+    "start": "node server.js"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/velaro/velaro-admin"
+  },
+  "keywords": ["velaro", "mcp", "knowledge-base", "claude", "ai", "model-context-protocol"],
+  "license": "MIT",
+  "files": [
+    "server.js",
+    "README.md"
+  ]
+}

package/server.js

@@ -0,0 +1,287 @@
+#!/usr/bin/env node
+/**
+ * Velaro MCP Server
+ *
+ * Exposes KB article management as Claude tools via the Model Context Protocol.
+ *
+ * Auth (pick one):
+ *   VELARO_MCP_KEY=vel_live_...   service key (create with: velaro mcp-key create --label "Claude Code")
+ *   VELARO_JWT=<token>            short-lived Velaro JWT (from velaro login, for dev use)
+ *
+ * API base:
+ *   VELARO_ADMIN_API=https://help.velaro.com   (default, production)
+ *   VELARO_ADMIN_API=https://velaro-admin-staging.azurewebsites.net  (staging)
+ *
+ * Claude Desktop config (~/.claude/claude_desktop_config.json):
+ *   {
+ *     "mcpServers": {
+ *       "velaro": {
+ *         "command": "node",
+ *         "args": ["/path/to/velaro-admin/mcp/server.js"],
+ *         "env": { "VELARO_MCP_KEY": "vel_live_..." }
+ *       }
+ *     }
+ *   }
+ *
+ * Claude Code config (settings.json → mcpServers):
+ *   "velaro": {
+ *     "command": "node",
+ *     "args": ["/path/to/velaro-admin/mcp/server.js"],
+ *     "env": { "VELARO_MCP_KEY": "vel_live_..." }
+ *   }
+ *
+ * Hosted HTTP endpoint (no Node required -- for customers and production):
+ *   "velaro": {
+ *     "url": "https://velaro-admin-staging.azurewebsites.net/mcp",
+ *     "headers": { "Authorization": "Bearer vel_live_..." }
+ *   }
+ *
+ * HTTP mode (set VELARO_MCP_MODE=http to run as an HTTP/SSE server instead of stdio):
+ *   VELARO_MCP_MODE=http PORT=3000 node server.js
+ */
+
+import { Server }            from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+
+const API_BASE = process.env.VELARO_ADMIN_API || 'https://help.velaro.com';
+const MCP_KEY  = process.env.VELARO_MCP_KEY;
+const JWT      = process.env.VELARO_JWT;
+
+if (!MCP_KEY && !JWT) {
+  process.stderr.write('ERROR: Set VELARO_MCP_KEY=vel_live_... or VELARO_JWT=<token>\n');
+  process.exit(1);
+}
+
+function authHeader() {
+  return MCP_KEY ? `Bearer ${MCP_KEY}` : `Bearer ${JWT}`;
+}
+
+async function api(method, path, body) {
+  const res = await fetch(`${API_BASE}${path}`, {
+    method,
+    headers: { Authorization: authHeader(), 'Content-Type': 'application/json' },
+    body: body !== undefined ? JSON.stringify(body) : undefined,
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    throw new Error(`Velaro API ${method} ${path} -> ${res.status}: ${text.slice(0, 300)}`);
+  }
+  const text = await res.text();
+  return text ? JSON.parse(text) : null;
+}
+
+// ── Tool definitions ──────────────────────────────────────────────────────────
+
+const TOOLS = [
+  {
+    name: 'kb_list_topics',
+    description: 'List all KB topics. Call this first to find the topicId needed for creating articles.',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+  {
+    name: 'kb_search_articles',
+    description: 'Search KB articles. Returns id, title, slug, topicName, hitCount, isPublished, and public URL.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        searchTerm:    { type: 'string',  description: 'Full-text search term' },
+        topicId:       { type: 'number',  description: 'Filter by topic ID' },
+        publishStatus: { type: 'string',  enum: ['Published', 'Unpublished'], description: 'Filter by publish status' },
+      },
+    },
+  },
+  {
+    name: 'kb_get_article',
+    description: 'Get full content of a KB article by ID.',
+    inputSchema: {
+      type: 'object',
+      properties: { id: { type: 'number', description: 'Article ID' } },
+      required: ['id'],
+    },
+  },
+  {
+    name: 'kb_create_article',
+    description: 'Create a new KB article. Use kb_list_topics first to find the topicId.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        title:       { type: 'string',  description: 'Article title' },
+        slug:        { type: 'string',  description: 'URL slug (lowercase, hyphens only)' },
+        topicId:     { type: 'number',  description: 'Topic ID from kb_list_topics' },
+        content:     { type: 'string',  description: 'Article body as HTML' },
+        description: { type: 'string',  description: 'Short description (shown in search results)' },
+        searchTags:  { type: 'string',  description: 'Space-separated tags for search' },
+        isPublished: { type: 'boolean', description: 'Publish immediately (default: false)' },
+        botSummary:  { type: 'string',  description: 'Concise bot-readable summary (max 800 chars)' },
+      },
+      required: ['title', 'slug', 'topicId', 'content'],
+    },
+  },
+  {
+    name: 'kb_update_article',
+    description: 'Update an existing KB article. Fetch with kb_get_article first, then pass all fields.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id:          { type: 'number',  description: 'Article ID to update' },
+        title:       { type: 'string' },
+        slug:        { type: 'string' },
+        topicId:     { type: 'number' },
+        content:     { type: 'string',  description: 'Full article body as HTML' },
+        description: { type: 'string' },
+        searchTags:  { type: 'string' },
+        isPublished: { type: 'boolean' },
+        botSummary:  { type: 'string' },
+      },
+      required: ['id', 'title', 'slug', 'topicId', 'content'],
+    },
+  },
+  {
+    name: 'kb_delete_article',
+    description: 'Delete a KB article. Irreversible — confirm with the user before calling.',
+    inputSchema: {
+      type: 'object',
+      properties: { id: { type: 'number', description: 'Article ID to delete' } },
+      required: ['id'],
+    },
+  },
+];
+
+// ── Tool handlers ─────────────────────────────────────────────────────────────
+
+async function handleTool(name, args) {
+  switch (name) {
+    case 'kb_list_topics': {
+      const data   = await api('GET', '/api/kb/topics');
+      const topics = data?.topics ?? [];
+      return topics.map(t => `[${t.id}] ${t.name} (${t.articleCount} articles)`).join('\n')
+        || 'No topics found.';
+    }
+
+    case 'kb_search_articles': {
+      const data     = await api('POST', '/api/kb/articles/search', {
+        searchTerm:    args.searchTerm,
+        topicId:       args.topicId,
+        publishStatus: args.publishStatus,
+      });
+      const articles = data?.articles ?? [];
+      if (!articles.length) return 'No articles found.';
+      return articles.map(a =>
+        `[${a.id}] ${a.isPublished ? 'published' : 'draft'} | "${a.title}" | ${a.hitCount ?? 0} views | ${a.url ?? 'not public'}`
+      ).join('\n');
+    }
+
+    case 'kb_get_article': {
+      const a = await api('GET', `/api/kb/articles?id=${args.id}`);
+      return JSON.stringify({
+        id:          a.id,
+        title:       a.title,
+        slug:        a.slug,
+        topicId:     a.topicId,
+        description: a.description,
+        content:     a.content,
+        searchTags:  a.searchTags,
+        isPublished: a.isPublished,
+        botSummary:  a.botSummary,
+        url:         a.url,
+      }, null, 2);
+    }
+
+    case 'kb_create_article': {
+      await api('POST', '/api/kb/articles', {
+        title:             args.title,
+        slug:              args.slug,
+        topicId:           args.topicId,
+        content:           args.content,
+        description:       args.description || '',
+        searchTags:        args.searchTags  || '',
+        visibility:        'Public',
+        isPublished:       args.isPublished  ?? false,
+        displayPriority:   0,
+        enableBotResponse: !!args.botSummary,
+        botSummary:        args.botSummary  || '',
+        isFeatured:        false,
+      });
+      const result = await api('POST', '/api/kb/articles/search', { searchTerm: args.slug, topicId: args.topicId });
+      const created = result?.articles?.find(a => a.slug === args.slug);
+      const id = created?.id;
+      return id
+        ? `Created article [${id}] "${args.title}". URL: https://help.velaro.com/kb/article/${id}/${args.slug}`
+        : `Created "${args.title}" — search by slug "${args.slug}" to find the ID.`;
+    }
+
+    case 'kb_update_article': {
+      await api('PUT', `/api/kb/articles?id=${args.id}`, {
+        title:             args.title,
+        slug:              args.slug,
+        topicId:           args.topicId,
+        content:           args.content,
+        description:       args.description || '',
+        searchTags:        args.searchTags  || '',
+        visibility:        'Public',
+        isPublished:       args.isPublished  ?? false,
+        displayPriority:   0,
+        enableBotResponse: !!args.botSummary,
+        botSummary:        args.botSummary  || '',
+        isFeatured:        false,
+      });
+      return `Updated article [${args.id}] "${args.title}".`;
+    }
+
+    case 'kb_delete_article': {
+      await api('DELETE', `/api/kb/articles?id=${args.id}`);
+      return `Article ${args.id} deleted.`;
+    }
+
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}
+
+// ── Server setup ──────────────────────────────────────────────────────────────
+
+const server = new Server(
+  { name: 'velaro', version: '0.1.0' },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  try {
+    const result = await handleTool(name, args ?? {});
+    return { content: [{ type: 'text', text: String(result) }] };
+  } catch (err) {
+    return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+  }
+});
+
+const mode = process.env.VELARO_MCP_MODE || 'stdio';
+
+if (mode === 'http') {
+  const { SSEServerTransport } = await import('@modelcontextprotocol/sdk/server/sse.js');
+  const http = await import('http');
+  const port = parseInt(process.env.PORT || '3000', 10);
+
+  const httpServer = http.createServer(async (req, res) => {
+    if (req.method === 'GET' && req.url === '/mcp') {
+      const transport = new SSEServerTransport('/mcp', res);
+      await server.connect(transport);
+    } else if (req.method === 'POST' && req.url === '/mcp') {
+      // handled by SSEServerTransport automatically
+    } else {
+      res.writeHead(404).end();
+    }
+  });
+
+  httpServer.listen(port, () =>
+    process.stderr.write(`Velaro MCP HTTP server listening on port ${port}\n`));
+} else {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}