harper-knowledge 0.1.0

package/dist/http-utils.js

@@ -0,0 +1,132 @@
+/**
+ * HTTP Utilities for Harper's stream-based request/response handling.
+ *
+ * Shared by MCP middleware, OAuth middleware, and webhook middleware.
+ */
+/** Maximum request body size: 1 MB */
+const MAX_BODY_SIZE = 1_048_576;
+/**
+ * Read the request body as a string from Harper's stream-based body.
+ *
+ * Harper's request.body is a RequestBody wrapper with .on()/.pipe() methods,
+ * not a parsed object. We need to consume the stream to get the raw text.
+ *
+ * Enforces a maximum body size to prevent memory exhaustion from oversized requests.
+ */
+export function readBody(request) {
+    return new Promise((resolve, reject) => {
+        const body = request.body;
+        if (!body) {
+            resolve("");
+            return;
+        }
+        // If body is already a string (unlikely but handle it)
+        if (typeof body === "string") {
+            resolve(body);
+            return;
+        }
+        // If body is a stream with .on(), read it
+        if (typeof body.on === "function") {
+            const chunks = [];
+            let totalSize = 0;
+            body.on("data", (chunk) => {
+                totalSize += chunk.length;
+                if (totalSize > MAX_BODY_SIZE) {
+                    body.destroy?.();
+                    reject(new Error("Request body too large"));
+                    return;
+                }
+                chunks.push(Buffer.from(chunk));
+            });
+            body.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+            body.on("error", reject);
+            return;
+        }
+        // If body is already an object (parsed), stringify it
+        if (typeof body === "object") {
+            resolve(JSON.stringify(body));
+            return;
+        }
+        resolve(String(body));
+    });
+}
+/**
+ * Build Web Standard Headers from Harper's Headers object.
+ *
+ * Harper's request.headers is a custom Headers class (iterable, with .get()),
+ * not a plain Record<string, string>.
+ */
+export function buildHeaders(request) {
+    const headers = new Headers();
+    const src = request.headers;
+    if (!src)
+        return headers;
+    // Harper's Headers class is iterable with [key, value] pairs
+    if (typeof src[Symbol.iterator] === "function") {
+        for (const [key, value] of src) {
+            if (value !== undefined) {
+                headers.set(key, Array.isArray(value) ? value.join(", ") : String(value));
+            }
+        }
+    }
+    else if (typeof src === "object") {
+        // Fallback: plain object
+        for (const [key, value] of Object.entries(src)) {
+            if (value !== undefined) {
+                headers.set(key, Array.isArray(value) ? value.join(", ") : String(value));
+            }
+        }
+    }
+    return headers;
+}
+/**
+ * Build the base URL (origin) from a Harper request.
+ *
+ * Uses the request's protocol and host properties. Defaults to
+ * http://localhost:9926 if not available.
+ */
+export function getBaseUrl(request) {
+    const protocol = request.protocol || "http";
+    const host = request.host || "localhost:9926";
+    return `${protocol}://${host}`;
+}
+/**
+ * Parse an application/x-www-form-urlencoded body into a key-value map.
+ */
+export function parseFormBody(body) {
+    const params = new URLSearchParams(body);
+    const result = {};
+    for (const [key, value] of params) {
+        result[key] = value;
+    }
+    return result;
+}
+/**
+ * Get a header value from Harper's request, case-insensitive.
+ */
+export function getHeader(request, name) {
+    const headers = request.headers;
+    if (!headers)
+        return "";
+    // Try .get() method (Harper's Headers class)
+    if (typeof headers.get === "function") {
+        const val = headers.get(name);
+        if (val !== undefined && val !== null)
+            return String(val);
+    }
+    // Try direct access (case-sensitive)
+    const direct = headers[name] ?? headers[name.toLowerCase()];
+    if (direct !== undefined) {
+        return Array.isArray(direct) ? direct[0] : String(direct);
+    }
+    // Fallback: iterate to find case-insensitive match
+    const lowerName = name.toLowerCase();
+    if (typeof headers[Symbol.iterator] === "function") {
+        for (const [key, value] of headers) {
+            if (key.toLowerCase() === lowerName && value !== undefined) {
+                return Array.isArray(value) ? value[0] : String(value);
+            }
+        }
+    }
+    return "";
+}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * harper-knowledge — 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 type { Scope } from "./types.ts";
+export { createEntry, getEntry, updateEntry, deprecateEntry, linkSupersedes, linkSiblings, linkRelated, } from "./core/entries.ts";
+export { search, filterByApplicability } from "./core/search.ts";
+export { logEdit, getHistory } from "./core/history.ts";
+export { listTags, syncTags } from "./core/tags.ts";
+export { submitTriage, processTriage, listPending, dismissTriage, findBySourceId, } from "./core/triage.ts";
+export { generateEmbedding, initEmbeddingModel, dispose as disposeEmbeddings, } from "./core/embeddings.ts";
+export type { KnowledgeEntry, KnowledgeEntryInput, KnowledgeEntryUpdate, KnowledgeEntryEdit, TriageItem, KnowledgeTag, QueryLog, ServiceKey, SearchParams, SearchResult, ApplicabilityScope, ApplicabilityContext, TriageAction, TriageProcessOptions, KnowledgePluginConfig, } from "./types.ts";
+/**
+ * Plugin entry point — called by Harper on each worker thread.
+ */
+export declare function handleApplication(scope: Scope): Promise<void>;

package/dist/index.js

@@ -0,0 +1,76 @@
+/**
+ * harper-knowledge — 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 { 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 { HistoryResource } from "./resources/HistoryResource.js";
+import { createMcpMiddleware } from "./mcp/server.js";
+import { createWebhookMiddleware } from "./webhooks/middleware.js";
+import { createOAuthMiddleware } from "./oauth/middleware.js";
+import { ensureSigningKey } from "./oauth/keys.js";
+// Re-export core modules for external use
+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";
+/**
+ * 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 }).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 (generates RSA key pair on first run)
+    try {
+        await ensureSigningKey();
+    }
+    catch (error) {
+        scopeLogger?.error?.("Failed to initialize OAuth signing key:", error.message);
+    }
+    // Register REST Resource classes
+    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("History", HistoryResource);
+    // Register OAuth endpoints (must be first — handles /.well-known/*, /oauth/*)
+    scope.server.http?.(createOAuthMiddleware());
+    // 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");
+}

package/dist/mcp/server.d.ts

@@ -0,0 +1,24 @@
+/**
+ * MCP Server Middleware
+ *
+ * Creates an HTTP middleware for Harper's scope.server.http() that handles
+ * MCP (Model Context Protocol) requests using Streamable HTTP transport.
+ *
+ * The middleware intercepts requests to /mcp and dispatches them through
+ * the MCP SDK's WebStandardStreamableHTTPServerTransport. Requests to
+ * other paths are passed through to the next handler.
+ *
+ * Auth: Validates JWT Bearer tokens issued by the co-located OAuth 2.1
+ * authorization server. Unauthenticated requests get 401 with
+ * WWW-Authenticate pointing to the Protected Resource Metadata endpoint.
+ */
+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 is /mcp or starts with /mcp/
+ * 2. If not MCP, passes through to next()
+ * 3. If MCP, validates Bearer token, then handles the request
+ */
+export declare function createMcpMiddleware(): (request: HarperRequest, next: (req: HarperRequest) => Promise<unknown>) => Promise<unknown>;

package/dist/mcp/server.js

@@ -0,0 +1,124 @@
+/**
+ * MCP Server Middleware
+ *
+ * Creates an HTTP middleware for Harper's scope.server.http() that handles
+ * MCP (Model Context Protocol) requests using Streamable HTTP transport.
+ *
+ * The middleware intercepts requests to /mcp and dispatches them through
+ * the MCP SDK's WebStandardStreamableHTTPServerTransport. Requests to
+ * other paths are passed through to the next handler.
+ *
+ * Auth: Validates JWT Bearer tokens issued by the co-located OAuth 2.1
+ * authorization server. Unauthenticated requests get 401 with
+ * WWW-Authenticate pointing to the Protected Resource Metadata endpoint.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { registerTools } from "./tools.js";
+import { validateMcpAuth } from "../oauth/validate.js";
+import { readBody, buildHeaders, getBaseUrl } from "../http-utils.js";
+/** Anonymous caller for unauthenticated requests — read-only access */
+const ANONYMOUS_CALLER = {
+    userId: "anonymous",
+    clientId: "anonymous",
+    scopes: ["mcp:read"],
+};
+/**
+ * Create a new McpServer instance with all tools registered.
+ * Called per-request in stateless mode. The caller determines scope access.
+ */
+function createServer(caller) {
+    const server = new McpServer({
+        name: "harper-knowledge",
+        version: "0.1.0",
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    registerTools(server, caller);
+    return server;
+}
+/**
+ * Create an MCP middleware function for Harper's scope.server.http().
+ *
+ * The middleware:
+ * 1. Checks if the request pathname is /mcp or starts with /mcp/
+ * 2. If not MCP, passes through to next()
+ * 3. If MCP, validates Bearer token, then handles the request
+ */
+export function createMcpMiddleware() {
+    return async (request, next) => {
+        const pathname = request.pathname || "";
+        // Only handle /mcp routes
+        if (pathname !== "/mcp" && !pathname.startsWith("/mcp/")) {
+            return next(request);
+        }
+        // Validate JWT Bearer token (if present)
+        const { caller, hasToken } = await validateMcpAuth(request);
+        // 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"`,
+                },
+            });
+        }
+        // No token → anonymous read-only; valid token → authenticated caller
+        const effectiveCaller = caller ?? ANONYMOUS_CALLER;
+        try {
+            // Read the body from Harper's stream
+            const bodyText = await readBody(request);
+            const parsedBody = bodyText ? JSON.parse(bodyText) : undefined;
+            // Build an absolute URL (Request constructor requires it)
+            const host = request.host || "localhost";
+            const protocol = request.protocol || "http";
+            const absoluteUrl = `${protocol}://${host}${request.url || pathname}`;
+            // Build Web Standard headers
+            const headers = buildHeaders(request);
+            // Create a minimal Web Standard Request — body is not needed since
+            // we pass parsedBody directly to the transport
+            const webRequest = new Request(absoluteUrl, {
+                method: request.method || "POST",
+                headers,
+                body: bodyText || undefined,
+            });
+            // Stateless mode: create a fresh transport and server per request
+            const transport = new WebStandardStreamableHTTPServerTransport({
+                enableJsonResponse: true,
+            });
+            const server = createServer(effectiveCaller);
+            await server.connect(transport);
+            // Let the MCP transport handle the request
+            const webResponse = await transport.handleRequest(webRequest, {
+                parsedBody,
+            });
+            return webResponse;
+        }
+        catch (error) {
+            logger?.error?.("MCP request handling failed:", error.message, error.stack);
+            // Return a JSON-RPC error response
+            return new Response(JSON.stringify({
+                jsonrpc: "2.0",
+                error: {
+                    code: -32603,
+                    message: "Internal server error",
+                },
+                id: null,
+            }), {
+                status: 500,
+                headers: { "Content-Type": "application/json" },
+            });
+        }
+    };
+}

package/dist/mcp/tools.d.ts

@@ -0,0 +1,13 @@
+/**
+ * MCP Tool Registration
+ *
+ * Defines and registers all 6 MCP tools with the McpServer instance.
+ * Each tool wraps a core function from src/core/ and returns JSON-formatted results.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ValidatedCaller } from "../oauth/validate.ts";
+/**
+ * Register all knowledge base MCP tools on the given server.
+ * The caller determines scope access — write tools require mcp:write.
+ */
+export declare function registerTools(server: McpServer, caller: ValidatedCaller): void;