@spilno/herald-mcp 1.0.0

package/README.md

@@ -0,0 +1,65 @@
+# @spilno/herald-mcp
+
+Herald MCP - Diplomatic interface to [CEDA](https://getceda.com) (Cognitive Event-Driven Architecture).
+
+## Installation
+
+```bash
+npx @spilno/herald-mcp
+```
+
+Or install globally:
+
+```bash
+npm install -g @spilno/herald-mcp
+herald-mcp
+```
+
+## Configuration
+
+Set environment variables:
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `HERALD_API_URL` | Yes | CEDA server URL (e.g., `https://getceda.com`) |
+| `HERALD_API_TOKEN` | No | Bearer token for authentication |
+
+## Tools
+
+Herald exposes these MCP tools:
+
+- **herald_health** - Check CEDA system status
+- **herald_stats** - Get server statistics and pattern info
+- **herald_predict** - Generate structure prediction from natural language
+- **herald_observe** - Record prediction feedback for learning
+
+## Usage with Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "herald": {
+      "command": "npx",
+      "args": ["@spilno/herald-mcp"],
+      "env": {
+        "HERALD_API_URL": "https://getceda.com"
+      }
+    }
+  }
+}
+```
+
+## Usage with Devin
+
+In Devin MCP marketplace:
+- **Server Name**: Herald-CEDA
+- **Transport**: STDIO
+- **Command**: `npx`
+- **Arguments**: `@spilno/herald-mcp`
+- **Environment**: `HERALD_API_URL=https://getceda.com`
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * Herald MCP - Diplomatic interface to CEDA ecosystem
+ *
+ * Herald speaks CEDA. Cognition stays sovereign.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+/**
+ * Herald MCP - Diplomatic interface to CEDA ecosystem
+ *
+ * Herald speaks CEDA. Cognition stays sovereign.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+// Configuration - all sensitive values from environment only
+const CEDA_API_URL = process.env.HERALD_API_URL;
+const CEDA_API_TOKEN = process.env.HERALD_API_TOKEN; // Bearer token (optional for demo)
+const CEDA_API_USER = process.env.HERALD_API_USER; // Basic auth user (optional)
+const CEDA_API_PASS = process.env.HERALD_API_PASS; // Basic auth pass (optional)
+const DEFAULT_CONTEXT_ID = process.env.HERALD_CONTEXT_ID || "ctx_default";
+// Auth strategy: prefer Bearer token, fallback to Basic auth, allow none for demo
+function getAuthHeader() {
+    if (CEDA_API_TOKEN) {
+        return `Bearer ${CEDA_API_TOKEN}`;
+    }
+    if (CEDA_API_USER && CEDA_API_PASS) {
+        const basicAuth = Buffer.from(`${CEDA_API_USER}:${CEDA_API_PASS}`).toString("base64");
+        return `Basic ${basicAuth}`;
+    }
+    return null; // No auth - acceptable for local demo
+}
+async function callCedaAPI(endpoint, method = "GET", body) {
+    // Validate configuration
+    if (!CEDA_API_URL) {
+        return {
+            success: false,
+            error: "HERALD_API_URL not configured. Set environment variable."
+        };
+    }
+    const url = `${CEDA_API_URL}${endpoint}`;
+    const headers = {
+        "Content-Type": "application/json",
+    };
+    // Add auth header if configured (optional for demo)
+    const authHeader = getAuthHeader();
+    if (authHeader) {
+        headers["Authorization"] = authHeader;
+    }
+    try {
+        const response = await fetch(url, {
+            method,
+            headers,
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        if (!response.ok) {
+            return { success: false, error: `HTTP ${response.status}: ${response.statusText}` };
+        }
+        return await response.json();
+    }
+    catch (error) {
+        return { success: false, error: `Connection failed: ${error}` };
+    }
+}
+// Create MCP server
+const server = new Server({
+    name: "herald",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// Tool definitions - aligned with actual CEDA server endpoints
+const tools = [
+    {
+        name: "herald_health",
+        description: "Check Herald and CEDA system status",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+    },
+    {
+        name: "herald_stats",
+        description: "Get CEDA server statistics and loaded patterns info",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+    },
+    {
+        name: "herald_predict",
+        description: "Generate non-deterministic structure prediction from signal",
+        inputSchema: {
+            type: "object",
+            properties: {
+                signal: {
+                    type: "string",
+                    description: "Natural language input (e.g., 'create safety assessment module')",
+                },
+                context_id: {
+                    type: "string",
+                    description: "Context identifier (user/company)",
+                },
+                context: {
+                    type: "string",
+                    description: "Additional context for better prediction",
+                },
+                session_id: {
+                    type: "string",
+                    description: "Optional session for continuity",
+                },
+                domain: {
+                    type: "string",
+                    description: "Optional domain filter (e.g., 'hse')",
+                },
+            },
+            required: ["signal"],
+        },
+    },
+    {
+        name: "herald_observe",
+        description: "Record prediction outcome for learning",
+        inputSchema: {
+            type: "object",
+            properties: {
+                session_id: {
+                    type: "string",
+                    description: "Session ID from prediction",
+                },
+                accepted: {
+                    type: "boolean",
+                    description: "Was prediction accepted by user?",
+                },
+                feedback: {
+                    type: "string",
+                    description: "Optional user feedback/comment",
+                },
+            },
+            required: ["session_id", "accepted"],
+        },
+    },
+];
+// Handle list tools
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools,
+}));
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    switch (name) {
+        case "herald_health": {
+            // Maps to: GET /health
+            const result = await callCedaAPI("/health");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(result, null, 2),
+                    },
+                ],
+            };
+        }
+        case "herald_stats": {
+            // Maps to: GET /api/stats
+            const result = await callCedaAPI("/api/stats");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(result, null, 2),
+                    },
+                ],
+            };
+        }
+        case "herald_predict": {
+            // Maps to: POST /api/predict
+            const params = args;
+            // Build context array if additional context provided
+            const context = params.context ? [
+                {
+                    type: "user_context",
+                    value: params.context,
+                    source: "herald_mcp",
+                }
+            ] : [];
+            const result = await callCedaAPI("/api/predict", "POST", {
+                input: params.signal, // CEDA uses 'input' not 'signal'
+                context,
+                config: {
+                    enableAutoFix: true,
+                    maxAutoFixAttempts: 3,
+                },
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(result, null, 2),
+                    },
+                ],
+            };
+        }
+        case "herald_observe": {
+            // Maps to: POST /api/feedback
+            const params = args;
+            const result = await callCedaAPI("/api/feedback", "POST", {
+                sessionId: params.session_id, // CEDA uses camelCase
+                accepted: params.accepted,
+                comment: params.feedback,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(result, null, 2),
+                    },
+                ],
+            };
+        }
+        default:
+            throw new Error(`Unknown tool: ${name}`);
+    }
+});
+// Start server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Herald MCP server running on stdio");
+}
+main().catch(console.error);

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@spilno/herald-mcp",
+  "version": "1.0.0",
+  "description": "Herald MCP - Diplomatic interface to CEDA (Cognitive Event-Driven Architecture)",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": "./dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ceda",
+    "ai",
+    "copilot",
+    "herald"
+  ],
+  "author": "Spilno",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Spilno-me/ceda.git",
+    "directory": "herald-mcp"
+  },
+  "homepage": "https://getceda.com",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^0.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ]
+}