MCPedia

Una base de conocimiento centrada en el contenido: legible como Markdown/MDX en Git, consultable por humanos a través de una interfaz web y por agentes de IA mediante el Protocolo de Contexto de Modelo (MCP).

MCPedia mantiene el contenido como archivos Markdown simples en content/. Una fuente de verdad controlada por Git, indexada en PostgreSQL (metadatos + una columna tsvector de texto completo) y servida a través de una única capa Core que comparten todas las interfaces (Web, MCP): sin lógica de negocio duplicada por superficie.

Estructura del monorepo

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

Principio de arquitectura

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

Todas las interfaces pasan por @mcpedia/core. Nada fuera de packages/db y packages/core toca la base de datos directamente.

Inicio rápido

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)

Base de datos

El esquema se define en packages/db/src/schema.ts (documents con un search_vector tsvector ponderado + índice GIN, y document_chunks con un embedding real[]). La extensión pgvector no está disponible en el Postgres compartido de imrnes, por lo que la búsqueda semántica almacena los vectores como real[] y clasifica mediante similitud coseno en la aplicación.

Las migraciones viven en packages/db/drizzle/. Se aplicaron manualmente con psql (drizzle-kit push no es fiable con el agrupamiento de transacciones de PgBouncer); para volver a aplicarlas en una base de datos nueva:

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

Nota: en imrnes (PgBouncer :6432) una variable de shell DATABASE_URL filtrada puede ocultar .env. @mcpedia/config carga .env al final, por lo que la configuración del repositorio siempre gana en local/desarrollo.

Contenido

Cada archivo Markdown lleva frontmatter YAML:

---
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 = ruta relativa bajo content/ (p. ej. docs/websocket/contract). El body que se muestra en la interfaz siempre se lee del archivo en disco (fuente de verdad); la base de datos almacena los metadatos y el vector de búsqueda.

Herramientas MCP

Recursos MCP

({+slug} usa la expansión reservada de RFC 6570 para que un slug como docs/websocket/contract coincida con la plantilla).

Prueba de humo (transporte en memoria, JSON-RPC real):

bun --cwd apps/mcp run smoke

API (Fase 2 + Fase 3)

Se expone una API tRPC v11 mediante Hono en :4020 (todos los procedimientos reflejan las herramientas MCP). La Fase 3 añade procedimientos de trabajos asíncronos y de revisión, y webhooks de sincronización Git:

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

Procedimientos tRPC: search, semanticSearch, hybridSearch, getDocument, listDocuments, related (Fase 2); además de revisions, getRevision, restoreRevision, jobStatus, queueStatus (Fase 3).

Webhooks de sincronización Git (ponen en cola trabajos de BullMQ; el trabajador los procesa):

• POST /hooks/reindex — reindexa todo el corpus (apunta el webhook de push de tu proveedor Git aquí para reindexar automáticamente al hacer push).

• POST /hooks/index?slug=<slug> — reindexa un único documento.

Seguridad: ambos webhooks requieren una cabecera x-webhook-secret que coincida con WEBHOOK_SECRET (definida en .env). La API se niega a arrancar si WEBHOOK_SECRET no está definida, por lo que los hooks nunca quedan abiertos.

bun run index ahora también fragmenta e incrusta (indexador de la Fase 2) y crea una instantánea de revisión cada vez que cambia el cuerpo (Fase 3). Consulta .env.example para las variables EMBED_* / REDIS_* / QUEUE_PREFIX / WEBHOOK_SECRET.

Ejecutar como servicio supervisado (Fase 4)

deploy/mcpedia-api.service + deploy/mcpedia-worker.service son unidades systemd (Restart=on-failure, EnvironmentFile=.env, WorkingDirectory=/home/code/mcpedia). Actívalas con:

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

La API debería estar detrás de Caddy (o tu proxy inverso) para TLS; expón solo :4020 internamente y la aplicación web públicamente.

Estado

Fase 1 — MVP (COMPLETADA): monorepo, Core, interfaz web (inicio/documento/búsqueda), servidor MCP, búsqueda por palabras clave con Postgres FTS, indexación de contenido.

Fase 2 — Semántica + API (COMPLETADA): proveedor de incrustaciones (OpenRouter vía 9router), document_chunks fragmentados, semanticSearch + hybridSearch (RRF), API tRPC/Hono (apps/api, :4020), herramientas MCP semantic_search/hybrid_search, conmutador híbrido web.

Fase 3 — Asíncrono + Escalado (COMPLETADA): trabajadores de indexación/incrustación en segundo plano con Redis + BullMQ (packages/queue, apps/worker), webhooks de sincronización Git (POST /hooks/*), sistema de revisión de documentos (document_revisions + restauración) y Recursos MCP (mcpedia://docs/...). Ver PHASES.md.

pgvector no está instalado en el Postgres compartido de imrnes, por lo que el almacenamiento de vectores es una columna real[] con similitud coseno en la aplicación (instantáneo a escala de KB). pgvector es la vía de escalado de la Fase 4. Ver PHASES.md.

Consulta PHASES.md para las fases 3–4 (Redis/BullMQ, autenticación, revisiones, escalado).