feat(mcpedia): Phase 1 MVP — monorepo, Core, Web UI, MCP server, Postgres FTS

- bun workspaces + Turborepo monorepo (apps/web, apps/mcp; packages/*, scripts)
- @mcpedia/core single business-logic layer (Document/Content/Search services)
- @mcpedia/db Drizzle schema: documents + weighted tsvector (GIN) for FTS
- @mcpedia/parser frontmatter, @mcpedia/search Postgres FTS (ts_rank+ts_headline)
- Next.js 16 Web UI (home/doc SSG, search dynamic) + react-markdown render
- MCP server (stdio) with 4 tools + in-memory smoke test
- scripts/indexer walks content/ -> upserts into Postgres
- 4 seed docs; README + PHASES status

apps/mcp/src/index.ts

@@ -0,0 +1,96 @@
+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";
+
+export function createMcpServer(): McpServer {
+  const server = new McpServer({
+    name: "mcpedia",
+    version: "0.1.0",
+  });
+
+  server.registerTool(
+    "search_documents",
+    {
+      description:
+        "Full-text search across the MCPedia knowledge base (Postgres FTS). Returns ranked documents with a headline snippet.",
+      inputSchema: z.object({
+        query: z.string().describe("Free-text search query"),
+        limit: z.number().int().positive().max(50).optional(),
+      }),
+    },
+    async ({ query, limit }) => {
+      const hits = await keywordSearch(query, limit ?? 20);
+      return {
+        content: [{ type: "text", text: JSON.stringify(hits, null, 2) }],
+      };
+    },
+  );
+
+  server.registerTool(
+    "get_document",
+    {
+      description:
+        "Fetch the full markdown body of a document by its slug (e.g. 'docs/websocket/contract').",
+      inputSchema: z.object({
+        slug: z.string().describe("Document slug, e.g. 'docs/websocket/contract'"),
+      }),
+    },
+    async ({ slug }) => {
+      const doc = await getDocument(slug);
+      if (!doc) {
+        return {
+          content: [{ type: "text", text: `Document not found: ${slug}` }],
+          isError: true,
+        };
+      }
+      return { content: [{ type: "text", text: doc.body }] };
+    },
+  );
+
+  server.registerTool(
+    "list_documents",
+    {
+      description: "List documents, optionally filtered by section.",
+      inputSchema: z.object({
+        section: z
+          .enum(["docs", "writeups", "research", "notes"])
+          .optional(),
+      }),
+    },
+    async ({ section }) => {
+      const docs = await listDocuments({ section });
+      return {
+        content: [{ type: "text", text: JSON.stringify(docs, null, 2) }],
+      };
+    },
+  );
+
+  server.registerTool(
+    "get_related_documents",
+    {
+      description: "Return documents that share tags with the given slug.",
+      inputSchema: z.object({
+        slug: z.string(),
+        limit: z.number().int().positive().max(20).optional(),
+      }),
+    },
+    async ({ slug, limit }) => {
+      const related = await getRelated(slug, limit ?? 5);
+      return {
+        content: [{ type: "text", text: JSON.stringify(related, null, 2) }],
+      };
+    },
+  );
+
+  return server;
+}
+
+// When run directly (bun run src/index.ts), serve over stdio.
+const isMain =
+  process.argv[1] && import.meta.url === `file://${process.argv[1]}`;
+if (isMain) {
+  const transport = new StdioServerTransport();
+  await createMcpServer().connect(transport);
+}

apps/mcp/src/smoke.test.ts

@@ -0,0 +1,79 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { createMcpServer } from "../src/index";
+
+async function main() {
+  const server = createMcpServer();
+  const [clientT, serverT] = InMemoryTransport.createLinkedPair();
+  await server.connect(serverT);
+
+  const client = new Client({ name: "smoke", version: "0.0.1" });
+  await client.connect(clientT);
+
+  // 1) tool discovery
+  const tools = await client.listTools();
+  const names = tools.tools.map((t) => t.name).sort();
+  console.log("tools:", names.join(", "));
+  const expected = [
+    "get_document",
+    "get_related_documents",
+    "list_documents",
+    "search_documents",
+  ].sort();
+  if (JSON.stringify(names) !== JSON.stringify(expected)) {
+    throw new Error(`tool set mismatch: ${names.join(",")}`);
+  }
+
+  // 2) search_documents
+  const search = await client.callTool({
+    name: "search_documents",
+    arguments: { query: "websocket", limit: 10 },
+  });
+  const hits = JSON.parse((search.content as any)[0].text);
+  if (!Array.isArray(hits) || hits.length < 1) {
+    throw new Error("search_documents returned no hits");
+  }
+  console.log(`search_documents("websocket") => ${hits.length} hits`);
+  console.log("  top:", hits[0].doc.slug, hits[0].doc.title);
+
+  // 3) get_document
+  const get = await client.callTool({
+    name: "get_document",
+    arguments: { slug: "docs/websocket/contract" },
+  });
+  const body = (get.content as any)[0].text;
+  if (!body.includes("WebSocket Contract")) {
+    throw new Error("get_document returned unexpected body");
+  }
+  console.log("get_document('docs/websocket/contract') => body ok (len", body.length, ")");
+
+  // 4) get_document not found
+  const missing = await client.callTool({
+    name: "get_document",
+    arguments: { slug: "nope/missing" },
+  });
+  if (!(missing as any).isError) {
+    throw new Error("get_document should report isError for missing doc");
+  }
+  console.log("get_document('nope/missing') => isError ok");
+
+  // 5) list_documents
+  const list = await client.callTool({
+    name: "list_documents",
+    arguments: { section: "docs" },
+  });
+  const docs = JSON.parse((list.content as any)[0].text);
+  if (docs.length !== 1) throw new Error("list_documents docs != 1");
+  console.log("list_documents(section=docs) =>", docs.length, "doc");
+
+  await client.close();
+  await server.close();
+  console.log("\nSMOKE OK");
+}
+
+main()
+  .then(() => process.exit(0))
+  .catch((e) => {
+    console.error("SMOKE FAIL:", e);
+    process.exit(1);
+  });