feat(mcpedia): Phase 2 — semantic + hybrid search, tRPC/Hono API

- @mcpedia/embeddings: OpenRouter provider (9router /v1, encoding_format float),
  chunkText + embedChunks; EMBED_DIM=2048
- document_chunks table (real[] embedding) — pgvector NOT available on shared
  imrnes Postgres, so cosine is computed in-app (KB-scale fine); pgvector deferred
- indexer: chunk + embed + upsert per document
- @mcpedia/search: semanticSearch (cosine) + hybridSearch (FTS+cosine RRF)
- apps/api: Hono + tRPC v11 (6 procedures), serve on :4020
- MCP: semantic_search + hybrid_search tools (6 total)
- web: keyword/hybrid toggle; .env.example + README + PHASES updated

apps/api/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@mcpedia/api",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "bun run src/index.ts",
+    "start": "bun run src/index.ts",
+    "lint": "tsc --noEmit",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@hono/node-server": "^1.13.0",
+    "@mcpedia/config": "workspace:*",
+    "@mcpedia/core": "workspace:*",
+    "@trpc/server": "^11.0.0",
+    "hono": "^4.6.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0"
+  }
+}

apps/api/src/index.ts

@@ -0,0 +1,26 @@
+import { serve } from "@hono/node-server";
+import { Hono } from "hono";
+import { fetchRequestHandler } from "@trpc/server/adapters/fetch";
+import { db } from "@mcpedia/db";
+import { appRouter } from "./router";
+import type { Context } from "./trpc";
+
+const app = new Hono();
+
+// Health check.
+app.get("/health", (c) => c.json({ ok: true }));
+
+// Mount tRPC at /trpc/*. The fetch adapter is the canonical Bun/Hono adapter.
+app.all("/trpc/*", (c) =>
+  fetchRequestHandler({
+    endpoint: "/trpc",
+    req: c.req.raw,
+    router: appRouter,
+    createContext: (): Context => ({ db }),
+  }),
+);
+
+const port = Number(process.env.API_PORT ?? 4020);
+serve({ fetch: app.fetch, port }, (info) => {
+  console.log(`MCPedia API listening on http://localhost:${info.port}`);
+});

apps/api/src/router.ts

@@ -0,0 +1,38 @@
+import { z } from "zod";
+import { publicProcedure, router } from "./trpc";
+import {
+  getDocument,
+  getRelated,
+  hybridSearch,
+  keywordSearch,
+  listDocuments,
+  semanticSearch,
+} from "@mcpedia/core";
+
+export const appRouter = router({
+  search: publicProcedure
+    .input(z.object({ q: z.string(), limit: z.number().int().min(1).max(50).default(20) }))
+    .query(({ input }) => keywordSearch(input.q, input.limit)),
+
+  semanticSearch: publicProcedure
+    .input(z.object({ q: z.string(), limit: z.number().int().min(1).max(50).default(10) }))
+    .query(async ({ input }) => semanticSearch(input.q, input.limit)),
+
+  hybridSearch: publicProcedure
+    .input(z.object({ q: z.string(), limit: z.number().int().min(1).max(50).default(10) }))
+    .query(async ({ input }) => hybridSearch(input.q, input.limit)),
+
+  getDocument: publicProcedure
+    .input(z.object({ slug: z.string() }))
+    .query(async ({ input }) => getDocument(input.slug)),
+
+  listDocuments: publicProcedure
+    .input(z.object({ section: z.string().optional(), status: z.string().optional() }).optional())
+    .query(async ({ input }) => listDocuments(input ?? {})),
+
+  related: publicProcedure
+    .input(z.object({ slug: z.string(), limit: z.number().int().min(1).max(20).default(5) }))
+    .query(async ({ input }) => getRelated(input.slug, input.limit)),
+});
+
+export type AppRouter = typeof appRouter;

apps/api/src/trpc.ts

@@ -0,0 +1,11 @@
+import { initTRPC } from "@trpc/server";
+import { db } from "@mcpedia/db";
+
+export interface Context {
+  db: typeof db;
+}
+
+export const t = initTRPC.context<Context>().create();
+
+export const router = t.router;
+export const publicProcedure = t.procedure;

apps/api/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "paths": {
+      "@mcpedia/db": ["../../packages/db/src/index.ts"],
+      "@mcpedia/db/schema": ["../../packages/db/src/schema.ts"],
+      "@mcpedia/*": ["../../packages/*"]
+    }
+  },
+  "include": ["src/**/*.ts"]
+}

apps/mcp/src/index.ts

@@ -1,8 +1,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { listDocuments, getDocument, getRelated } from "@mcpedia/core";
-import { keywordSearch } from "@mcpedia/search";
+import { listDocuments, getDocument, getRelated, semanticSearch, hybridSearch, keywordSearch } from "@mcpedia/core";
 
 export function createMcpServer(): McpServer {
   const server = new McpServer({
@@ -84,6 +83,42 @@ export function createMcpServer(): McpServer {
     },
   );
 
+  server.registerTool(
+    "semantic_search",
+    {
+      description:
+        "Semantic (embedding) search across chunked document content. Best for conceptual/paraphrased queries that don't share exact keywords. Returns chunks ranked by cosine similarity.",
+      inputSchema: z.object({
+        query: z.string().describe("Natural-language query"),
+        limit: z.number().int().positive().max(50).optional(),
+      }),
+    },
+    async ({ query, limit }) => {
+      const hits = await semanticSearch(query, limit ?? 10);
+      return {
+        content: [{ type: "text", text: JSON.stringify(hits, null, 2) }],
+      };
+    },
+  );
+
+  server.registerTool(
+    "hybrid_search",
+    {
+      description:
+        "Hybrid search fusing full-text (Postgres FTS) and semantic (embedding) signals via Reciprocal Rank Fusion. Best general-purpose search.",
+      inputSchema: z.object({
+        query: z.string().describe("Free-text or natural-language query"),
+        limit: z.number().int().positive().max(50).optional(),
+      }),
+    },
+    async ({ query, limit }) => {
+      const hits = await hybridSearch(query, limit ?? 10);
+      return {
+        content: [{ type: "text", text: JSON.stringify(hits, null, 2) }],
+      };
+    },
+  );
+
   return server;
 }
 

apps/mcp/src/smoke.test.ts

@@ -17,8 +17,10 @@ async function main() {
   const expected = [
     "get_document",
     "get_related_documents",
+    "hybrid_search",
     "list_documents",
     "search_documents",
+    "semantic_search",
   ].sort();
   if (JSON.stringify(names) !== JSON.stringify(expected)) {
     throw new Error(`tool set mismatch: ${names.join(",")}`);
@@ -66,6 +68,30 @@ async function main() {
   if (docs.length !== 1) throw new Error("list_documents docs != 1");
   console.log("list_documents(section=docs) =>", docs.length, "doc");
 
+  // 6) semantic_search
+  const sem = await client.callTool({
+    name: "semantic_search",
+    arguments: { query: "websocket connection closing unexpectedly", limit: 5 },
+  });
+  const semHits = JSON.parse((sem.content as any)[0].text);
+  if (!Array.isArray(semHits) || semHits.length < 1) {
+    throw new Error("semantic_search returned no hits");
+  }
+  console.log(
+    `semantic_search => ${semHits.length} chunks, top: ${semHits[0].slug}@${semHits[0].score.toFixed(3)}`,
+  );
+
+  // 7) hybrid_search
+  const hyb = await client.callTool({
+    name: "hybrid_search",
+    arguments: { query: "websocket timeout debugging", limit: 5 },
+  });
+  const hybHits = JSON.parse((hyb.content as any)[0].text);
+  if (!Array.isArray(hybHits) || hybHits.length < 1) {
+    throw new Error("hybrid_search returned no hits");
+  }
+  console.log(`hybrid_search => ${hybHits.length} docs, top: ${hybHits[0].doc.slug}`);
+
   await client.close();
   await server.close();
   console.log("\nSMOKE OK");

apps/mcp/tsconfig.json

@@ -2,6 +2,8 @@
   "extends": "../../tsconfig.base.json",
   "compilerOptions": {
     "paths": {
+      "@mcpedia/db": ["../../packages/db/src/index.ts"],
+      "@mcpedia/db/schema": ["../../packages/db/src/schema.ts"],
       "@mcpedia/*": ["../../packages/*"]
     }
   },

apps/web/app/search/page.tsx

@@ -1,18 +1,45 @@
 import Link from "next/link";
-import { keywordSearch } from "@mcpedia/core";
+import { keywordSearch, hybridSearch } from "@mcpedia/core";
+
+type Mode = "keyword" | "hybrid";
 
 export default async function SearchPage({
   searchParams,
 }: {
-  searchParams: Promise<{ q?: string }>;
+  searchParams: Promise<{ q?: string; mode?: string }>;
 }) {
-  const { q } = await searchParams;
+  const { q, mode } = await searchParams;
   const query = q?.trim() ?? "";
-  const hits = query ? await keywordSearch(query, 30) : [];
+  const activeMode: Mode = mode === "hybrid" ? "hybrid" : "keyword";
+
+  const hits = query
+    ? activeMode === "hybrid"
+      ? await hybridSearch(query, 30)
+      : await keywordSearch(query, 30)
+    : [];
+
+  const toggle = (m: Mode) => `/search?q=${encodeURIComponent(query)}&mode=${m}`;
 
   return (
     <div className="space-y-4">
-      <h1 className="text-2xl font-semibold tracking-tight">Search</h1>
+      <div className="flex items-center justify-between">
+        <h1 className="text-2xl font-semibold tracking-tight">Search</h1>
+        <div className="flex rounded overflow-hidden border border-zinc-300 dark:border-zinc-700 text-sm">
+          <Link
+            href={toggle("keyword")}
+            className={`px-3 py-1.5 ${activeMode === "keyword" ? "bg-zinc-900 text-white dark:bg-zinc-100 dark:text-zinc-900" : "hover:bg-zinc-100 dark:hover:bg-zinc-800"}`}
+          >
+            Keyword
+          </Link>
+          <Link
+            href={toggle("hybrid")}
+            className={`px-3 py-1.5 ${activeMode === "hybrid" ? "bg-zinc-900 text-white dark:bg-zinc-100 dark:text-zinc-900" : "hover:bg-zinc-100 dark:hover:bg-zinc-800"}`}
+          >
+            Hybrid
+          </Link>
+        </div>
+      </div>
+
       <form method="get" className="flex gap-2">
         <input
           name="q"
@@ -20,6 +47,7 @@ export default async function SearchPage({
           placeholder="e.g. websocket contract typescript"
           className="flex-1 rounded border border-zinc-300 dark:border-zinc-700 bg-white dark:bg-zinc-900 px-3 py-2 text-sm"
         />
+        <input type="hidden" name="mode" value={activeMode} />
         <button
           type="submit"
           className="rounded bg-zinc-900 text-white dark:bg-zinc-100 dark:text-zinc-900 px-4 py-2 text-sm font-medium"
@@ -44,6 +72,9 @@ export default async function SearchPage({
             >
               {h.doc.title}
             </Link>
+            {/* Snippet comes from Postgres ts_headline (keyword mode) or our own
+                chunk content (hybrid mode) — both trusted, first-party data, not
+                user input. The only markup is <mark> from ts_headline. */}
             <p
               className="text-sm text-zinc-600 dark:text-zinc-400 mt-1"
               dangerouslySetInnerHTML={{ __html: h.snippet }}