MCPedia

一个以内容为先的知识库 —— 在 Git 中以 Markdown/MDX 形式可读，人类通过 Web UI 查询，AI 代理通过模型上下文协议（MCP）查询。

MCPedia 将内容保持为 content/ 下的纯 Markdown 文件。以 Git 跟踪的事实来源，索引到 PostgreSQL（元数据 + tsvector 全文列）中，并通过单个 Core 层提供服务，所有接口（Web、MCP）共用该层 —— 每个界面不重复业务逻辑。

单仓库布局

mcpedia/
├── apps/
│   ├── web/      # Next.js 16 (Turbopack) — human-facing docs UI + search
│   ├── mcp/      # MCP server (stdio) — AI-agent interface (tools + resources)
│   └── api/      # Hono + tRPC v11 API on :4020 (+ /hooks/* git-sync webhooks)
├── 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)
│   ├── embeddings/ # embedding provider + chunker
│   ├── queue/    # Redis (ioredis) + BullMQ worker/queue (Phase 3)
│   └── core/     # Document/Content/Search/Index/Revision — the only business logic
├── content/      # docs/ writeups/ research/ notes/ (the knowledge base)
└── scripts/      # indexer.ts (full reindex), enqueue.ts (one-shot job enqueue)

Related MCP server: astra-knowledge-base-mcp

架构原则

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

所有接口都通过 @mcpedia/core。除 packages/db 和 packages/core 外，没有其他模块直接访问数据库。

快速开始

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)

数据库

模式在 packages/db/src/schema.ts 中定义（documents 带加权 search_vector tsvector + GIN 索引，document_chunks 带 embedding real[]）。共享的 imrnes Postgres 上没有 pgvector 扩展，因此语义搜索将向量存储为 real[]，并通过应用内余弦相似度排序。

迁移文件位于 packages/db/drizzle/ 中。它们是通过 psql 手动应用的（drizzle-kit push 在 PgBouncer 事务池下不可靠）；要在新数据库上重新应用：

psql $DATABASE_URL -f packages/db/drizzle/0000_grey_toro.sql
psql $DATABASE_URL -f packages/db/drizzle/0001_document_chunks.sql

注意：在 imrnes（PgBouncer :6432）上，泄漏的 DATABASE_URL shell 变量可能遮蔽 .env。@mcpedia/config 最后加载 .env，因此仓库配置在本地/开发环境中始终优先。

内容

每个 Markdown 文件都带有 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 = content/ 下的相对路径（例如 docs/websocket/contract）。UI 中显示的 body 始终从磁盘上的文件读取（事实来源）；数据库存储元数据 + 搜索向量。

MCP 工具

MCP 资源

（{+slug} 使用 RFC 6570 保留扩展，因此类似 docs/websocket/contract 的 slug 可以匹配模板。）

冒烟测试（内存传输，真实 JSON-RPC）：

bun --cwd apps/mcp run smoke

API（阶段 2 + 阶段 3）

通过 :4020 端口提供 tRPC v11 API（所有过程镜像 MCP 工具）。阶段 3 增加了异步任务和修订过程以及 git-sync webhooks：

bun run api            # http://localhost:4020 (GET /health, POST/GET /trpc/*)

tRPC 过程：search、semanticSearch、hybridSearch、getDocument、listDocuments、related（阶段 2）；加上 revisions、getRevision、restoreRevision、jobStatus、queueStatus（阶段 3）。

git-sync webhooks（将任务入队到 BullMQ；由 worker 处理）：

• POST /hooks/reindex —— 全语料库重新索引（将你的 Git 提供商的 push webhook 指向这里，以便在推送时自动重新索引）。

• POST /hooks/index?slug=<slug> —— 重新索引单个文档。

安全性： 两个 webhook 都需要 x-webhook-secret 头，与 WEBHOOK_SECRET（在 .env 中）匹配。如果 WEBHOOK_SECRET 未设置，API 将拒绝启动，因此钩子永远不会处于未受保护状态。

bun run index 现在还会进行分块 + 嵌入（Phase 2 索引器），并在正文更改时快照修订（Phase 3）。参见 .env.example 了解 EMBED_* / REDIS_* / QUEUE_PREFIX / WEBHOOK_SECRET 变量。

作为受监控服务运行（阶段 4）

deploy/mcpedia-api.service + deploy/mcpedia-worker.service 是 systemd 单元（Restart=on-failure，EnvironmentFile=.env，WorkingDirectory=/home/code/mcpedia）。使用以下命令启用：

sudo cp deploy/*.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now mcpedia-api mcpedia-worker
# tail logs
journalctl -u mcpedia-api -u mcpedia-worker -f

API 应位于 Caddy（或反向代理）之后以提供 TLS；仅将 :4020 暴露在内部，Web 应用公开。

状态

阶段 1 — MVP（已完成）： monorepo、核心层、Web UI（首页/文档/搜索）、MCP 服务器、Postgres FTS 关键字搜索、内容索引。

阶段 2 — 语义 + API（已完成）： 嵌入提供者（通过 9router 的 OpenRouter）、分块的 document_chunks、semanticSearch + hybridSearch（RRF）、tRPC/Hono API（apps/api，:4020）、MCP semantic_search/hybrid_search 工具、Web 混合搜索开关。

阶段 3 — 异步 + 扩展（已完成）： Redis + BullMQ 后台索引/嵌入工作进程（packages/queue、apps/worker）、git 同步 webhook（POST /hooks/*）、文档修订系统（document_revisions + 还原），以及 MCP 资源（mcpedia://docs/...）。请参阅 PHASES.md。

共享的 imrnes Postgres 上未安装 pgvector，因此向量存储使用 real[] 列，并在应用内计算余弦相似度（在 KB 规模下瞬间完成）。pgvector 是第 4 阶段的扩展路径。请参阅 PHASES.md。

请参阅 PHASES.md 了解阶段 3–4（Redis/BullMQ、认证、修订、扩展）。