@apono-io/mcp-knowledge 0.2.0

package/README.md

@@ -0,0 +1,38 @@
+# @apono-io/mcp-knowledge
+
+Apono MCP server for the Koalition knowledge service. Thin stdio proxy that forwards tool calls to the remote knowledge REST API.
+
+## Tools
+
+| Tool | Description |
+|------|------------|
+| `knowledge_search` | Search the knowledge base — automatically classifies queries and routes to retrieval, aggregation, or analytical handlers |
+| `knowledge_status` | Show collection stats, document counts, and last ingest timestamps |
+
+## Environment Variables
+
+| Variable | Description |
+|----------|------------|
+| `KNOWLEDGE_URL` | Base URL of the knowledge service (e.g. `https://your-knowledge-service-url`) |
+
+## Usage
+
+```bash
+KNOWLEDGE_URL=https://your-knowledge-service-url npx @apono-io/mcp-knowledge
+```
+
+### Claude Code config
+
+```json
+{
+  "mcpServers": {
+    "knowledge": {
+      "command": "npx",
+      "args": ["-y", "@apono-io/mcp-knowledge@latest"],
+      "env": {
+        "KNOWLEDGE_URL": "https://your-knowledge-service-url"
+      }
+    }
+  }
+}
+```

package/dist/__tests__/tools.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tools.test.d.ts.map

package/dist/__tests__/tools.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/tools.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/tools.test.js

@@ -0,0 +1,10 @@
+import { describe, it, expect } from 'vitest';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { registerTools } from '../tools.js';
+describe('registerTools', () => {
+    it('registers all knowledge tools without error', () => {
+        const server = new McpServer({ name: 'test', version: '0.0.1' });
+        expect(() => registerTools(server, 'https://example.com')).not.toThrow();
+    });
+});
+//# sourceMappingURL=tools.test.js.map

package/dist/__tests__/tools.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.test.js","sourceRoot":"","sources":["../../src/__tests__/tools.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,QAAQ,CAAC,eAAe,EAAE,GAAG,EAAE;IAC7B,EAAE,CAAC,6CAA6C,EAAE,GAAG,EAAE;QACrD,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;QACjE,MAAM,CAAC,GAAG,EAAE,CAAC,aAAa,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;IAC3E,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { createRequire } from 'node:module';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { registerTools } from './tools.js';
+import { log } from './logger.js';
+const require = createRequire(import.meta.url);
+const { name, version } = require('../package.json');
+const KNOWLEDGE_URL = process.env.KNOWLEDGE_URL;
+if (!KNOWLEDGE_URL) {
+    process.stderr.write('KNOWLEDGE_URL environment variable is required\n');
+    process.exit(1);
+}
+const server = new McpServer({ name, version });
+registerTools(server, KNOWLEDGE_URL.replace(/\/$/, ''));
+const transport = new StdioServerTransport();
+await server.connect(transport);
+log('Server started');
+process.on('SIGINT', () => {
+    log('Shutting down');
+    process.exit(0);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAElC,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAErD,MAAM,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC;AAChD,IAAI,CAAC,aAAa,EAAE,CAAC;IACnB,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,kDAAkD,CACnD,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;AAEhD,aAAa,CAAC,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC;AAExD,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;AAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAChC,GAAG,CAAC,gBAAgB,CAAC,CAAC;AAEtB,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE;IACxB,GAAG,CAAC,eAAe,CAAC,CAAC;IACrB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/logger.d.ts

@@ -0,0 +1,2 @@
+export declare function log(message: string, ...args: unknown[]): void;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAEA,wBAAgB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAE7D"}

package/dist/logger.js

@@ -0,0 +1,5 @@
+const PREFIX = '[mcp-knowledge]';
+export function log(message, ...args) {
+    console.error(`${PREFIX} ${message}`, ...args);
+}
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,GAAG,iBAAiB,CAAC;AAEjC,MAAM,UAAU,GAAG,CAAC,OAAe,EAAE,GAAG,IAAe;IACrD,OAAO,CAAC,KAAK,CAAC,GAAG,MAAM,IAAI,OAAO,EAAE,EAAE,GAAG,IAAI,CAAC,CAAC;AACjD,CAAC"}

package/dist/tools.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerTools(server: McpServer, baseUrl: string): void;
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAuBzE,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAkEtE"}

package/dist/tools.js

@@ -0,0 +1,67 @@
+import { z } from 'zod';
+import { log } from './logger.js';
+async function fetchJson(url) {
+    const res = await fetch(url);
+    if (!res.ok) {
+        const body = await res.text();
+        throw new Error(`HTTP ${res.status}: ${body}`);
+    }
+    return res.json();
+}
+function textContent(text) {
+    return { content: [{ type: 'text', text }] };
+}
+function errorContent(toolName, err) {
+    const message = err instanceof Error ? err.message : String(err);
+    log(`${toolName} error:`, err);
+    return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
+}
+export function registerTools(server, baseUrl) {
+    server.tool('knowledge_search', 'Search the knowledge base. Automatically classifies your query and routes to the right handler (retrieval, aggregation, or analytical).', {
+        query: z.string().describe('The natural language question to search for'),
+        collection: z
+            .string()
+            .optional()
+            .describe("Limit to a specific collection (e.g. 'gong_transcripts'). Omit to search all."),
+    }, async ({ query, collection }) => {
+        try {
+            const params = new URLSearchParams({ q: query });
+            if (collection)
+                params.set('collection', collection);
+            const data = await fetchJson(`${baseUrl}/context?${params}`);
+            if (data.context !== undefined) {
+                return data.context
+                    ? textContent(data.context)
+                    : textContent('No relevant results found.');
+            }
+            if (data.type === 'aggregation') {
+                return textContent(data.answer);
+            }
+            if (data.type === 'analytical') {
+                const text = data.sources?.length
+                    ? `${data.answer}\n\nSources: ${data.sources.join(', ')}`
+                    : data.answer;
+                return textContent(text);
+            }
+            return textContent(JSON.stringify(data, null, 2));
+        }
+        catch (err) {
+            return errorContent('knowledge_search', err);
+        }
+    });
+    server.tool('knowledge_status', "Show what's in the knowledge base — collection stats, document counts, last ingest timestamps.", {}, async () => {
+        try {
+            const data = await fetchJson(`${baseUrl}/status`);
+            const lines = [];
+            for (const [name, stats] of Object.entries(data.collections)) {
+                const lastIngest = stats.last_ingest ?? 'never';
+                lines.push(`${name}: ${stats.documents} documents, ${stats.chunks} chunks, last ingest: ${lastIngest}`);
+            }
+            return textContent(lines.join('\n'));
+        }
+        catch (err) {
+            return errorContent('knowledge_status', err);
+        }
+    });
+}
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@apono-io/mcp-knowledge",
+  "version": "0.2.0",
+  "description": "Apono MCP server for the Koalition knowledge service — proxies knowledge_search and knowledge_status to the remote REST API",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "apono-mcp-knowledge": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "Apono",
+  "license": "ISC"
+}