@promptev/context-engine 0.0.0

package/dist/mcp.cjs

@@ -0,0 +1,181 @@
+'use strict';
+
+// src/errors.ts
+var ExtraMissingError = class extends Error {
+  constructor(extra, pkg, what) {
+    super(`${what} requires the '${pkg}' package (optional extra: ${extra}): npm install ${pkg}`);
+    this.name = "ExtraMissingError";
+  }
+};
+
+// src/extras.ts
+async function requireExtra(specifier, extra, what) {
+  try {
+    return await import(specifier);
+  } catch (_err) {
+    throw new ExtraMissingError(extra, specifier, what);
+  }
+}
+
+// src/tools/mcp-tools.ts
+var SCOPE_NOTE = " Results are scoped to the caller's permissions (resolved by the server's injected principals dependency \u2014 never a caller-supplied argument) and to the given source_ids, if any.";
+async function resolvePrincipalsFn(principals) {
+  const result = await Promise.resolve(principals());
+  return result;
+}
+function registerToolGateway(mcp, engine, principals) {
+  mcp.tool(
+    "search_tools",
+    "Keyword search over the tools this deployment has registered (http/db/mcp/function) \u2014 the ACL-visible name, kind, description, and JSON Schema params of each match, so a caller can discover what it can then invoke with `execute_tool`." + SCOPE_NOTE,
+    { query: { type: "string" }, limit: { type: "number" } },
+    async (...raw) => {
+      const args = raw[0] ?? {};
+      const callerPrincipals = await resolvePrincipalsFn(principals);
+      const tools = await engine.searchTools(String(args.query ?? ""), {
+        principals: callerPrincipals,
+        limit: args.limit ?? 10
+      });
+      return { tools };
+    }
+  );
+  mcp.tool(
+    "execute_tool",
+    "Governed execution of a tool previously discovered via `search_tools` (ACL check, approval gate, audit). Returns `{result, usage}` on success, or an `approval_required` payload when the call needs a human approval that isn't already granted \u2014 the caller must not retry until that approval resolves." + SCOPE_NOTE,
+    { name: { type: "string" }, args: { type: "object" } },
+    async (...raw) => {
+      const body = raw[0] ?? {};
+      const callerPrincipals = await resolvePrincipalsFn(principals);
+      return engine.executeTool(String(body.name), body.args ?? null, {
+        principals: callerPrincipals,
+        source: "mcp"
+      });
+    }
+  );
+}
+
+// src/version.ts
+var __version__ = "0.0.0";
+
+// src/mcp.ts
+function asMcpResult(data) {
+  return { content: [{ type: "text", text: JSON.stringify(data) }] };
+}
+async function createMcpApp(engine, opts) {
+  if (!opts?.principals) {
+    throw new TypeError("createMcpApp requires principals");
+  }
+  let McpServer;
+  let StreamableHTTPServerTransport;
+  try {
+    const serverMod = await requireExtra(
+      "@modelcontextprotocol/sdk/server/mcp.js",
+      "mcp",
+      "MCP server"
+    );
+    const httpMod = await requireExtra("@modelcontextprotocol/sdk/server/streamableHttp.js", "mcp", "MCP server");
+    McpServer = serverMod.McpServer;
+    StreamableHTTPServerTransport = httpMod.StreamableHTTPServerTransport;
+  } catch (exc) {
+    if (exc instanceof ExtraMissingError) throw exc;
+    throw new ExtraMissingError("mcp", "@modelcontextprotocol/sdk", "MCP server");
+  }
+  const mcp = new McpServer({ name: "context-engine", version: __version__ });
+  const tool = (name, description, schema, handler2) => {
+    mcp.tool(
+      name,
+      description,
+      schema,
+      async (args) => asMcpResult(await handler2(args))
+    );
+  };
+  tool(
+    "search_knowledge_base",
+    `Hybrid search (full-text + trigram + vector, RRF-fused) over the ingested corpus. Returns the top-matching chunks with their source document.${SCOPE_NOTE}`,
+    {
+      query: { type: "string" },
+      source_ids: { type: "array", items: { type: "string" } },
+      top_k: { type: "number" },
+      mode: { type: "string", enum: ["hybrid", "graph"] }
+    },
+    async (args) => {
+      const callerPrincipals = await resolvePrincipalsFn(opts.principals);
+      const result = await engine.search(String(args.query ?? ""), {
+        sourceIds: args.source_ids,
+        principals: callerPrincipals,
+        topK: args.top_k ?? 10,
+        mode: args.mode ?? "hybrid"
+      });
+      return {
+        hits: (result.hits ?? []).map((hit) => {
+          const h = hit;
+          return {
+            document_name: h.document_name ?? h.documentName,
+            chunk_text: h.chunk_text ?? h.chunkText,
+            score: h.score,
+            source_id: h.source_id ?? h.sourceId
+          };
+        }),
+        usage: result.usage
+      };
+    }
+  );
+  tool(
+    "get_document",
+    `Fetch one document's full text and metadata by id.${SCOPE_NOTE}`,
+    { document_id: { type: "string" } },
+    async (args) => {
+      const callerPrincipals = await resolvePrincipalsFn(opts.principals);
+      return engine.getDocument(String(args.document_id), { principals: callerPrincipals });
+    }
+  );
+  if (engine.config.llm != null) {
+    tool(
+      "query_structured",
+      `Answer a question against documents' extracted structured data (only documents with structured data are candidates).${SCOPE_NOTE}`,
+      { question: { type: "string" }, source_ids: { type: "array", items: { type: "string" } } },
+      async (args) => {
+        const callerPrincipals = await resolvePrincipalsFn(opts.principals);
+        if (!engine.queryStructured) throw new Error("queryStructured is not available on this engine");
+        return engine.queryStructured(String(args.question), {
+          sourceIds: args.source_ids,
+          principals: callerPrincipals
+        });
+      }
+    );
+    if (engine.config.enableCodeExecution) {
+      tool(
+        "compute",
+        `Run LLM-authored JavaScript over in-scope spreadsheet documents and return the computed result.${SCOPE_NOTE}`,
+        { instruction: { type: "string" }, source_ids: { type: "array", items: { type: "string" } } },
+        async (args) => {
+          const callerPrincipals = await resolvePrincipalsFn(opts.principals);
+          if (!engine.compute) throw new Error("compute is not available on this engine");
+          return engine.compute(String(args.instruction), {
+            sourceIds: args.source_ids,
+            principals: callerPrincipals
+          });
+        }
+      );
+    }
+  }
+  registerToolGateway(
+    {
+      tool: (name, description, schema, handler2) => {
+        tool(name, description, schema, async (args) => handler2(args));
+      }
+    },
+    engine,
+    opts.principals
+  );
+  const handler = (async (req, res) => {
+    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: void 0 });
+    await mcp.connect(transport);
+    await transport.handleRequest(req, res);
+  });
+  handler.mcp = mcp;
+  return handler;
+}
+
+exports.createMcpApp = createMcpApp;
+//# sourceMappingURL=mcp.cjs.map
+//# sourceMappingURL=mcp.cjs.map

package/dist/mcp.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/extras.ts","../src/tools/mcp-tools.ts","../src/version.ts","../src/mcp.ts"],"names":["handler"],"mappings":"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","file":"mcp.cjs","sourcesContent":["/** Action-surface errors — user-facing / data-dependent failures (not found, ACL, bad input).\n *  Config/programming errors stay as TypeError / RangeError / Error.\n */\nexport class EngineActionError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"EngineActionError\";\n  }\n}\n\n/** Missing vs forbidden document: identical message so callers cannot distinguish. */\nexport class DocumentNotFoundError extends Error {\n  constructor(documentId: string) {\n    super(`document not found: ${documentId}`);\n    this.name = \"DocumentNotFoundError\";\n  }\n}\n\nexport class GraphLegUnavailable extends Error {\n  constructor(message = \"graph ranked list was not supplied\") {\n    super(message);\n    this.name = \"GraphLegUnavailable\";\n  }\n}\n\nexport class ApprovalNotPending extends Error {\n  constructor(message = \"approval is not pending\") {\n    super(message);\n    this.name = \"ApprovalNotPending\";\n  }\n}\n\nexport class ApprovalExpired extends Error {\n  constructor(message = \"approval has expired\") {\n    super(message);\n    this.name = \"ApprovalExpired\";\n  }\n}\n\nexport class CodeExecutionError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"CodeExecutionError\";\n  }\n}\n\nexport class CodeExecutionTimeout extends Error {\n  constructor(message = \"code execution timed out\") {\n    super(message);\n    this.name = \"CodeExecutionTimeout\";\n  }\n}\n\nexport class ExtraMissingError extends Error {\n  constructor(extra: string, pkg: string, what: string) {\n    super(`${what} requires the '${pkg}' package (optional extra: ${extra}): npm install ${pkg}`);\n    this.name = \"ExtraMissingError\";\n  }\n}\n","import { ExtraMissingError } from \"./errors.js\";\n\nexport async function tryImport<T = unknown>(specifier: string): Promise<T | null> {\n  try {\n    return (await import(specifier)) as T;\n  } catch {\n    return null;\n  }\n}\n\nexport async function requireExtra<T = unknown>(specifier: string, extra: string, what: string): Promise<T> {\n  try {\n    return (await import(specifier)) as T;\n  } catch (_err) {\n    throw new ExtraMissingError(extra, specifier, what);\n  }\n}\n","export type PrincipalsFn = () => unknown | Promise<unknown>;\n\nexport const SCOPE_NOTE =\n  \" Results are scoped to the caller's permissions (resolved by the server's \" +\n  \"injected principals dependency — never a caller-supplied argument) and to \" +\n  \"the given source_ids, if any.\";\n\nexport async function resolvePrincipalsFn(principals: PrincipalsFn): Promise<string[] | null> {\n  const result = await Promise.resolve(principals());\n  return result as string[] | null;\n}\n\nexport type McpToolHost = {\n  tool(\n    name: string,\n    description: string,\n    schema: Record<string, unknown>,\n    handler: (...args: never[]) => Promise<unknown>,\n  ): unknown;\n};\n\nexport function registerToolGateway(\n  mcp: McpToolHost,\n  engine: {\n    searchTools: (query: string, opts?: Record<string, unknown>) => Promise<unknown[]>;\n    executeTool: (\n      name: string,\n      args: Record<string, unknown> | null,\n      opts?: Record<string, unknown>,\n    ) => Promise<Record<string, unknown>>;\n  },\n  principals: PrincipalsFn,\n): void {\n  mcp.tool(\n    \"search_tools\",\n    \"Keyword search over the tools this deployment has registered \" +\n      \"(http/db/mcp/function) — the ACL-visible name, kind, description, \" +\n      \"and JSON Schema params of each match, so a caller can discover what \" +\n      \"it can then invoke with `execute_tool`.\" +\n      SCOPE_NOTE,\n    { query: { type: \"string\" }, limit: { type: \"number\" } },\n    async (...raw: never[]) => {\n      const args = (raw[0] ?? {}) as { query?: string; limit?: number };\n      const callerPrincipals = await resolvePrincipalsFn(principals);\n      const tools = await engine.searchTools(String(args.query ?? \"\"), {\n        principals: callerPrincipals,\n        limit: args.limit ?? 10,\n      });\n      return { tools };\n    },\n  );\n\n  mcp.tool(\n    \"execute_tool\",\n    \"Governed execution of a tool previously discovered via \" +\n      \"`search_tools` (ACL check, approval gate, audit). Returns \" +\n      \"`{result, usage}` on success, or an `approval_required` payload \" +\n      \"when the call needs a human approval that isn't already granted — \" +\n      \"the caller must not retry until that approval resolves.\" +\n      SCOPE_NOTE,\n    { name: { type: \"string\" }, args: { type: \"object\" } },\n    async (...raw: never[]) => {\n      const body = (raw[0] ?? {}) as { name?: string; args?: Record<string, unknown> };\n      const callerPrincipals = await resolvePrincipalsFn(principals);\n      return engine.executeTool(String(body.name), body.args ?? null, {\n        principals: callerPrincipals,\n        source: \"mcp\",\n      });\n    },\n  );\n}\n","/** Bumped by CI on every main merge; 0.0.0 = pre-first-release. */\nexport const __version__ = \"0.0.0\";\n","import { ExtraMissingError } from \"./errors.js\";\nimport { requireExtra } from \"./extras.js\";\nimport {\n  type PrincipalsFn,\n  registerToolGateway,\n  resolvePrincipalsFn,\n  SCOPE_NOTE,\n} from \"./tools/mcp-tools.js\";\nimport { __version__ } from \"./version.js\";\n\ntype Engine = {\n  config: { llm?: unknown; enableCodeExecution?: boolean };\n  search: (query: string, opts?: Record<string, unknown>) => Promise<{ hits: unknown[]; usage?: unknown }>;\n  getDocument: (id: string, opts?: Record<string, unknown>) => Promise<unknown>;\n  queryStructured?: (question: string, opts?: Record<string, unknown>) => Promise<unknown>;\n  compute?: (instruction: string, opts?: Record<string, unknown>) => Promise<unknown>;\n  searchTools: (query: string, opts?: Record<string, unknown>) => Promise<unknown[]>;\n  executeTool: (\n    name: string,\n    args: Record<string, unknown> | null,\n    opts?: Record<string, unknown>,\n  ) => Promise<Record<string, unknown>>;\n};\n\nfunction asMcpResult(data: unknown): { content: Array<{ type: \"text\"; text: string }> } {\n  return { content: [{ type: \"text\", text: JSON.stringify(data) }] };\n}\n\nexport async function createMcpApp(\n  engine: Engine,\n  opts: { principals: PrincipalsFn },\n): Promise<\n  ((req: import(\"node:http\").IncomingMessage, res: import(\"node:http\").ServerResponse) => Promise<void>) & {\n    mcp: unknown;\n  }\n> {\n  if (!opts?.principals) {\n    throw new TypeError(\"createMcpApp requires principals\");\n  }\n\n  let McpServer: new (info: {\n    name: string;\n    version: string;\n  }) => {\n    tool: (...args: unknown[]) => unknown;\n    connect: (t: unknown) => Promise<void>;\n  };\n  let StreamableHTTPServerTransport: new (opts: {\n    sessionIdGenerator?: undefined;\n  }) => {\n    handleRequest: (req: unknown, res: unknown, body?: unknown) => Promise<void>;\n  };\n  try {\n    const serverMod = await requireExtra<{ McpServer: typeof McpServer }>(\n      \"@modelcontextprotocol/sdk/server/mcp.js\",\n      \"mcp\",\n      \"MCP server\",\n    );\n    const httpMod = await requireExtra<{\n      StreamableHTTPServerTransport: typeof StreamableHTTPServerTransport;\n    }>(\"@modelcontextprotocol/sdk/server/streamableHttp.js\", \"mcp\", \"MCP server\");\n    McpServer = serverMod.McpServer;\n    StreamableHTTPServerTransport = httpMod.StreamableHTTPServerTransport;\n  } catch (exc) {\n    if (exc instanceof ExtraMissingError) throw exc;\n    throw new ExtraMissingError(\"mcp\", \"@modelcontextprotocol/sdk\", \"MCP server\");\n  }\n\n  const mcp = new McpServer({ name: \"context-engine\", version: __version__ });\n\n  const tool = (\n    name: string,\n    description: string,\n    schema: Record<string, unknown>,\n    handler: (args: Record<string, unknown>) => Promise<unknown>,\n  ) => {\n    mcp.tool(name, description, schema, async (args: Record<string, unknown>) =>\n      asMcpResult(await handler(args)),\n    );\n  };\n\n  tool(\n    \"search_knowledge_base\",\n    `Hybrid search (full-text + trigram + vector, RRF-fused) over the ingested corpus. Returns the top-matching chunks with their source document.${SCOPE_NOTE}`,\n    {\n      query: { type: \"string\" },\n      source_ids: { type: \"array\", items: { type: \"string\" } },\n      top_k: { type: \"number\" },\n      mode: { type: \"string\", enum: [\"hybrid\", \"graph\"] },\n    },\n    async (args) => {\n      const callerPrincipals = await resolvePrincipalsFn(opts.principals);\n      const result = await engine.search(String(args.query ?? \"\"), {\n        sourceIds: args.source_ids,\n        principals: callerPrincipals,\n        topK: args.top_k ?? 10,\n        mode: args.mode ?? \"hybrid\",\n      });\n      return {\n        hits: (result.hits ?? []).map((hit) => {\n          const h = hit as Record<string, unknown>;\n          return {\n            document_name: h.document_name ?? h.documentName,\n            chunk_text: h.chunk_text ?? h.chunkText,\n            score: h.score,\n            source_id: h.source_id ?? h.sourceId,\n          };\n        }),\n        usage: result.usage,\n      };\n    },\n  );\n\n  tool(\n    \"get_document\",\n    `Fetch one document's full text and metadata by id.${SCOPE_NOTE}`,\n    { document_id: { type: \"string\" } },\n    async (args) => {\n      const callerPrincipals = await resolvePrincipalsFn(opts.principals);\n      return engine.getDocument(String(args.document_id), { principals: callerPrincipals });\n    },\n  );\n\n  if (engine.config.llm != null) {\n    tool(\n      \"query_structured\",\n      `Answer a question against documents' extracted structured data (only documents with structured data are candidates).${SCOPE_NOTE}`,\n      { question: { type: \"string\" }, source_ids: { type: \"array\", items: { type: \"string\" } } },\n      async (args) => {\n        const callerPrincipals = await resolvePrincipalsFn(opts.principals);\n        if (!engine.queryStructured) throw new Error(\"queryStructured is not available on this engine\");\n        return engine.queryStructured(String(args.question), {\n          sourceIds: args.source_ids,\n          principals: callerPrincipals,\n        });\n      },\n    );\n    if (engine.config.enableCodeExecution) {\n      tool(\n        \"compute\",\n        `Run LLM-authored JavaScript over in-scope spreadsheet documents and return the computed result.${SCOPE_NOTE}`,\n        { instruction: { type: \"string\" }, source_ids: { type: \"array\", items: { type: \"string\" } } },\n        async (args) => {\n          const callerPrincipals = await resolvePrincipalsFn(opts.principals);\n          if (!engine.compute) throw new Error(\"compute is not available on this engine\");\n          return engine.compute(String(args.instruction), {\n            sourceIds: args.source_ids,\n            principals: callerPrincipals,\n          });\n        },\n      );\n    }\n  }\n\n  registerToolGateway(\n    {\n      tool: (name, description, schema, handler) => {\n        tool(name, description, schema, async (args) => handler(args as never));\n      },\n    },\n    engine,\n    opts.principals,\n  );\n\n  const handler = (async (\n    req: import(\"node:http\").IncomingMessage,\n    res: import(\"node:http\").ServerResponse,\n  ) => {\n    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });\n    await mcp.connect(transport);\n    await transport.handleRequest(req, res);\n  }) as ((\n    req: import(\"node:http\").IncomingMessage,\n    res: import(\"node:http\").ServerResponse,\n  ) => Promise<void>) & { mcp: unknown };\n  handler.mcp = mcp;\n  return handler;\n}\n"]}

package/dist/mcp.d.cts

@@ -0,0 +1,26 @@
+import * as node_http from 'node:http';
+
+type PrincipalsFn = () => unknown | Promise<unknown>;
+
+type Engine = {
+    config: {
+        llm?: unknown;
+        enableCodeExecution?: boolean;
+    };
+    search: (query: string, opts?: Record<string, unknown>) => Promise<{
+        hits: unknown[];
+        usage?: unknown;
+    }>;
+    getDocument: (id: string, opts?: Record<string, unknown>) => Promise<unknown>;
+    queryStructured?: (question: string, opts?: Record<string, unknown>) => Promise<unknown>;
+    compute?: (instruction: string, opts?: Record<string, unknown>) => Promise<unknown>;
+    searchTools: (query: string, opts?: Record<string, unknown>) => Promise<unknown[]>;
+    executeTool: (name: string, args: Record<string, unknown> | null, opts?: Record<string, unknown>) => Promise<Record<string, unknown>>;
+};
+declare function createMcpApp(engine: Engine, opts: {
+    principals: PrincipalsFn;
+}): Promise<((req: node_http.IncomingMessage, res: node_http.ServerResponse) => Promise<void>) & {
+    mcp: unknown;
+}>;
+
+export { createMcpApp };

package/dist/mcp.d.ts

@@ -0,0 +1,26 @@
+import * as node_http from 'node:http';
+
+type PrincipalsFn = () => unknown | Promise<unknown>;
+
+type Engine = {
+    config: {
+        llm?: unknown;
+        enableCodeExecution?: boolean;
+    };
+    search: (query: string, opts?: Record<string, unknown>) => Promise<{
+        hits: unknown[];
+        usage?: unknown;
+    }>;
+    getDocument: (id: string, opts?: Record<string, unknown>) => Promise<unknown>;
+    queryStructured?: (question: string, opts?: Record<string, unknown>) => Promise<unknown>;
+    compute?: (instruction: string, opts?: Record<string, unknown>) => Promise<unknown>;
+    searchTools: (query: string, opts?: Record<string, unknown>) => Promise<unknown[]>;
+    executeTool: (name: string, args: Record<string, unknown> | null, opts?: Record<string, unknown>) => Promise<Record<string, unknown>>;
+};
+declare function createMcpApp(engine: Engine, opts: {
+    principals: PrincipalsFn;
+}): Promise<((req: node_http.IncomingMessage, res: node_http.ServerResponse) => Promise<void>) & {
+    mcp: unknown;
+}>;
+
+export { createMcpApp };

package/dist/mcp.js

@@ -0,0 +1,179 @@
+// src/errors.ts
+var ExtraMissingError = class extends Error {
+  constructor(extra, pkg, what) {
+    super(`${what} requires the '${pkg}' package (optional extra: ${extra}): npm install ${pkg}`);
+    this.name = "ExtraMissingError";
+  }
+};
+
+// src/extras.ts
+async function requireExtra(specifier, extra, what) {
+  try {
+    return await import(specifier);
+  } catch (_err) {
+    throw new ExtraMissingError(extra, specifier, what);
+  }
+}
+
+// src/tools/mcp-tools.ts
+var SCOPE_NOTE = " Results are scoped to the caller's permissions (resolved by the server's injected principals dependency \u2014 never a caller-supplied argument) and to the given source_ids, if any.";
+async function resolvePrincipalsFn(principals) {
+  const result = await Promise.resolve(principals());
+  return result;
+}
+function registerToolGateway(mcp, engine, principals) {
+  mcp.tool(
+    "search_tools",
+    "Keyword search over the tools this deployment has registered (http/db/mcp/function) \u2014 the ACL-visible name, kind, description, and JSON Schema params of each match, so a caller can discover what it can then invoke with `execute_tool`." + SCOPE_NOTE,
+    { query: { type: "string" }, limit: { type: "number" } },
+    async (...raw) => {
+      const args = raw[0] ?? {};
+      const callerPrincipals = await resolvePrincipalsFn(principals);
+      const tools = await engine.searchTools(String(args.query ?? ""), {
+        principals: callerPrincipals,
+        limit: args.limit ?? 10
+      });
+      return { tools };
+    }
+  );
+  mcp.tool(
+    "execute_tool",
+    "Governed execution of a tool previously discovered via `search_tools` (ACL check, approval gate, audit). Returns `{result, usage}` on success, or an `approval_required` payload when the call needs a human approval that isn't already granted \u2014 the caller must not retry until that approval resolves." + SCOPE_NOTE,
+    { name: { type: "string" }, args: { type: "object" } },
+    async (...raw) => {
+      const body = raw[0] ?? {};
+      const callerPrincipals = await resolvePrincipalsFn(principals);
+      return engine.executeTool(String(body.name), body.args ?? null, {
+        principals: callerPrincipals,
+        source: "mcp"
+      });
+    }
+  );
+}
+
+// src/version.ts
+var __version__ = "0.0.0";
+
+// src/mcp.ts
+function asMcpResult(data) {
+  return { content: [{ type: "text", text: JSON.stringify(data) }] };
+}
+async function createMcpApp(engine, opts) {
+  if (!opts?.principals) {
+    throw new TypeError("createMcpApp requires principals");
+  }
+  let McpServer;
+  let StreamableHTTPServerTransport;
+  try {
+    const serverMod = await requireExtra(
+      "@modelcontextprotocol/sdk/server/mcp.js",
+      "mcp",
+      "MCP server"
+    );
+    const httpMod = await requireExtra("@modelcontextprotocol/sdk/server/streamableHttp.js", "mcp", "MCP server");
+    McpServer = serverMod.McpServer;
+    StreamableHTTPServerTransport = httpMod.StreamableHTTPServerTransport;
+  } catch (exc) {
+    if (exc instanceof ExtraMissingError) throw exc;
+    throw new ExtraMissingError("mcp", "@modelcontextprotocol/sdk", "MCP server");
+  }
+  const mcp = new McpServer({ name: "context-engine", version: __version__ });
+  const tool = (name, description, schema, handler2) => {
+    mcp.tool(
+      name,
+      description,
+      schema,
+      async (args) => asMcpResult(await handler2(args))
+    );
+  };
+  tool(
+    "search_knowledge_base",
+    `Hybrid search (full-text + trigram + vector, RRF-fused) over the ingested corpus. Returns the top-matching chunks with their source document.${SCOPE_NOTE}`,
+    {
+      query: { type: "string" },
+      source_ids: { type: "array", items: { type: "string" } },
+      top_k: { type: "number" },
+      mode: { type: "string", enum: ["hybrid", "graph"] }
+    },
+    async (args) => {
+      const callerPrincipals = await resolvePrincipalsFn(opts.principals);
+      const result = await engine.search(String(args.query ?? ""), {
+        sourceIds: args.source_ids,
+        principals: callerPrincipals,
+        topK: args.top_k ?? 10,
+        mode: args.mode ?? "hybrid"
+      });
+      return {
+        hits: (result.hits ?? []).map((hit) => {
+          const h = hit;
+          return {
+            document_name: h.document_name ?? h.documentName,
+            chunk_text: h.chunk_text ?? h.chunkText,
+            score: h.score,
+            source_id: h.source_id ?? h.sourceId
+          };
+        }),
+        usage: result.usage
+      };
+    }
+  );
+  tool(
+    "get_document",
+    `Fetch one document's full text and metadata by id.${SCOPE_NOTE}`,
+    { document_id: { type: "string" } },
+    async (args) => {
+      const callerPrincipals = await resolvePrincipalsFn(opts.principals);
+      return engine.getDocument(String(args.document_id), { principals: callerPrincipals });
+    }
+  );
+  if (engine.config.llm != null) {
+    tool(
+      "query_structured",
+      `Answer a question against documents' extracted structured data (only documents with structured data are candidates).${SCOPE_NOTE}`,
+      { question: { type: "string" }, source_ids: { type: "array", items: { type: "string" } } },
+      async (args) => {
+        const callerPrincipals = await resolvePrincipalsFn(opts.principals);
+        if (!engine.queryStructured) throw new Error("queryStructured is not available on this engine");
+        return engine.queryStructured(String(args.question), {
+          sourceIds: args.source_ids,
+          principals: callerPrincipals
+        });
+      }
+    );
+    if (engine.config.enableCodeExecution) {
+      tool(
+        "compute",
+        `Run LLM-authored JavaScript over in-scope spreadsheet documents and return the computed result.${SCOPE_NOTE}`,
+        { instruction: { type: "string" }, source_ids: { type: "array", items: { type: "string" } } },
+        async (args) => {
+          const callerPrincipals = await resolvePrincipalsFn(opts.principals);
+          if (!engine.compute) throw new Error("compute is not available on this engine");
+          return engine.compute(String(args.instruction), {
+            sourceIds: args.source_ids,
+            principals: callerPrincipals
+          });
+        }
+      );
+    }
+  }
+  registerToolGateway(
+    {
+      tool: (name, description, schema, handler2) => {
+        tool(name, description, schema, async (args) => handler2(args));
+      }
+    },
+    engine,
+    opts.principals
+  );
+  const handler = (async (req, res) => {
+    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: void 0 });
+    await mcp.connect(transport);
+    await transport.handleRequest(req, res);
+  });
+  handler.mcp = mcp;
+  return handler;
+}
+
+export { createMcpApp };
+//# sourceMappingURL=mcp.js.map
+//# sourceMappingURL=mcp.js.map

package/dist/mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/extras.ts","../src/tools/mcp-tools.ts","../src/version.ts","../src/mcp.ts"],"names":["handler"],"mappings":"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","file":"mcp.js","sourcesContent":["/** Action-surface errors — user-facing / data-dependent failures (not found, ACL, bad input).\n *  Config/programming errors stay as TypeError / RangeError / Error.\n */\nexport class EngineActionError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"EngineActionError\";\n  }\n}\n\n/** Missing vs forbidden document: identical message so callers cannot distinguish. */\nexport class DocumentNotFoundError extends Error {\n  constructor(documentId: string) {\n    super(`document not found: ${documentId}`);\n    this.name = \"DocumentNotFoundError\";\n  }\n}\n\nexport class GraphLegUnavailable extends Error {\n  constructor(message = \"graph ranked list was not supplied\") {\n    super(message);\n    this.name = \"GraphLegUnavailable\";\n  }\n}\n\nexport class ApprovalNotPending extends Error {\n  constructor(message = \"approval is not pending\") {\n    super(message);\n    this.name = \"ApprovalNotPending\";\n  }\n}\n\nexport class ApprovalExpired extends Error {\n  constructor(message = \"approval has expired\") {\n    super(message);\n    this.name = \"ApprovalExpired\";\n  }\n}\n\nexport class CodeExecutionError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"CodeExecutionError\";\n  }\n}\n\nexport class CodeExecutionTimeout extends Error {\n  constructor(message = \"code execution timed out\") {\n    super(message);\n    this.name = \"CodeExecutionTimeout\";\n  }\n}\n\nexport class ExtraMissingError extends Error {\n  constructor(extra: string, pkg: string, what: string) {\n    super(`${what} requires the '${pkg}' package (optional extra: ${extra}): npm install ${pkg}`);\n    this.name = \"ExtraMissingError\";\n  }\n}\n","import { ExtraMissingError } from \"./errors.js\";\n\nexport async function tryImport<T = unknown>(specifier: string): Promise<T | null> {\n  try {\n    return (await import(specifier)) as T;\n  } catch {\n    return null;\n  }\n}\n\nexport async function requireExtra<T = unknown>(specifier: string, extra: string, what: string): Promise<T> {\n  try {\n    return (await import(specifier)) as T;\n  } catch (_err) {\n    throw new ExtraMissingError(extra, specifier, what);\n  }\n}\n","export type PrincipalsFn = () => unknown | Promise<unknown>;\n\nexport const SCOPE_NOTE =\n  \" Results are scoped to the caller's permissions (resolved by the server's \" +\n  \"injected principals dependency — never a caller-supplied argument) and to \" +\n  \"the given source_ids, if any.\";\n\nexport async function resolvePrincipalsFn(principals: PrincipalsFn): Promise<string[] | null> {\n  const result = await Promise.resolve(principals());\n  return result as string[] | null;\n}\n\nexport type McpToolHost = {\n  tool(\n    name: string,\n    description: string,\n    schema: Record<string, unknown>,\n    handler: (...args: never[]) => Promise<unknown>,\n  ): unknown;\n};\n\nexport function registerToolGateway(\n  mcp: McpToolHost,\n  engine: {\n    searchTools: (query: string, opts?: Record<string, unknown>) => Promise<unknown[]>;\n    executeTool: (\n      name: string,\n      args: Record<string, unknown> | null,\n      opts?: Record<string, unknown>,\n    ) => Promise<Record<string, unknown>>;\n  },\n  principals: PrincipalsFn,\n): void {\n  mcp.tool(\n    \"search_tools\",\n    \"Keyword search over the tools this deployment has registered \" +\n      \"(http/db/mcp/function) — the ACL-visible name, kind, description, \" +\n      \"and JSON Schema params of each match, so a caller can discover what \" +\n      \"it can then invoke with `execute_tool`.\" +\n      SCOPE_NOTE,\n    { query: { type: \"string\" }, limit: { type: \"number\" } },\n    async (...raw: never[]) => {\n      const args = (raw[0] ?? {}) as { query?: string; limit?: number };\n      const callerPrincipals = await resolvePrincipalsFn(principals);\n      const tools = await engine.searchTools(String(args.query ?? \"\"), {\n        principals: callerPrincipals,\n        limit: args.limit ?? 10,\n      });\n      return { tools };\n    },\n  );\n\n  mcp.tool(\n    \"execute_tool\",\n    \"Governed execution of a tool previously discovered via \" +\n      \"`search_tools` (ACL check, approval gate, audit). Returns \" +\n      \"`{result, usage}` on success, or an `approval_required` payload \" +\n      \"when the call needs a human approval that isn't already granted — \" +\n      \"the caller must not retry until that approval resolves.\" +\n      SCOPE_NOTE,\n    { name: { type: \"string\" }, args: { type: \"object\" } },\n    async (...raw: never[]) => {\n      const body = (raw[0] ?? {}) as { name?: string; args?: Record<string, unknown> };\n      const callerPrincipals = await resolvePrincipalsFn(principals);\n      return engine.executeTool(String(body.name), body.args ?? null, {\n        principals: callerPrincipals,\n        source: \"mcp\",\n      });\n    },\n  );\n}\n","/** Bumped by CI on every main merge; 0.0.0 = pre-first-release. */\nexport const __version__ = \"0.0.0\";\n","import { ExtraMissingError } from \"./errors.js\";\nimport { requireExtra } from \"./extras.js\";\nimport {\n  type PrincipalsFn,\n  registerToolGateway,\n  resolvePrincipalsFn,\n  SCOPE_NOTE,\n} from \"./tools/mcp-tools.js\";\nimport { __version__ } from \"./version.js\";\n\ntype Engine = {\n  config: { llm?: unknown; enableCodeExecution?: boolean };\n  search: (query: string, opts?: Record<string, unknown>) => Promise<{ hits: unknown[]; usage?: unknown }>;\n  getDocument: (id: string, opts?: Record<string, unknown>) => Promise<unknown>;\n  queryStructured?: (question: string, opts?: Record<string, unknown>) => Promise<unknown>;\n  compute?: (instruction: string, opts?: Record<string, unknown>) => Promise<unknown>;\n  searchTools: (query: string, opts?: Record<string, unknown>) => Promise<unknown[]>;\n  executeTool: (\n    name: string,\n    args: Record<string, unknown> | null,\n    opts?: Record<string, unknown>,\n  ) => Promise<Record<string, unknown>>;\n};\n\nfunction asMcpResult(data: unknown): { content: Array<{ type: \"text\"; text: string }> } {\n  return { content: [{ type: \"text\", text: JSON.stringify(data) }] };\n}\n\nexport async function createMcpApp(\n  engine: Engine,\n  opts: { principals: PrincipalsFn },\n): Promise<\n  ((req: import(\"node:http\").IncomingMessage, res: import(\"node:http\").ServerResponse) => Promise<void>) & {\n    mcp: unknown;\n  }\n> {\n  if (!opts?.principals) {\n    throw new TypeError(\"createMcpApp requires principals\");\n  }\n\n  let McpServer: new (info: {\n    name: string;\n    version: string;\n  }) => {\n    tool: (...args: unknown[]) => unknown;\n    connect: (t: unknown) => Promise<void>;\n  };\n  let StreamableHTTPServerTransport: new (opts: {\n    sessionIdGenerator?: undefined;\n  }) => {\n    handleRequest: (req: unknown, res: unknown, body?: unknown) => Promise<void>;\n  };\n  try {\n    const serverMod = await requireExtra<{ McpServer: typeof McpServer }>(\n      \"@modelcontextprotocol/sdk/server/mcp.js\",\n      \"mcp\",\n      \"MCP server\",\n    );\n    const httpMod = await requireExtra<{\n      StreamableHTTPServerTransport: typeof StreamableHTTPServerTransport;\n    }>(\"@modelcontextprotocol/sdk/server/streamableHttp.js\", \"mcp\", \"MCP server\");\n    McpServer = serverMod.McpServer;\n    StreamableHTTPServerTransport = httpMod.StreamableHTTPServerTransport;\n  } catch (exc) {\n    if (exc instanceof ExtraMissingError) throw exc;\n    throw new ExtraMissingError(\"mcp\", \"@modelcontextprotocol/sdk\", \"MCP server\");\n  }\n\n  const mcp = new McpServer({ name: \"context-engine\", version: __version__ });\n\n  const tool = (\n    name: string,\n    description: string,\n    schema: Record<string, unknown>,\n    handler: (args: Record<string, unknown>) => Promise<unknown>,\n  ) => {\n    mcp.tool(name, description, schema, async (args: Record<string, unknown>) =>\n      asMcpResult(await handler(args)),\n    );\n  };\n\n  tool(\n    \"search_knowledge_base\",\n    `Hybrid search (full-text + trigram + vector, RRF-fused) over the ingested corpus. Returns the top-matching chunks with their source document.${SCOPE_NOTE}`,\n    {\n      query: { type: \"string\" },\n      source_ids: { type: \"array\", items: { type: \"string\" } },\n      top_k: { type: \"number\" },\n      mode: { type: \"string\", enum: [\"hybrid\", \"graph\"] },\n    },\n    async (args) => {\n      const callerPrincipals = await resolvePrincipalsFn(opts.principals);\n      const result = await engine.search(String(args.query ?? \"\"), {\n        sourceIds: args.source_ids,\n        principals: callerPrincipals,\n        topK: args.top_k ?? 10,\n        mode: args.mode ?? \"hybrid\",\n      });\n      return {\n        hits: (result.hits ?? []).map((hit) => {\n          const h = hit as Record<string, unknown>;\n          return {\n            document_name: h.document_name ?? h.documentName,\n            chunk_text: h.chunk_text ?? h.chunkText,\n            score: h.score,\n            source_id: h.source_id ?? h.sourceId,\n          };\n        }),\n        usage: result.usage,\n      };\n    },\n  );\n\n  tool(\n    \"get_document\",\n    `Fetch one document's full text and metadata by id.${SCOPE_NOTE}`,\n    { document_id: { type: \"string\" } },\n    async (args) => {\n      const callerPrincipals = await resolvePrincipalsFn(opts.principals);\n      return engine.getDocument(String(args.document_id), { principals: callerPrincipals });\n    },\n  );\n\n  if (engine.config.llm != null) {\n    tool(\n      \"query_structured\",\n      `Answer a question against documents' extracted structured data (only documents with structured data are candidates).${SCOPE_NOTE}`,\n      { question: { type: \"string\" }, source_ids: { type: \"array\", items: { type: \"string\" } } },\n      async (args) => {\n        const callerPrincipals = await resolvePrincipalsFn(opts.principals);\n        if (!engine.queryStructured) throw new Error(\"queryStructured is not available on this engine\");\n        return engine.queryStructured(String(args.question), {\n          sourceIds: args.source_ids,\n          principals: callerPrincipals,\n        });\n      },\n    );\n    if (engine.config.enableCodeExecution) {\n      tool(\n        \"compute\",\n        `Run LLM-authored JavaScript over in-scope spreadsheet documents and return the computed result.${SCOPE_NOTE}`,\n        { instruction: { type: \"string\" }, source_ids: { type: \"array\", items: { type: \"string\" } } },\n        async (args) => {\n          const callerPrincipals = await resolvePrincipalsFn(opts.principals);\n          if (!engine.compute) throw new Error(\"compute is not available on this engine\");\n          return engine.compute(String(args.instruction), {\n            sourceIds: args.source_ids,\n            principals: callerPrincipals,\n          });\n        },\n      );\n    }\n  }\n\n  registerToolGateway(\n    {\n      tool: (name, description, schema, handler) => {\n        tool(name, description, schema, async (args) => handler(args as never));\n      },\n    },\n    engine,\n    opts.principals,\n  );\n\n  const handler = (async (\n    req: import(\"node:http\").IncomingMessage,\n    res: import(\"node:http\").ServerResponse,\n  ) => {\n    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });\n    await mcp.connect(transport);\n    await transport.handleRequest(req, res);\n  }) as ((\n    req: import(\"node:http\").IncomingMessage,\n    res: import(\"node:http\").ServerResponse,\n  ) => Promise<void>) & { mcp: unknown };\n  handler.mcp = mcp;\n  return handler;\n}\n"]}

package/dist/migrations/sql/0001.sql

@@ -0,0 +1,119 @@
+-- 0001_initial — documents, chunks, meta, structured_keys
+-- dim is substituted by the migrator (default 1536)
+
+CREATE EXTENSION IF NOT EXISTS vector;
+CREATE EXTENSION IF NOT EXISTS pg_trgm;
+CREATE EXTENSION IF NOT EXISTS unaccent;
+
+CREATE OR REPLACE FUNCTION immutable_unaccent(text)
+RETURNS text
+LANGUAGE sql
+IMMUTABLE
+STRICT
+PARALLEL SAFE
+AS $fn$
+  SELECT unaccent($1)
+$fn$;
+
+CREATE TABLE context_engine_documents (
+  id UUID PRIMARY KEY,
+  source_id TEXT,
+  external_id TEXT,
+  name TEXT,
+  description TEXT,
+  meta_data JSONB NOT NULL DEFAULT '{}'::jsonb,
+  acl TEXT[],
+  mode TEXT NOT NULL DEFAULT 'hybrid',
+  mime_type TEXT,
+  lang TEXT,
+  text TEXT,
+  text_search TSVECTOR GENERATED ALWAYS AS (
+    to_tsvector('simple'::regconfig,
+      left(coalesce(name,'') || ' ' || coalesce(description,'') || ' ' || coalesce(text,''), 500000))
+  ) STORED,
+  modified_time TIMESTAMPTZ,
+  revision TEXT,
+  ingest_hash BYTEA,
+  status TEXT NOT NULL DEFAULT 'queued',
+  error TEXT,
+  started_at TIMESTAMPTZ,
+  completed_at TIMESTAMPTZ,
+  document_type TEXT,
+  structured_data JSONB,
+  structured_keys TEXT[],
+  structured_quality JSONB,
+  extraction_version TEXT,
+  media_bytes BYTEA,
+  media_size BIGINT,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX ix_context_engine_documents_source_id ON context_engine_documents (source_id);
+CREATE INDEX ix_context_engine_documents_status ON context_engine_documents (status);
+CREATE INDEX ix_context_engine_documents_meta_data_gin ON context_engine_documents USING gin (meta_data);
+CREATE INDEX ix_context_engine_documents_text_search ON context_engine_documents USING gin (text_search);
+
+CREATE UNIQUE INDEX ix_context_engine_documents_uniq_source_external
+  ON context_engine_documents (COALESCE(source_id, ''), external_id)
+  WHERE external_id IS NOT NULL;
+
+CREATE UNIQUE INDEX ix_context_engine_documents_uniq_source_name
+  ON context_engine_documents (COALESCE(source_id, ''), name)
+  WHERE external_id IS NULL;
+
+CREATE TABLE context_engine_chunks (
+  id UUID PRIMARY KEY,
+  document_id UUID NOT NULL REFERENCES context_engine_documents(id) ON DELETE CASCADE,
+  source_id TEXT,
+  acl TEXT[],
+  idx INTEGER,
+  text TEXT,
+  meta_data JSONB NOT NULL DEFAULT '{}'::jsonb,
+  text_trgm_norm TEXT GENERATED ALWAYS AS (coalesce(text, '')) STORED,
+  text_search TSVECTOR GENERATED ALWAYS AS (
+    to_tsvector('simple'::regconfig, left(coalesce(text,''), 500000))
+  ) STORED,
+  lang TEXT,
+  embedding vector(__DIM__),
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX ix_context_engine_chunks_document_id ON context_engine_chunks (document_id);
+CREATE INDEX ix_context_engine_chunks_source_id ON context_engine_chunks (source_id);
+CREATE INDEX ix_context_engine_chunks_text_search ON context_engine_chunks USING gin (text_search) WHERE text IS NOT NULL;
+CREATE INDEX ix_context_engine_chunks_text_trgm_norm ON context_engine_chunks USING gin (text_trgm_norm gin_trgm_ops) WHERE text IS NOT NULL;
+CREATE INDEX ix_context_engine_chunks_embedding_hnsw ON context_engine_chunks USING hnsw (embedding vector_cosine_ops) WHERE embedding IS NOT NULL;
+
+CREATE TABLE context_engine_meta (
+  id INTEGER PRIMARY KEY,
+  embedding_provider TEXT,
+  embedding_model TEXT,
+  embedding_dim INTEGER,
+  schema_version INTEGER NOT NULL DEFAULT 1,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  CONSTRAINT chk_context_engine_meta_singleton CHECK (id = 1)
+);
+
+CREATE TABLE context_engine_structured_keys (
+  id UUID PRIMARY KEY,
+  source_id TEXT,
+  doc_type TEXT NOT NULL,
+  key_norm TEXT NOT NULL,
+  synonyms TEXT[] NOT NULL DEFAULT '{}',
+  data_type TEXT NOT NULL,
+  example_values TEXT[],
+  frequency INTEGER NOT NULL DEFAULT 1,
+  embedding vector(__DIM__),
+  co_occurrence_fields JSONB NOT NULL DEFAULT '{}'::jsonb,
+  value_stats JSONB NOT NULL DEFAULT '{}'::jsonb,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  CONSTRAINT uq_context_engine_structured_keys_norm UNIQUE (source_id, doc_type, key_norm)
+);
+
+CREATE INDEX ix_context_engine_structured_keys_source_doctype ON context_engine_structured_keys (source_id, doc_type);
+CREATE INDEX ix_context_engine_structured_keys_synonyms_gin ON context_engine_structured_keys USING gin (synonyms);
+CREATE INDEX ix_context_engine_structured_keys_co_occurrence_gin ON context_engine_structured_keys USING gin (co_occurrence_fields);
+CREATE INDEX ix_context_engine_structured_keys_value_stats_gin ON context_engine_structured_keys USING gin (value_stats);
+CREATE INDEX ix_context_engine_structured_keys_embedding_hnsw ON context_engine_structured_keys USING hnsw (embedding vector_cosine_ops) WHERE embedding IS NOT NULL;

package/dist/migrations/sql/0002_graph.sql

@@ -0,0 +1,48 @@
+-- 0002_graph — entities, relationships, chunk_entities, communities
+
+CREATE TABLE context_engine_entities (
+  id UUID PRIMARY KEY,
+  name TEXT NOT NULL,
+  normalized_name TEXT NOT NULL,
+  type TEXT NOT NULL,
+  frequency INTEGER NOT NULL DEFAULT 1,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  CONSTRAINT uq_context_engine_entities_normalized_name UNIQUE (normalized_name)
+);
+CREATE INDEX ix_context_engine_entities_type ON context_engine_entities (type);
+
+CREATE TABLE context_engine_entity_relationships (
+  id UUID PRIMARY KEY,
+  source_entity_id UUID NOT NULL REFERENCES context_engine_entities(id) ON DELETE CASCADE,
+  target_entity_id UUID NOT NULL REFERENCES context_engine_entities(id) ON DELETE CASCADE,
+  category TEXT NOT NULL,
+  label TEXT NOT NULL,
+  evidence TEXT,
+  chunk_id UUID REFERENCES context_engine_chunks(id) ON DELETE CASCADE,
+  confidence DOUBLE PRECISION NOT NULL DEFAULT 1.0,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE INDEX ix_context_engine_entity_rel_source ON context_engine_entity_relationships (source_entity_id);
+CREATE INDEX ix_context_engine_entity_rel_target ON context_engine_entity_relationships (target_entity_id);
+CREATE INDEX ix_context_engine_entity_rel_category ON context_engine_entity_relationships (category);
+CREATE INDEX ix_context_engine_entity_rel_chunk ON context_engine_entity_relationships (chunk_id);
+
+CREATE TABLE context_engine_chunk_entities (
+  chunk_id UUID NOT NULL REFERENCES context_engine_chunks(id) ON DELETE CASCADE,
+  entity_id UUID NOT NULL REFERENCES context_engine_entities(id) ON DELETE CASCADE,
+  PRIMARY KEY (chunk_id, entity_id)
+);
+CREATE INDEX ix_context_engine_chunk_entities_entity ON context_engine_chunk_entities (entity_id);
+
+CREATE TABLE context_engine_communities (
+  id UUID PRIMARY KEY,
+  level INTEGER NOT NULL DEFAULT 0,
+  entity_ids JSONB NOT NULL DEFAULT '[]'::jsonb,
+  entity_count INTEGER NOT NULL DEFAULT 0,
+  relationship_count INTEGER NOT NULL DEFAULT 0,
+  summary TEXT,
+  embedding vector(__DIM__),
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE INDEX ix_context_engine_communities_level ON context_engine_communities (level);