harper-kb 0.2.0

package/dist/index.js

@@ -0,0 +1,78 @@
+/**
+ * harper-kb — Harper Knowledge Base Plugin
+ *
+ * Sub-component plugin that provides a knowledge base with vector search,
+ * triage queue, and MCP server integration. Loaded by a parent application
+ * via `package:` in the parent's config.yaml.
+ *
+ * Harper calls handleApplication(scope) on each worker thread.
+ */
+import { initEmbeddingModel, dispose as disposeEmbeddings } from "./core/embeddings.js";
+import { KnowledgeBaseResource } from "./resources/KnowledgeBaseResource.js";
+import { KnowledgeEntryResource } from "./resources/KnowledgeEntryResource.js";
+import { TriageResource } from "./resources/TriageResource.js";
+import { TagResource } from "./resources/TagResource.js";
+import { QueryLogResource } from "./resources/QueryLogResource.js";
+import { ServiceKeyResource } from "./resources/ServiceKeyResource.js";
+import { WebhookEndpointResource } from "./resources/WebhookEndpointResource.js";
+import { HistoryResource } from "./resources/HistoryResource.js";
+import { MeResource } from "./resources/MeResource.js";
+import { createMcpMiddleware } from "./mcp/server.js";
+import { createWebhookMiddleware } from "./webhooks/middleware.js";
+import { initOAuth } from "./oauth/init.js";
+// Re-export core modules for external use
+export { createKnowledgeBase, getKnowledgeBase, updateKnowledgeBase, deleteKnowledgeBase, listKnowledgeBases, } from "./core/knowledge-base.js";
+export { createEntry, getEntry, updateEntry, deprecateEntry, linkSupersedes, linkSiblings, linkRelated, } from "./core/entries.js";
+export { search, filterByApplicability } from "./core/search.js";
+export { logEdit, getHistory } from "./core/history.js";
+export { listTags, syncTags } from "./core/tags.js";
+export { submitTriage, processTriage, listPending, dismissTriage, findBySourceId } from "./core/triage.js";
+export { generateEmbedding, initEmbeddingModel, dispose as disposeEmbeddings } from "./core/embeddings.js";
+export { createWebhookEndpoint, listWebhookEndpoints, deleteWebhookEndpoint } from "./core/webhook-endpoints.js";
+export { registerHooks } from "./hooks.js";
+/**
+ * Plugin entry point — called by Harper on each worker thread.
+ */
+export async function handleApplication(scope) {
+    const scopeLogger = scope.logger;
+    scopeLogger?.info?.('Knowledge base plugin initializing...');
+    // Read plugin configuration
+    const rawOptions = (scope.options.getAll() || {});
+    const embeddingModel = rawOptions.embeddingModel || 'nomic-embed-text';
+    // Initialize the embedding model in the background (downloads on first run).
+    // Don't await — the download can take minutes and would exceed Harper's
+    // 30-second handleApplication timeout. Semantic search degrades gracefully
+    // to keyword-only mode until the model is ready.
+    initEmbeddingModel({ embeddingModel, componentDir: scope.directory }).then(() => scopeLogger?.info?.(`Embedding model "${embeddingModel}" loaded`), (error) => scopeLogger?.error?.('Failed to initialize embedding model — semantic search will be unavailable:', error.message));
+    // Initialize OAuth (signing keys, middleware)
+    await initOAuth(scope);
+    // Register REST Resource classes
+    scope.resources.set('KnowledgeBase', KnowledgeBaseResource);
+    scope.resources.set('Knowledge', KnowledgeEntryResource);
+    scope.resources.set('Triage', TriageResource);
+    scope.resources.set('KnowledgeTag', TagResource);
+    scope.resources.set('QueryLog', QueryLogResource);
+    scope.resources.set('ServiceKey', ServiceKeyResource);
+    scope.resources.set('WebhookEndpoint', WebhookEndpointResource);
+    scope.resources.set('History', HistoryResource);
+    scope.resources.set('me', MeResource);
+    // Register webhook intake middleware (before MCP so /webhooks/* is handled first)
+    scope.server.http?.(createWebhookMiddleware(scope));
+    // Register MCP endpoint middleware (runFirst so it executes before Harper's auth layer)
+    scope.server.http?.(createMcpMiddleware(), { runFirst: true });
+    scopeLogger?.info?.('Knowledge base resources, OAuth, and MCP endpoint registered');
+    // Watch for configuration changes
+    scope.options.on('change', (_key, _value, _config) => {
+        scopeLogger?.debug?.('Knowledge base configuration changed');
+        // Future: re-configure embedding model or other settings as needed
+    });
+    // Clean up on scope close
+    scope.on('close', () => {
+        scopeLogger?.info?.('Knowledge base plugin shutting down');
+        disposeEmbeddings().catch((error) => {
+            scopeLogger?.error?.('Error disposing embedding model:', error.message);
+        });
+    });
+    scopeLogger?.info?.('Knowledge base plugin initialized');
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/mcp/protocol.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Minimal MCP JSON-RPC 2.0 Protocol Handler
+ *
+ * Routes initialize, tools/list, and tools/call methods.
+ * No SDK, no transport layer — just a function from parsed body to response body.
+ */
+import type { ValidatedCaller } from '../oauth/validate.ts';
+interface JsonRpcResponse {
+    jsonrpc: '2.0';
+    id: string | number | null;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+/**
+ * Handle a single JSON-RPC request.
+ *
+ * Returns a JSON-RPC response object, or null for notifications (no id).
+ */
+export declare function handleJsonRpc(body: unknown, caller: ValidatedCaller): Promise<JsonRpcResponse | null>;
+export {};
+//# sourceMappingURL=protocol.d.ts.map

package/dist/mcp/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/mcp/protocol.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAc5D,UAAU,eAAe;IACxB,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CAC1D;AAcD;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAsF3G"}

package/dist/mcp/protocol.js

@@ -0,0 +1,105 @@
+/**
+ * Minimal MCP JSON-RPC 2.0 Protocol Handler
+ *
+ * Routes initialize, tools/list, and tools/call methods.
+ * No SDK, no transport layer — just a function from parsed body to response body.
+ */
+import { tools } from "./tools.js";
+const SERVER_INFO = {
+    name: 'knowledge-base',
+    version: '0.1.0',
+};
+const PROTOCOL_VERSION = '2025-03-26';
+const INVALID_REQUEST = -32600;
+const METHOD_NOT_FOUND = -32601;
+const INTERNAL_ERROR = -32603;
+/** Pre-built name→tool index (built once at module load). */
+const toolsByName = new Map(tools.map((t) => [t.name, t]));
+/** Format a tool definition for the tools/list response. */
+function toToolListEntry(tool) {
+    return {
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+    };
+}
+/**
+ * Handle a single JSON-RPC request.
+ *
+ * Returns a JSON-RPC response object, or null for notifications (no id).
+ */
+export async function handleJsonRpc(body, caller) {
+    if (!body || typeof body !== 'object' || body.jsonrpc !== '2.0') {
+        return {
+            jsonrpc: '2.0',
+            id: body?.id ?? null,
+            error: { code: INVALID_REQUEST, message: 'Invalid JSON-RPC request' },
+        };
+    }
+    const req = body;
+    // Notifications have no id — acknowledge silently
+    if (req.id === undefined || req.id === null) {
+        return null;
+    }
+    const { id } = req;
+    try {
+        switch (req.method) {
+            case 'initialize':
+                return {
+                    jsonrpc: '2.0',
+                    id,
+                    result: {
+                        protocolVersion: PROTOCOL_VERSION,
+                        capabilities: { tools: {} },
+                        serverInfo: SERVER_INFO,
+                    },
+                };
+            case 'tools/list':
+                return {
+                    jsonrpc: '2.0',
+                    id,
+                    result: {
+                        tools: tools.map(toToolListEntry),
+                    },
+                };
+            case 'tools/call': {
+                const toolName = req.params?.name;
+                const toolArgs = req.params?.arguments ?? {};
+                const tool = toolsByName.get(toolName);
+                if (!tool) {
+                    return {
+                        jsonrpc: '2.0',
+                        id,
+                        error: {
+                            code: METHOD_NOT_FOUND,
+                            message: `Unknown tool: ${toolName}`,
+                        },
+                    };
+                }
+                const result = await tool.handler(toolArgs, caller);
+                return { jsonrpc: '2.0', id, result };
+            }
+            default:
+                return {
+                    jsonrpc: '2.0',
+                    id,
+                    error: {
+                        code: METHOD_NOT_FOUND,
+                        message: `Unknown method: ${req.method}`,
+                    },
+                };
+        }
+    }
+    catch (error) {
+        logger?.error?.('MCP JSON-RPC handler failed:', error.message);
+        return {
+            jsonrpc: '2.0',
+            id,
+            error: {
+                code: INTERNAL_ERROR,
+                message: 'Internal server error',
+            },
+        };
+    }
+}
+//# sourceMappingURL=protocol.js.map

package/dist/mcp/protocol.js.map

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

package/dist/mcp/server.d.ts

@@ -0,0 +1,28 @@
+/**
+ * MCP Server Middleware
+ *
+ * Creates an HTTP middleware for Harper's scope.server.http() that handles
+ * MCP (Model Context Protocol) requests as direct JSON-RPC.
+ *
+ * Each knowledge base gets its own MCP endpoint at /mcp/<kbId>.
+ * The kbId is extracted from the URL path, validated against the
+ * KnowledgeBase table, and passed to all tools implicitly via the caller.
+ *
+ * Auth: Validates JWT Bearer tokens issued by the co-located OAuth 2.1
+ * authorization server. Tokens are scoped to a specific KB via the
+ * audience claim (aud = "{baseUrl}/mcp/{kbId}"). Unauthenticated
+ * requests get read-only access.
+ */
+import type { HarperRequest } from '../types.ts';
+/**
+ * Create an MCP middleware function for Harper's scope.server.http().
+ *
+ * The middleware:
+ * 1. Checks if the request pathname starts with /mcp/
+ * 2. Extracts kbId from the path
+ * 3. Validates the KB exists
+ * 4. Validates Bearer token (scoped to this KB)
+ * 5. Handles the MCP request via JSON-RPC dispatch
+ */
+export declare function createMcpMiddleware(): (request: HarperRequest, next: (req: HarperRequest) => Promise<unknown>) => Promise<unknown>;
+//# sourceMappingURL=server.d.ts.map

package/dist/mcp/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAOH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAajD;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,IAAI,CACtC,OAAO,EAAE,aAAa,EACtB,IAAI,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,KAC1C,OAAO,CAAC,OAAO,CAAC,CAgIpB"}

package/dist/mcp/server.js

@@ -0,0 +1,144 @@
+/**
+ * MCP Server Middleware
+ *
+ * Creates an HTTP middleware for Harper's scope.server.http() that handles
+ * MCP (Model Context Protocol) requests as direct JSON-RPC.
+ *
+ * Each knowledge base gets its own MCP endpoint at /mcp/<kbId>.
+ * The kbId is extracted from the URL path, validated against the
+ * KnowledgeBase table, and passed to all tools implicitly via the caller.
+ *
+ * Auth: Validates JWT Bearer tokens issued by the co-located OAuth 2.1
+ * authorization server. Tokens are scoped to a specific KB via the
+ * audience claim (aud = "{baseUrl}/mcp/{kbId}"). Unauthenticated
+ * requests get read-only access.
+ */
+import { handleJsonRpc } from "./protocol.js";
+import { validateMcpAuth } from "../oauth/validate.js";
+import { getKnowledgeBase } from "../core/knowledge-base.js";
+import { checkAccess } from "../hooks.js";
+import { readBody, getBaseUrl } from "../http-utils.js";
+/**
+ * Extract the kbId from the URL path.
+ *
+ * Matches: /mcp/<kbId> or /mcp/<kbId>/...
+ * Returns null if the path doesn't match.
+ */
+function extractKbIdFromPath(pathname) {
+    const match = pathname.match(/^\/mcp\/([^/]+)/);
+    return match ? match[1] : null;
+}
+/**
+ * Create an MCP middleware function for Harper's scope.server.http().
+ *
+ * The middleware:
+ * 1. Checks if the request pathname starts with /mcp/
+ * 2. Extracts kbId from the path
+ * 3. Validates the KB exists
+ * 4. Validates Bearer token (scoped to this KB)
+ * 5. Handles the MCP request via JSON-RPC dispatch
+ */
+export function createMcpMiddleware() {
+    return async (request, next) => {
+        const pathname = request.pathname || '';
+        // Only handle /mcp/<kbId> routes (bare /mcp passes through)
+        if (!pathname.startsWith('/mcp/')) {
+            return next(request);
+        }
+        // Extract kbId from the path
+        const kbId = extractKbIdFromPath(pathname);
+        if (!kbId) {
+            return next(request);
+        }
+        // Validate the KB exists
+        const kb = await getKnowledgeBase(kbId);
+        if (!kb) {
+            return new Response(JSON.stringify({
+                jsonrpc: '2.0',
+                error: {
+                    code: -32001,
+                    message: `Knowledge base not found: ${kbId}`,
+                },
+                id: null,
+            }), {
+                status: 404,
+                headers: { 'Content-Type': 'application/json' },
+            });
+        }
+        // Validate JWT Bearer token (if present), scoped to this KB
+        const { caller, hasToken } = await validateMcpAuth(request, kbId);
+        // Invalid token → 401 so the client re-authenticates
+        if (hasToken && !caller) {
+            const baseUrl = getBaseUrl(request);
+            return new Response(JSON.stringify({
+                jsonrpc: '2.0',
+                error: {
+                    code: -32001,
+                    message: 'Unauthorized',
+                },
+                id: null,
+            }), {
+                status: 401,
+                headers: {
+                    'Content-Type': 'application/json',
+                    'WWW-Authenticate': `Bearer resource_metadata="${baseUrl}/.well-known/oauth-protected-resource/${kbId}"`,
+                },
+            });
+        }
+        // No token → anonymous read-only; valid token → authenticated caller
+        const effectiveCaller = caller ?? {
+            userId: 'anonymous',
+            clientId: 'anonymous',
+            scopes: ['mcp:read'],
+            kbId,
+        };
+        // Run the onAccessCheck hook (if registered by the parent app)
+        const accessResult = await checkAccess(effectiveCaller, kbId);
+        if (accessResult && !accessResult.allow) {
+            logger?.warn?.(`Access denied for ${effectiveCaller.userId} on KB ${kbId}: ${accessResult.reason || 'denied by hook'}`);
+            return new Response(JSON.stringify({
+                jsonrpc: '2.0',
+                error: {
+                    code: -32001,
+                    message: 'Forbidden',
+                },
+                id: null,
+            }), {
+                status: 403,
+                headers: { 'Content-Type': 'application/json' },
+            });
+        }
+        // Hook may override scopes (e.g., downgrade to read-only)
+        const finalCaller = accessResult?.scopes
+            ? { ...effectiveCaller, scopes: accessResult.scopes }
+            : effectiveCaller;
+        try {
+            const bodyText = await readBody(request);
+            const body = bodyText ? JSON.parse(bodyText) : undefined;
+            const response = await handleJsonRpc(body, finalCaller);
+            // Notification (no id) → 202 Accepted
+            if (response === null) {
+                return new Response(null, { status: 202 });
+            }
+            return new Response(JSON.stringify(response), {
+                status: 200,
+                headers: { 'Content-Type': 'application/json' },
+            });
+        }
+        catch (error) {
+            logger?.error?.('MCP request handling failed:', error.message, error.stack);
+            return new Response(JSON.stringify({
+                jsonrpc: '2.0',
+                error: {
+                    code: -32603,
+                    message: 'Internal server error',
+                },
+                id: null,
+            }), {
+                status: 500,
+                headers: { 'Content-Type': 'application/json' },
+            });
+        }
+    };
+}
+//# sourceMappingURL=server.js.map

package/dist/mcp/server.js.map

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

package/dist/mcp/tools.d.ts

@@ -0,0 +1,26 @@
+/**
+ * MCP Tool Definitions
+ *
+ * Static array of tool definitions with JSON Schema input schemas
+ * and handler functions. Each handler receives (args, caller) and
+ * returns MCP tool content.
+ *
+ * The kbId is implicit — it comes from the caller (extracted from the URL
+ * path /mcp/<kbId>), so tools don't need it as an input parameter.
+ */
+import type { ValidatedCaller } from '../oauth/validate.ts';
+export interface ToolContent {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: true;
+}
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    handler: (args: Record<string, unknown>, caller: ValidatedCaller) => Promise<ToolContent>;
+}
+export declare const tools: ToolDefinition[];
+//# sourceMappingURL=tools.d.ts.map

package/dist/mcp/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/mcp/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAiBH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAM5D,MAAM,WAAW,WAAW;IAC3B,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,OAAO,CAAC,EAAE,IAAI,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,eAAe,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;CAC1F;AA8BD,eAAO,MAAM,KAAK,EAAE,cAAc,EAgsBjC,CAAC"}