Files

T

asepharyana ec3a2867d4 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

2026-08-19 17:40:14 +07:00

3.7 KiB

Raw Blame History

MCPedia

A content-first knowledge base — readable as Markdown/MDX in Git, queryable by humans via a Web UI and by AI agents via the Model Context Protocol (MCP).

MCPedia keeps content as plain Markdown files under content/. A Git-tracked source of truth, indexed into PostgreSQL (metadata + a tsvector full-text column) and served through a single Core layer that every interface (Web, MCP) shares — no business logic duplicated per surface.

Monorepo layout

mcpedia/
├── apps/
│   ├── web/      # Next.js 16 (Turbopack) — human-facing docs UI + search
│   └── mcp/      # MCP server (stdio) — AI-agent interface
├── packages/
│   ├── types/    # shared domain types (DocSection, Document, SearchHit, ...)
│   ├── config/   # loads .env (repo root) as authoritative dev config
│   ├── db/       # Drizzle ORM schema + client + drizzle-kit config
│   ├── parser/   # frontmatter (gray-matter) parsing
│   ├── search/   # Postgres FTS query (ts_rank + ts_headline)
│   └── core/     # Document/Content/Search services — the only business logic
├── content/      # docs/ writeups/ research/ notes/ (the knowledge base)
└── scripts/      # indexer.ts (walks content/ -> upserts into Postgres)

Architecture principle

Web ─┐
     ├──► Core ──► Repository (@mcpedia/db) ──► PostgreSQL
MCP ─┘

All interfaces go through @mcpedia/core. Nothing outside packages/db and packages/core touches the database directly.

Quick start

bun install                       # install workspace deps
cp .env.example .env             # set DATABASE_URL (dev uses imrnes Postgres :6432)
bunx turbo run build             # typecheck + build every package

bun run index                    # walk content/ -> upsert into Postgres
bun --cwd apps/web run dev       # Web UI on :3000
bun run mcp                       # MCP server on stdio (pipe to an MCP client)

Database

Phase 1 uses Postgres FTS only. Schema is defined in packages/db/src/schema.ts (a documents table with a search_vector generated tsvector column + GIN index). Apply it with:

bunx --cwd packages/db drizzle-kit push

Note: on imrnes (PgBouncer :6432) a leaked DATABASE_URL shell var can shadow .env. @mcpedia/config loads .env last so the repo config always wins for local/dev.

Content

Each Markdown file carries YAML frontmatter:

---
id: websocket-contract
title: WebSocket Contract
type: documentation
tags: [typescript, websocket, rpc]
status: published
author: asep
created_at: 2026-08-19
updated_at: 2026-08-19
---

slug = relative path under content/ (e.g. docs/websocket/contract). The body shown in the UI is always read from the on-disk file (source of truth); the DB stores metadata + the search vector.

MCP tools (Phase 1)

Tool	Purpose
`search_documents`	Postgres FTS over the corpus (ranked + snippet)
`get_document`	Full markdown body by slug
`list_documents`	List, optionally filtered by section
`get_related_documents`	Docs sharing tags with a given slug

Smoke test (in-memory transport, real JSON-RPC):

bun --cwd apps/mcp run smoke

Status

Phase 1 — MVP (DONE): monorepo, Core, Web UI (home/doc/search), MCP server, Postgres FTS keyword search, content indexing.

See PHASES.md for Phase 2–4 (pgvector semantic/hybrid search, tRPC/Hono API, auth, Redis/BullMQ background workers, revisions, scale-out).

3.7 KiB Raw Blame History Unescape Escape