MCPedia

콘텐츠 우선 지식 베이스 — Git에서 Markdown/MDX로 읽을 수 있고, 인간은 Web UI로, AI 에이전트는 Model Context Protocol(MCP)로 질의할 수 있습니다.

MCPedia는 콘텐츠를 content/ 아래의 일반 Markdown 파일로 유지합니다. Git으로 추적되는 단일 진실 공급원(source of truth)이며, PostgreSQL(메타데이터 + tsvector 전문 검색 컬럼)에 인덱싱되고 모든 인터페이스(Web, MCP)가 공유하는 단일 Core 레이어를 통해 제공됩니다 — 표면별로 비즈니스 로직이 중복되지 않습니다.

모노레포 구조

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에 정의되어 있습니다(가중치가 적용된 search_vector tsvector + GIN 인덱스가 있는 documents, 그리고 embedding real[]이 있는 document_chunks). pgvector 확장은 공유 imrnes Postgres에서 사용할 수 없으므로, 의미 검색(semantic search)은 벡터를 real[]로 저장하고 앱 내 코사인 유사도로 순위를 매깁니다.

마이그레이션은 packages/db/drizzle/에 있습니다. psql로 수동 적용되었습니다(drizzle-kit push는 PgBouncer 트랜잭션 풀링에서 신뢰할 수 없음). 새 DB에 다시 적용하려면:

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 셸 변수가 .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는 항상 디스크의 파일(단일 진실 공급원)에서 읽습니다. DB에는 메타데이터와 검색 벡터만 저장됩니다.

MCP 도구

MCP 리소스

({+slug}는 RFC 6570 예약 확장을 사용하므로 docs/websocket/contract 같은 slug가 템플릿과 일치합니다.)

스모크 테스트(인메모리 전송, 실제 JSON-RPC):

bun --cwd apps/mcp run smoke

API (Phase 2 + Phase 3)

tRPC v11 API가 Hono를 통해 :4020에서 노출됩니다(모든 프로시저는 MCP 도구를 미러링합니다). Phase 3은 비동기 작업 + 개정 프로시저와 git-sync 웹훅을 추가합니다:

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

tRPC 프로시저: search, semanticSearch, hybridSearch, getDocument, listDocuments, related (Phase 2); 그리고 revisions, getRevision, restoreRevision, jobStatus, queueStatus (Phase 3).

Git-sync 웹훅(BullMQ 작업을 큐에 넣고, 워커가 처리합니다):

• POST /hooks/reindex — 전체 코퍼스 재인덱싱(푸시 시 자동 재인덱싱하려면 Git 제공자의 푸시 웹훅을 여기로 지정).

• POST /hooks/index?slug=<slug> — 단일 문서 재인덱싱.

보안: 두 웹훅 모두 .env에 설정된 WEBHOOK_SECRET과 일치하는 x-webhook-secret 헤더가 필요합니다. WEBHOOK_SECRET이 설정되지 않으면 API가 시작을 거부하므로 훅이 열린 채로 남는 일이 없습니다.

bun run index는 이제 청킹 + 임베딩(Phase 2 인덱서)을 수행하고 본문이 변경될 때마다 개정 스냅샷을 생성합니다(Phase 3). EMBED_* / REDIS_* / QUEUE_PREFIX / WEBHOOK_SECRET 변수는 .env.example을 참조하세요.

감독 서비스로 실행 (Phase 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는 TLS를 위해 Caddy(또는 리버스 프록시) 뒤에 있어야 합니다. :4020은 내부에서만 노출하고 웹 앱은 공개적으로 노출하세요.

상태

Phase 1 — MVP (완료): 모노레포, Core, Web UI(홈/문서/검색), MCP 서버, Postgres FTS 키워드 검색, 콘텐츠 인덱싱.

Phase 2 — 의미 검색 + API (완료): 임베딩 제공자(9router를 통한 OpenRouter), 청크된 document_chunks, semanticSearch + hybridSearch(RRF), tRPC/Hono API(apps/api, :4020), MCP semantic_search/hybrid_search 도구, 웹 하이브리드 토글.

Phase 3 — 비동기 + 확장 (완료): Redis + BullMQ 백그라운드 인덱싱/임베딩 워커(packages/queue, apps/worker), git-sync 웹훅(POST /hooks/*), 문서 개정 시스템(document_revisions + 복원), MCP 리소스(mcpedia://docs/...). PHASES.md 참조.

pgvector는 공유 imrnes Postgres에 설치되어 있지 않으므로, 벡터 저장은 real[] 컬럼과 앱 내 코사인 유사도를 사용합니다(KB 규모에서 즉시 처리). pgvector는 Phase 4 확장 경로입니다. PHASES.md 참조.

Phase 3–4(Redis/BullMQ, 인증, 개정, 확장)에 대해서는 PHASES.md를 참조하세요.