MCPedia

Eine inhaltsorientierte Wissensdatenbank – lesbar als Markdown/MDX in Git, abfragbar von Menschen über eine Web-UI und von KI-Agenten über das Model Context Protocol (MCP).

MCPedia hält Inhalte als einfache Markdown-Dateien unter content/. Eine in Git nachverfolgte Quelle der Wahrheit, indexiert in PostgreSQL (Metadaten + eine tsvector-Volltextspalte) und bereitgestellt über eine einzige Core-Schicht, die alle Schnittstellen (Web, MCP) gemeinsam nutzen – keine Geschäftslogik wird pro Oberfläche dupliziert.

Monorepo-Layout

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

Architekturprinzip

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

Alle Schnittstellen laufen über @mcpedia/core. Nichts außerhalb von packages/db und packages/core greift direkt auf die Datenbank zu.

Schnellstart

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)

Datenbank

Das Schema ist in packages/db/src/schema.ts definiert (documents mit einem gewichteten search_vector-tsvector + GIN-Index und document_chunks mit einem embedding real[]). Die pgvector-Erweiterung ist nicht verfügbar auf dem gemeinsamen imrnes-Postgres, daher speichert die semantische Suche Vektoren als real[] und sortiert nach Kosinus-Ähnlichkeit in der Anwendung.

Migrationen liegen in packages/db/drizzle/. Sie wurden manuell über psql angewendet (drizzle-kit push ist unter PgBouncer-Transaktions-Pooling unzuverlässig); um sie auf einer frischen DB erneut anzuwenden:

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

Hinweis: auf imrnes (PgBouncer :6432) kann eine ausgelaufene DATABASE_URL-Shell-Variable .env überschatten. @mcpedia/config lädt .env zuletzt, sodass die Repo-Konfiguration für lokal/Dev immer gewinnt.

Inhalt

Jede Markdown-Datei trägt 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 = relativer Pfad unter content/ (z. B. docs/websocket/contract). Der in der UI angezeigte body wird immer aus der Datei auf der Festplatte gelesen (Quelle der Wahrheit); die DB speichert Metadaten + den Suchvektor.

MCP-Tools

MCP-Ressourcen

({+slug} verwendet die reservierte Erweiterung von RFC 6570, sodass ein Slug wie docs/websocket/contract zur Vorlage passt.)

Smoke-Test (In-Memory-Transport, echtes JSON-RPC):

bun --cwd apps/mcp run smoke

API (Phase 2 + Phase 3)

Eine tRPC-v11-API wird über Hono auf :4020 bereitgestellt (alle Prozeduren spiegeln die MCP-Tools). Phase 3 fügt asynchrone Job- und Revisions-Prozeduren sowie Git-Sync-Webhooks hinzu:

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

tRPC-Prozeduren: search, semanticSearch, hybridSearch, getDocument, listDocuments, related (Phase 2); plus revisions, getRevision, restoreRevision, jobStatus, queueStatus (Phase 3).

Git-Sync-Webhooks (stellen BullMQ-Jobs in die Warteschlange; der Worker verarbeitet sie):

• POST /hooks/reindex — Vollkorpus-Reindex (weisen Sie den Push-Webhook Ihres Git-Anbieters hierher, um bei Push automatisch neu zu indexieren).

• POST /hooks/index?slug=<slug> — ein einzelnes Dokument neu indexieren.

Sicherheit: beide Webhooks erfordern einen x-webhook-secret-Header, der mit WEBHOOK_SECRET übereinstimmt (in .env gesetzt). Die API weigert sich zu starten, wenn WEBHOOK_SECRET nicht gesetzt ist, sodass die Hooks nie offen bleiben.

bun run index chunkt und embeddet jetzt auch (Phase-2-Indexer) und erstellt einen Revisions-Snapshot, wann immer sich der Body ändert (Phase 3). Siehe .env.example für die Variablen EMBED_* / REDIS_* / QUEUE_PREFIX / WEBHOOK_SECRET.

Als überwachter Dienst ausführen (Phase 4)

deploy/mcpedia-api.service + deploy/mcpedia-worker.service sind systemd-Units (Restart=on-failure, EnvironmentFile=.env, WorkingDirectory=/home/code/mcpedia). Aktivieren Sie sie mit:

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

Die API sollte für TLS hinter Caddy (oder Ihrem Reverse-Proxy) sitzen; exponieren Sie nur :4020 intern und die Web-App öffentlich.

Status

Phase 1 — MVP (FERTIG): Monorepo, Core, Web-UI (Start/Dokument/Suche), MCP-Server, Postgres-FTS-Stichwortsuche, Inhaltsindexierung.

Phase 2 — Semantisch + API (FERTIG): Embeddings-Anbieter (OpenRouter über 9router), gechunkte document_chunks, semanticSearch + hybridSearch (RRF), tRPC/Hono-API (apps/api, :4020), MCP-Tools semantic_search/hybrid_search, Web-Hybrid-Umschalter.

Phase 3 — Async + Skalierung (FERTIG): Redis + BullMQ-Hintergrund-Indexierungs-/Embedding-Worker (packages/queue, apps/worker), Git-Sync-Webhooks (POST /hooks/*), Dokument-Revisionssystem (document_revisions + Wiederherstellung) und MCP-Ressourcen (mcpedia://docs/...). Siehe PHASES.md.

pgvector ist nicht installiert auf dem gemeinsamen imrnes-Postgres, daher ist die Vektorspeicherung eine real[]-Spalte mit Kosinus-Ähnlichkeit in der Anwendung (sofort bei KB-Skalierung). pgvector ist der Skalierungspfad für Phase 4. Siehe PHASES.md.

Siehe PHASES.md für Phase 3–4 (Redis/BullMQ, Auth, Revisionen, Skalierung).