@revealui/mcp 0.6.2 → 0.7.1

package/dist/servers/factories/knowledge-graph.d.ts

@@ -0,0 +1,272 @@
+/**
+ * Factory for the `knowledge-graph` MCP server (GAP-349 P2 — agent surfaces for
+ * the fleet knowledge graph; P1 shipped the schema + `@revealui/knowledge-graph`
+ * core in revealui#1858).
+ *
+ * Tools exposed:
+ *   kg_search       — hybrid retrieval (vector + FTS + BFS traversal, RRF-fused)
+ *   kg_get_node     — fetch a node + its current facts by natural key
+ *   kg_neighbors    — BFS neighbors of a node (current or point-in-time)
+ *   kg_add_episode  — THE ONLY WRITE TOOL. Additive ingestion (never a rescan).
+ *   kg_path         — shortest path between two nodes
+ *   kg_at_time      — a node's facts as of a point-in-time timestamp
+ *   kg_context      — budgeted context assembly (design spec §8.4): BFS from an
+ *                      anchor, rerank by node-distance + episode-mentions, pack
+ *                      node summaries + edge facts (with provenance episode ids)
+ *                      into a text block capped at `charBudget` characters.
+ *
+ * All tools operate over a `KgExecutor` (the driver-agnostic query interface
+ * `@revealui/knowledge-graph` already exposes for Neon-in-prod / PGlite-in-tests
+ * parity). Production resolves a pooled executor lazily from `@revealui/db/pool`
+ * (the same connection pattern `revkg`'s CLI uses — extend, not duplicate); tests
+ * inject a PGlite-backed executor via `CreateKnowledgeGraphServerOptions.executor`.
+ *
+ * Read tools degrade gracefully with no pgvector and no embeddings present:
+ * `kgSearch`'s vector channel is skipped whenever no query embedding is
+ * supplied, and query-embedding generation here is best-effort — an
+ * `@revealui/ai` import failure or an Ollama-down `generateEmbedding()` call
+ * both fall back to FTS + BFS only, never a hard failure.
+ *
+ * `kg_add_episode` is the only write tool. It always calls the additive
+ * `ingestEpisode` (never `applyScan`, which is the deterministic-rescan path
+ * reserved for `revkg scan`), Zod-validates `episodeType` plus every node kind
+ * and edge relation against the ontology enums, and accepts no raw SQL or
+ * table-name input of any kind.
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { type Embedder, type KgExecutor } from '@revealui/knowledge-graph';
+import { z } from 'zod/v4';
+export declare const KgSearchArgsSchema: z.ZodObject<{
+    query: z.ZodString;
+    anchor: z.ZodOptional<z.ZodString>;
+    kinds: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        symbol: "symbol";
+        file: "file";
+        skill: "skill";
+        agent: "agent";
+        dependency: "dependency";
+        rule: "rule";
+        repo: "repo";
+        package: "package";
+        app: "app";
+        "db-table": "db-table";
+        route: "route";
+        "mcp-tool": "mcp-tool";
+        hook: "hook";
+        gap: "gap";
+        lane: "lane";
+        adr: "adr";
+        "secret-path": "secret-path";
+        workflow: "workflow";
+        concept: "concept";
+    }>>>;
+    relations: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        blocks: "blocks";
+        exports: "exports";
+        contains: "contains";
+        imports: "imports";
+        "depends-on": "depends-on";
+        documents: "documents";
+        decides: "decides";
+        tracks: "tracks";
+        implements: "implements";
+        supersedes: "supersedes";
+        guards: "guards";
+        invokes: "invokes";
+        "stores-in": "stores-in";
+        syncs: "syncs";
+        mentions: "mentions";
+        discovered: "discovered";
+        "relates-to": "relates-to";
+    }>>>;
+    at: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    bfsDepth: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export declare const KgGetNodeArgsSchema: z.ZodObject<{
+    naturalKey: z.ZodString;
+}, z.core.$strict>;
+export declare const KgNeighborsArgsSchema: z.ZodObject<{
+    naturalKey: z.ZodString;
+    depth: z.ZodOptional<z.ZodNumber>;
+    relations: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        blocks: "blocks";
+        exports: "exports";
+        contains: "contains";
+        imports: "imports";
+        "depends-on": "depends-on";
+        documents: "documents";
+        decides: "decides";
+        tracks: "tracks";
+        implements: "implements";
+        supersedes: "supersedes";
+        guards: "guards";
+        invokes: "invokes";
+        "stores-in": "stores-in";
+        syncs: "syncs";
+        mentions: "mentions";
+        discovered: "discovered";
+        "relates-to": "relates-to";
+    }>>>;
+    at: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const KgAddEpisodeArgsSchema: z.ZodObject<{
+    episodeType: z.ZodEnum<{
+        json: "json";
+        manual: "manual";
+        "code-scan": "code-scan";
+        "git-commit": "git-commit";
+        doc: "doc";
+        "agent-fact": "agent-fact";
+        memory: "memory";
+    }>;
+    source: z.ZodString;
+    content: z.ZodOptional<z.ZodString>;
+    contentRef: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    referenceTime: z.ZodOptional<z.ZodString>;
+    siteId: z.ZodOptional<z.ZodString>;
+    nodes: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            symbol: "symbol";
+            file: "file";
+            skill: "skill";
+            agent: "agent";
+            dependency: "dependency";
+            rule: "rule";
+            repo: "repo";
+            package: "package";
+            app: "app";
+            "db-table": "db-table";
+            route: "route";
+            "mcp-tool": "mcp-tool";
+            hook: "hook";
+            gap: "gap";
+            lane: "lane";
+            adr: "adr";
+            "secret-path": "secret-path";
+            workflow: "workflow";
+            concept: "concept";
+        }>;
+        name: z.ZodString;
+        naturalKey: z.ZodString;
+        repo: z.ZodOptional<z.ZodString>;
+        summary: z.ZodOptional<z.ZodString>;
+        attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strict>>>;
+    edges: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        source: z.ZodObject<{
+            kind: z.ZodEnum<{
+                symbol: "symbol";
+                file: "file";
+                skill: "skill";
+                agent: "agent";
+                dependency: "dependency";
+                rule: "rule";
+                repo: "repo";
+                package: "package";
+                app: "app";
+                "db-table": "db-table";
+                route: "route";
+                "mcp-tool": "mcp-tool";
+                hook: "hook";
+                gap: "gap";
+                lane: "lane";
+                adr: "adr";
+                "secret-path": "secret-path";
+                workflow: "workflow";
+                concept: "concept";
+            }>;
+            naturalKey: z.ZodString;
+        }, z.core.$strict>;
+        target: z.ZodObject<{
+            kind: z.ZodEnum<{
+                symbol: "symbol";
+                file: "file";
+                skill: "skill";
+                agent: "agent";
+                dependency: "dependency";
+                rule: "rule";
+                repo: "repo";
+                package: "package";
+                app: "app";
+                "db-table": "db-table";
+                route: "route";
+                "mcp-tool": "mcp-tool";
+                hook: "hook";
+                gap: "gap";
+                lane: "lane";
+                adr: "adr";
+                "secret-path": "secret-path";
+                workflow: "workflow";
+                concept: "concept";
+            }>;
+            naturalKey: z.ZodString;
+        }, z.core.$strict>;
+        relation: z.ZodEnum<{
+            blocks: "blocks";
+            exports: "exports";
+            contains: "contains";
+            imports: "imports";
+            "depends-on": "depends-on";
+            documents: "documents";
+            decides: "decides";
+            tracks: "tracks";
+            implements: "implements";
+            supersedes: "supersedes";
+            guards: "guards";
+            invokes: "invokes";
+            "stores-in": "stores-in";
+            syncs: "syncs";
+            mentions: "mentions";
+            discovered: "discovered";
+            "relates-to": "relates-to";
+        }>;
+        fact: z.ZodString;
+        repo: z.ZodOptional<z.ZodString>;
+        validAt: z.ZodOptional<z.ZodString>;
+        attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export declare const KgPathArgsSchema: z.ZodObject<{
+    fromNaturalKey: z.ZodString;
+    toNaturalKey: z.ZodString;
+    at: z.ZodOptional<z.ZodString>;
+    maxDepth: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export declare const KgAtTimeArgsSchema: z.ZodObject<{
+    naturalKey: z.ZodString;
+    at: z.ZodString;
+}, z.core.$strict>;
+export declare const KgContextArgsSchema: z.ZodObject<{
+    naturalKey: z.ZodString;
+    charBudget: z.ZodOptional<z.ZodNumber>;
+    depth: z.ZodOptional<z.ZodNumber>;
+    at: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export interface AssembledContext {
+    context: string;
+    anchor: {
+        id: string;
+        naturalKey: string;
+    };
+    nodeCount: number;
+    factCount: number;
+    charBudget: number;
+    charsUsed: number;
+    truncated: boolean;
+}
+export interface CreateKnowledgeGraphServerOptions {
+    /** Injected executor. Tests pass a PGlite-backed `KgExecutor`; production omits this and resolves lazily from `@revealui/db/pool`. */
+    executor?: KgExecutor;
+    /** Injected embedder. Tests can stub; production omits this and resolves lazily from `@revealui/ai/embeddings`, degrading to `undefined` (no vector channel) when unavailable. */
+    embedder?: Embedder;
+    /** siteId stamped on episodes ingested via `kg_add_episode`. Defaults to `os.hostname()`. */
+    siteId?: string;
+}
+/**
+ * Create a fresh `knowledge-graph` MCP Server instance. Safe to call multiple
+ * times — each call returns an independent Server with its own request
+ * handlers and its own lazily-resolved executor/embedder cache.
+ */
+export declare function createKnowledgeGraphServer(options?: CreateKnowledgeGraphServerOptions): Server;
+//# sourceMappingURL=knowledge-graph.d.ts.map

package/dist/servers/factories/knowledge-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-graph.d.ts","sourceRoot":"","sources":["../../../src/servers/factories/knowledge-graph.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAGH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAQnE,OAAO,EAIL,KAAK,QAAQ,EAEb,KAAK,UAAU,EAShB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AA6B3B,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAUpB,CAAC;AAEZ,eAAO,MAAM,mBAAmB;;kBAIrB,CAAC;AAEZ,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;kBAOvB,CAAC;AAgCZ,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAWxB,CAAC;AAEZ,eAAO,MAAM,gBAAgB;;;;;kBAOlB,CAAC;AAEZ,eAAO,MAAM,kBAAkB;;;kBAKpB,CAAC;AAEZ,eAAO,MAAM,mBAAmB;;;;;kBAOrB,CAAC;AAiPZ,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;CACpB;AAgID,MAAM,WAAW,iCAAiC;IAChD,sIAAsI;IACtI,QAAQ,CAAC,EAAE,UAAU,CAAC;IACtB,kLAAkL;IAClL,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,6FAA6F;IAC7F,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,CAAC,EAAE,iCAAiC,GAAG,MAAM,CAmP9F"}