harper-knowledge 0.1.0

package/dist/mcp/tools.js

@@ -0,0 +1,497 @@
+/**
+ * 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 * as z from "zod/v4";
+import { search } from "../core/search.js";
+import { createEntry, getEntry, updateEntry, stripEmbedding, } from "../core/entries.js";
+import { listTags } from "../core/tags.js";
+import { submitTriage } from "../core/triage.js";
+import { generateEmbedding } from "../core/embeddings.js";
+import { getHistory } from "../core/history.js";
+/**
+ * Format a result as MCP tool content (JSON text block).
+ */
+function jsonContent(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+    };
+}
+/**
+ * Format an error as MCP tool content with isError flag.
+ */
+function errorContent(message) {
+    return {
+        content: [{ type: "text", text: message }],
+        isError: true,
+    };
+}
+/**
+ * Register all knowledge base MCP tools on the given server.
+ * The caller determines scope access — write tools require mcp:write.
+ */
+export function registerTools(server, caller) {
+    // =========================================================================
+    // 1. knowledge_search — Search the knowledge base
+    // =========================================================================
+    server.registerTool("knowledge_search", {
+        description: "Search the Harper knowledge base using keyword, semantic, or hybrid search. " +
+            "Returns scored results sorted by relevance. Provide optional environment " +
+            "context to boost results matching your setup.",
+        inputSchema: {
+            query: z.string().describe("Search query string"),
+            tags: z.array(z.string()).optional().describe("Filter results by tags"),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(50)
+                .optional()
+                .describe("Maximum number of results (default 10)"),
+            context: z
+                .object({
+                harper: z
+                    .string()
+                    .optional()
+                    .describe('Harper version (e.g., "4.6.0" or ">=4.6.0")'),
+                storageEngine: z
+                    .string()
+                    .optional()
+                    .describe('Storage engine (e.g., "lmdb", "rocksdb")'),
+                node: z
+                    .string()
+                    .optional()
+                    .describe('Node.js version (e.g., "22.0.0")'),
+                platform: z
+                    .string()
+                    .optional()
+                    .describe('Platform (e.g., "linux", "darwin", "win32")'),
+            })
+                .optional()
+                .describe("Caller's environment context for applicability filtering"),
+        },
+    }, async ({ query, tags, limit, context }) => {
+        try {
+            const results = await search({ query, tags, limit, context });
+            const cleaned = results.map(stripEmbedding);
+            return jsonContent({
+                resultCount: cleaned.length,
+                results: cleaned,
+            });
+        }
+        catch (error) {
+            return errorContent("Search failed. Please try again.");
+        }
+    });
+    // =========================================================================
+    // 2. knowledge_add — Add a new knowledge entry
+    // =========================================================================
+    server.registerTool("knowledge_add", {
+        description: "Add a new entry to the Harper knowledge base. Entries added via MCP " +
+            'are automatically tagged with confidence "ai-generated". An embedding ' +
+            "is generated from the title and content for semantic search.",
+        inputSchema: {
+            title: z
+                .string()
+                .max(500)
+                .describe("Entry title — concise summary of the knowledge"),
+            content: z
+                .string()
+                .max(100_000)
+                .describe("Full content of the knowledge entry (Markdown supported)"),
+            tags: z
+                .array(z.string().max(100))
+                .max(50)
+                .describe('Tags for categorization (e.g., ["plugins", "config"])'),
+            source: z
+                .string()
+                .max(200)
+                .optional()
+                .describe('Source identifier (e.g., "github-issue", "docs", "slack")'),
+            sourceUrl: z
+                .string()
+                .max(2000)
+                .optional()
+                .describe("URL to the original source"),
+            appliesTo: z
+                .object({
+                harper: z
+                    .string()
+                    .optional()
+                    .describe("Harper version or semver range"),
+                storageEngine: z
+                    .string()
+                    .optional()
+                    .describe("Storage engine type"),
+                node: z
+                    .string()
+                    .optional()
+                    .describe("Node.js version or semver range"),
+                platform: z.string().optional().describe("Platform identifier"),
+            })
+                .optional()
+                .describe("Applicability scope — what environments this entry applies to"),
+        },
+    }, async ({ title, content, tags, source, sourceUrl, appliesTo }) => {
+        if (!caller.scopes.includes("mcp:write")) {
+            return errorContent("Write access required. Authenticate with an authorized GitHub account to add entries.");
+        }
+        try {
+            const entry = await createEntry({
+                title,
+                content,
+                tags,
+                source,
+                sourceUrl,
+                appliesTo,
+                confidence: "ai-generated", // MCP callers are AI agents
+            });
+            return jsonContent({
+                message: "Knowledge entry created successfully",
+                entry: stripEmbedding(entry),
+            });
+        }
+        catch (error) {
+            return errorContent("Failed to create entry. Please try again.");
+        }
+    });
+    // =========================================================================
+    // 3. knowledge_get — Get a knowledge entry by ID
+    // =========================================================================
+    server.registerTool("knowledge_get", {
+        description: "Get a single knowledge entry by ID. If the entry has relationships " +
+            "(supersedes, superseded by, siblings, related), the linked entries " +
+            "are also fetched and included in the response.",
+        inputSchema: {
+            id: z.string().describe("The knowledge entry ID"),
+        },
+    }, async ({ id }) => {
+        try {
+            const entry = await getEntry(id);
+            if (!entry) {
+                return errorContent(`Knowledge entry not found: ${id}`);
+            }
+            const result = {
+                entry: stripEmbedding(entry),
+            };
+            // Fetch related entries if relationships exist
+            const relationships = {};
+            if (entry.supersedesId) {
+                const supersedes = await getEntry(entry.supersedesId);
+                if (supersedes) {
+                    relationships.supersedes = stripEmbedding(supersedes);
+                }
+            }
+            if (entry.supersededById) {
+                const supersededBy = await getEntry(entry.supersededById);
+                if (supersededBy) {
+                    relationships.supersededBy = stripEmbedding(supersededBy);
+                }
+            }
+            if (entry.siblingIds && entry.siblingIds.length > 0) {
+                const siblings = [];
+                for (const siblingId of entry.siblingIds) {
+                    const sibling = await getEntry(siblingId);
+                    if (sibling) {
+                        siblings.push(stripEmbedding(sibling));
+                    }
+                }
+                if (siblings.length > 0) {
+                    relationships.siblings = siblings;
+                }
+            }
+            if (entry.relatedIds && entry.relatedIds.length > 0) {
+                const related = [];
+                for (const relatedId of entry.relatedIds) {
+                    const relatedEntry = await getEntry(relatedId);
+                    if (relatedEntry) {
+                        related.push(stripEmbedding(relatedEntry));
+                    }
+                }
+                if (related.length > 0) {
+                    relationships.related = related;
+                }
+            }
+            if (Object.keys(relationships).length > 0) {
+                result.relationships = relationships;
+            }
+            return jsonContent(result);
+        }
+        catch (error) {
+            return errorContent("Failed to get entry. Please try again.");
+        }
+    });
+    // =========================================================================
+    // 4. knowledge_related — Find entries related to a given entry
+    // =========================================================================
+    server.registerTool("knowledge_related", {
+        description: "Find knowledge entries related to a given entry. Combines explicit " +
+            "relationships (siblings, related, supersedes chain) with semantic " +
+            "similarity search using the entry's embedding.",
+        inputSchema: {
+            id: z
+                .string()
+                .describe("The knowledge entry ID to find related entries for"),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(50)
+                .optional()
+                .describe("Maximum number of results (default 10)"),
+        },
+    }, async ({ id, limit }) => {
+        const maxResults = limit ?? 10;
+        try {
+            const entry = await getEntry(id);
+            if (!entry) {
+                return errorContent(`Knowledge entry not found: ${id}`);
+            }
+            const relatedMap = new Map();
+            // Gather explicit relationships
+            if (entry.supersedesId) {
+                const supersedes = await getEntry(entry.supersedesId);
+                if (supersedes) {
+                    relatedMap.set(supersedes.id, {
+                        entry: stripEmbedding(supersedes),
+                        relationship: "supersedes",
+                    });
+                }
+            }
+            if (entry.supersededById) {
+                const supersededBy = await getEntry(entry.supersededById);
+                if (supersededBy) {
+                    relatedMap.set(supersededBy.id, {
+                        entry: stripEmbedding(supersededBy),
+                        relationship: "superseded_by",
+                    });
+                }
+            }
+            if (entry.siblingIds) {
+                for (const siblingId of entry.siblingIds) {
+                    if (!relatedMap.has(siblingId)) {
+                        const sibling = await getEntry(siblingId);
+                        if (sibling) {
+                            relatedMap.set(sibling.id, {
+                                entry: stripEmbedding(sibling),
+                                relationship: "sibling",
+                            });
+                        }
+                    }
+                }
+            }
+            if (entry.relatedIds) {
+                for (const relatedId of entry.relatedIds) {
+                    if (!relatedMap.has(relatedId)) {
+                        const relatedEntry = await getEntry(relatedId);
+                        if (relatedEntry) {
+                            relatedMap.set(relatedEntry.id, {
+                                entry: stripEmbedding(relatedEntry),
+                                relationship: "related",
+                            });
+                        }
+                    }
+                }
+            }
+            // Semantic similarity search using entry content
+            let semanticResults = [];
+            try {
+                const queryText = `${entry.title}\n\n${entry.content}`;
+                const embedding = await generateEmbedding(queryText);
+                // Collect similar entries from HNSW search
+                const searchResults = [];
+                for await (const item of databases.kb.KnowledgeEntry.search({
+                    sort: { attribute: "embedding", target: embedding },
+                    limit: maxResults + 10, // Fetch extra to account for filtering
+                })) {
+                    searchResults.push(item);
+                }
+                semanticResults = searchResults
+                    .map((r) => r)
+                    .filter((r) => r.id !== id && !r.deprecated);
+            }
+            catch {
+                // Embedding model may not be available — continue with explicit relationships only
+            }
+            // Merge semantic results (add those not already in explicit relationships)
+            for (const result of semanticResults) {
+                if (!relatedMap.has(result.id) && relatedMap.size < maxResults) {
+                    relatedMap.set(result.id, {
+                        entry: stripEmbedding(result),
+                        relationship: "similar",
+                    });
+                }
+            }
+            // Convert to array, limited to maxResults
+            const results = Array.from(relatedMap.values()).slice(0, maxResults);
+            return jsonContent({
+                entryId: id,
+                entryTitle: entry.title,
+                relatedCount: results.length,
+                related: results,
+            });
+        }
+        catch (error) {
+            return errorContent("Failed to find related entries. Please try again.");
+        }
+    });
+    // =========================================================================
+    // 5. knowledge_list_tags — List all knowledge tags
+    // =========================================================================
+    server.registerTool("knowledge_list_tags", {
+        description: "List all tags in the knowledge base with their entry counts. " +
+            "Useful for discovering available categories before searching.",
+    }, async () => {
+        try {
+            const tags = await listTags();
+            return jsonContent({
+                tagCount: tags.length,
+                tags,
+            });
+        }
+        catch (error) {
+            return errorContent("Failed to list tags. Please try again.");
+        }
+    });
+    // =========================================================================
+    // 6. knowledge_triage — Submit an item to the triage queue
+    // =========================================================================
+    server.registerTool("knowledge_triage", {
+        description: "Submit a new item to the knowledge triage queue for review. " +
+            "Use this when you encounter information that should potentially " +
+            "be added to the knowledge base but needs human review first.",
+        inputSchema: {
+            source: z
+                .string()
+                .describe('Source identifier (e.g., "claude-code", "github-issue", "slack")'),
+            summary: z
+                .string()
+                .describe("Brief summary of the knowledge to triage"),
+            payload: z
+                .record(z.string(), z.unknown())
+                .optional()
+                .describe("Additional payload data from the source"),
+        },
+    }, async ({ source, summary, payload }) => {
+        if (!caller.scopes.includes("mcp:write")) {
+            return errorContent("Write access required. Authenticate with an authorized GitHub account to submit triage items.");
+        }
+        try {
+            const item = await submitTriage(source, summary, payload);
+            return jsonContent({
+                message: "Triage item submitted successfully",
+                item,
+            });
+        }
+        catch (error) {
+            return errorContent("Failed to submit triage item. Please try again.");
+        }
+    });
+    // =========================================================================
+    // 7. knowledge_update — Update an existing knowledge entry
+    // =========================================================================
+    server.registerTool("knowledge_update", {
+        description: "Update an existing knowledge entry. Only provide fields you want to change. " +
+            "Edits are tracked in the history log with who made the change and why.",
+        inputSchema: {
+            id: z.string().describe("The knowledge entry ID to update"),
+            title: z.string().max(500).optional().describe("Updated title"),
+            content: z
+                .string()
+                .max(100_000)
+                .optional()
+                .describe("Updated content (Markdown supported)"),
+            tags: z
+                .array(z.string().max(100))
+                .max(50)
+                .optional()
+                .describe("Updated tags"),
+            source: z
+                .string()
+                .max(200)
+                .optional()
+                .describe("Updated source identifier"),
+            sourceUrl: z
+                .string()
+                .max(2000)
+                .optional()
+                .describe("Updated source URL"),
+            confidence: z
+                .enum(["ai-generated", "reviewed", "verified"])
+                .optional()
+                .describe("Updated confidence level"),
+            appliesTo: z
+                .object({
+                harper: z.string().optional(),
+                storageEngine: z.string().optional(),
+                node: z.string().optional(),
+                platform: z.string().optional(),
+            })
+                .optional()
+                .describe("Updated applicability scope"),
+            deprecated: z.boolean().optional().describe("Mark as deprecated"),
+            editSummary: z
+                .string()
+                .max(1000)
+                .optional()
+                .describe("Brief description of what changed and why (for the edit log)"),
+        },
+    }, async ({ id, editSummary, ...updates }) => {
+        if (!caller.scopes.includes("mcp:write")) {
+            return errorContent("Write access required. Authenticate with an authorized GitHub account to update entries.");
+        }
+        // MCP callers are AI agents — prevent confidence escalation
+        if (updates.confidence && updates.confidence !== "ai-generated") {
+            delete updates.confidence;
+        }
+        try {
+            const entry = await updateEntry(id, updates, {
+                editedBy: caller.userId,
+                editSummary,
+            });
+            return jsonContent({
+                message: "Knowledge entry updated successfully",
+                entry: stripEmbedding(entry),
+            });
+        }
+        catch (error) {
+            return errorContent("Failed to update entry. Please try again.");
+        }
+    });
+    // =========================================================================
+    // 8. knowledge_history — Get edit history for an entry
+    // =========================================================================
+    server.registerTool("knowledge_history", {
+        description: "Get the edit history for a knowledge entry. Shows who changed what, " +
+            "when, and why — with snapshots of previous values for each changed field.",
+        inputSchema: {
+            id: z.string().describe("The knowledge entry ID to get history for"),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .optional()
+                .describe("Maximum number of edits to return (default 50)"),
+        },
+    }, async ({ id, limit }) => {
+        try {
+            const entry = await getEntry(id);
+            if (!entry) {
+                return errorContent(`Knowledge entry not found: ${id}`);
+            }
+            const edits = await getHistory(id, limit);
+            return jsonContent({
+                entryId: id,
+                entryTitle: entry.title,
+                editCount: edits.length,
+                edits,
+            });
+        }
+        catch (error) {
+            return errorContent("Failed to get edit history. Please try again.");
+        }
+    });
+}

package/dist/oauth/authorize.d.ts

@@ -0,0 +1,27 @@
+/**
+ * OAuth Authorization Endpoint
+ *
+ * GET /oauth/authorize — MCP OAuth 2.1 authorization endpoint.
+ *
+ * Shows a login page with GitHub as the primary auth method and a
+ * subtle link to fall back to Harper credentials. If the user has an
+ * active session (from a prior GitHub login), issues an auth code
+ * immediately.
+ *
+ * Org membership is checked against the ALLOWED_GITHUB_ORGS env var
+ * for GitHub logins. Harper credential logins bypass org checks.
+ */
+import type { HarperRequest } from "../types.ts";
+/**
+ * Handle GET /oauth/authorize
+ *
+ * Three modes:
+ * 1. Returning from GitHub login (`pending` param) — complete authorization.
+ * 2. User already has a session — issue auth code directly.
+ * 3. First visit — show login page with GitHub button + Harper credentials.
+ */
+export declare function handleAuthorizeGet(request: HarperRequest): Promise<Response>;
+/**
+ * Handle POST /oauth/authorize — Harper credential login.
+ */
+export declare function handleAuthorizePost(request: HarperRequest): Promise<Response>;