Skip to main content
Glama
deenesjakoruzh
Unity-Billal-mesloub

MCP Documentation Server

by Unity-Billal-mesloub
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

MCP Registry npm version GitHub Stars Ask DeepWiki

MCP Documentation Server

로컬 우선 문서 관리 및 AI 코딩 에이전트를 위한 의미론적 검색. 외부 데이터베이스, 클라우드 API, 벤더 종속 없음.

CLI 전용인 다른 MCP 서버와 달리, 이 서버는 전체 웹 대시보드를 제공합니다 — 브라우저에서 지식 기반을 탐색, 검색, 업로드, 관리할 수 있습니다. 모든 MCP 도구는 REST API로도 노출되어 AI 에이전트에게 간결하고 스키마 없는 인터페이스를 제공합니다.

  • 🏠 완전 오프라인 실행 — Orama 벡터 DB와 로컬 AI 임베딩(Transformers.js)

  • 🌐 내장 웹 UI — MCP 서버와 함께 포트 3080에서 자동 시작

  • 🔍 하이브리드 검색 — 전체 텍스트 + 벡터 유사도, 부모-자식 청킹

  • 🤖 선택적 AI 검색 — 고급 문서 분석을 위한 Google Gemini (자체 키 사용)

  • 📁 드래그 앤 드롭 업로드 — .txt, .md, .pdf 지원

  • 📦 MCP Registry에 게시 — npx로 설치 가능, 클론 불필요

빠른 시작

{
  "mcpServers": {
    "documentation": {
      "command": "npx",
      "args": ["-y", "@Unity-Billal-mesloub/mcp-documentation-server"]
    }
  }
}

🤖 에이전트 스킬 (REST API) — AI 에이전트에게 권장

모든 MCP 도구는 ``의 REST API를 통해서도 접근할 수 있습니다. 이는 AI 에이전트(Claude Code, OpenCode, Gemini CLI, Cursor)와 상호작용하는 권장 방법입니다. MCP 도구 스키마를 대화 컨텍스트에 로드하지 않아도 되고, 응답 JSON만 들어오기 때문입니다.


  -H "Content-Type: application/json" \
  -d '{"query": "your search", "limit": 5}'

사용 준비가 된 스킬이 skills/documentation-server/SKILL.md에 포함되어 있습니다 — 에이전트에게 모든 엔드포인트를 예제와 함께 가르칩니다. 설치 방법:

npx skills add https://github.com/Unity-Billal-mesloub/mcp-documentation-server --skill documentation-server

기본 워크플로우

  1. add_document을 사용하여 문서를 추가하거나 업로드 폴더에 .txt / .md / .pdf 파일을 넣고 process_uploads를 호출하세요.

  2. search_all_documents로 전체를 검색하거나 search_documents로 단일 문서 내에서 검색하세요.

  3. get_context_window를 사용하여 인접한 청크를 가져와 LLM에 더 넓은 컨텍스트를 제공하세요.

Related MCP server: RAG MCP Server

웹 UI

웹 인터페이스는 MCP 서버가 시작될 때 포트 3080에서 자동으로 시작됩니다. 웹 UI에서 다음을 할 수 있습니다:

  • 📊 대시보드 — 모든 문서 및 통계 개요

  • 📄 문서 — 문서 탐색, 보기, 삭제

  • ➕ 문서 추가 — 제목, 내용, 메타데이터로 문서 생성

  • 🔍 전체 검색 — 모든 문서에 대한 의미론적 검색

  • 🎯 문서 내 검색 — 특정 문서 내에서 검색

  • 🤖 AI 검색 — Gemini 기반 분석 (GEMINI_API_KEY 설정 시)

  • 📁 파일 업로드 — 파일을 드래그 앤 드롭하여 지식 기반으로 처리

  • 🪟 컨텍스트 창 — 특정 인덱스 주변의 청크 탐색

MCP 클라이언트 구성

최소 설정

{
  "mcpServers": {
    "documentation": {
      "command": "npx",
      "args": ["-y", "@Unity-Billal-mesloub/mcp-documentation-server"]
    }
  }
}

환경 변수 사용 (모두 선택 사항)

{
  "mcpServers": {
    "documentation": {
      "command": "npx",
      "args": ["-y", "@Unity-Billal-mesloub/mcp-documentation-server"],
      "env": {
        "MCP_BASE_DIR": "/path/to/workspace",
        "GEMINI_API_KEY": "your-api-key-here",
        "MCP_EMBEDDING_MODEL": "Xenova/all-MiniLM-L6-v2",
        "START_WEB_UI": "true",
        "WEB_HOST": "127.0.0.1",
        "WEB_PORT": "3080"
      }
    }
  }
}

모든 환경 변수는 선택 사항입니다. GEMINI_API_KEY가 없으면 로컬 임베딩 기반 검색 도구만 사용할 수 있습니다.

MCP 도구

서버는 다음 도구를 등록합니다 (모두 Zod 스키마로 검증됨):

📄 문서 관리

Tool

설명

add_document

문서 추가 (제목, 내용, 선택적 메타데이터)

list_documents

모든 문서를 메타데이터 및 내용 미리보기와 함께 나열

get_document

ID로 문서의 전체 내용 검색

delete_document

문서, 해당 청크, 데이터베이스 항목 및 관련 파일 제거

📁 파일 처리

Tool

설명

process_uploads

업로드 폴더의 모든 파일 처리 (청킹 + 임베딩)

get_uploads_path

업로드 폴더의 절대 경로 반환

list_uploads_files

업로드 폴더의 파일을 크기 및 형식 정보와 함께 나열

get_ui_url

웹 UI URL 반환 (예: http://localhost:3080) — 대시보드를 열거나 브라우저에서 업로드 폴더를 찾는 데 유용

🔍 검색

Tool

설명

search_documents

특정 문서 내 의미론적 벡터 검색

search_all_documents

하이브리드 (전체 텍스트 + 벡터) 문서 간 검색

get_context_window

주어진 청크 인덱스 주변의 청크 창 반환

search_documents_with_ai

🤖 Gemini를 사용한 AI 기반 검색 (GEMINI_API_KEY 필요)

구성

환경 변수 또는 프로젝트 루트의 .env 파일을 통해 구성합니다:

Variable

Default

설명

MCP_BASE_DIR

~/.mcp-documentation-server

데이터 저장을 위한 기본 디렉터리

MCP_EMBEDDING_MODEL

Xenova/all-MiniLM-L6-v2

임베딩 모델 이름

GEMINI_API_KEY

—

Google Gemini API 키 (search_documents_with_ai 활성화)

MCP_CACHE_ENABLED

true

LRU 임베딩 캐시 활성화/비활성화

START_WEB_UI

true

false로 설정하면 내장 웹 인터페이스 비활성화

WEB_HOST

127.0.0.1

웹 UI 바인드 주소 (0.0.0.0 사용 시 모든 인터페이스에 노출)

WEB_PORT

3080

웹 UI 포트

MCP_STREAMING_ENABLED

true

대용량 파일의 스트리밍 읽기 활성화

MCP_STREAM_CHUNK_SIZE

65536

스트리밍 버퍼 크기 (바이트, 64KB)

MCP_STREAM_FILE_SIZE_LIMIT

10485760

스트리밍으로 전환하는 임계값 (10MB)

저장소 구조

~/.mcp-documentation-server/     # Or custom path via MCP_BASE_DIR
├── data/
│   ├── orama-chunks.msp         # Orama vector DB (child chunks + embeddings)
│   ├── orama-docs.msp           # Orama document DB (full content + metadata)
│   ├── orama-parents.msp        # Orama parent chunks DB (context sections)
│   ├── migration-complete.flag   # Written after legacy JSON migration
│   └── *.md                     # Markdown copies of documents
└── uploads/                     # Drop .txt, .md, .pdf files here

임베딩 모델

MCP_EMBEDDING_MODEL로 설정:

Model

Dimensions

설명

Xenova/all-MiniLM-L6-v2

384

기본 — 빠르고 품질 좋음

Xenova/paraphrase-multilingual-mpnet-base-v2

768

권장 — 최고 품질, 다국어 지원

모델은 처음 사용할 때 다운로드됩니다 (~80–420 MB). 벡터 차원은 공급자로부터 자동으로 결정됩니다.

⚠️ 중요: 임베딩 모델을 변경하면 모든 문서를 다시 추가해야 합니다 — 서로 다른 모델의 임베딩은 호환되지 않습니다. 차원이 변경되면 Orama 데이터베이스가 자동으로 재생성됩니다.

아키텍처

Server (FastMCP, stdio)
  ├─ Web UI (Express, port 3080)
  │    └─ REST API → DocumentManager
  └─ MCP Tools
       └─ DocumentManager
            ├─ OramaStore          — Orama vector DB (chunks DB + docs DB + parents DB), persistence, migration
            ├─ IntelligentChunker  — Parent-child chunking (code, markdown, text, PDF)
            ├─ EmbeddingProvider   — Local embeddings via @xenova/transformers
            │    └─ EmbeddingCache — LRU in-memory cache
            └─ GeminiSearchService — Optional AI search via Google Gemini

  • OramaStore는 세 개의 Orama 인스턴스를 관리합니다: 문서 메타데이터/내용용, 벡터 임베딩이 있는 하위 청크용, 상위 청크(컨텍스트 섹션)용. 모두 디스크의 이진 파일로 저장되고 시작 시 복원됩니다.

  • IntelligentChunker는 부모-자식 청킹 패턴을 구현합니다: 문서는 먼저 전체 컨텍스트(섹션, 단락)를 보존하는 큰 상위 청크로 분할된 다음, 각 상위 청크는 정밀한 벡터 검색을 위해 작은 하위 청크로 다시 분할됩니다. 쿼리 시 결과는 상위 청크별로 중복 제거되어 LLM이 일치하는 조각과 더 넓은 컨텍스트를 모두 받습니다.

  • EmbeddingProvider는 로컬 추론을 위해 Transformers.js 모델을 지연 로드합니다 — API 호출이 필요 없습니다.

개발

git clone https://github.com/Unity-Billal-mesloub/mcp-documentation-server.git
cd mcp-documentation-server
npm install
npm run dev       # FastMCP dev mode with hot reload
npm run build     # TypeScript compilation
npm run inspect   # FastMCP web UI for interactive tool testing
npm start         # Direct tsx execution (MCP server + web UI)
npm run web       # Run only the web UI (development)
npm run web:build # Run only the web UI (compiled)

기여

  1. 저장소를 포크하세요

  2. 기능 브랜치를 생성하세요: git checkout -b feature/name

  3. 커밋 메시지에 Conventional Commits 규칙을 따르세요

  4. 풀 리퀘스트를 여세요

지원

스타 기록

Star History Chart

FastMCP, Orama, TypeScript로 제작

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • OpenLMlib

    Vedant9500
    A
    license
    B
    quality
    B
    maintenance
    Provides AI assistants with a local knowledge base and research library, enabling semantic and full-text retrieval, memory persistence, and multi-agent collaboration via 58 MCP tools.
    76
    2
    MIT

  • RAG MCP Server

    alejandro-ao
    F
    license
    Not graded
    quality
    D
    maintenance
    Provides tools for ingesting documents into a local vector database and retrieving relevant information via semantic search, enabling retrieval-augmented generation for MCP clients.
    6
    -

  • rag-retriever-mcp

    code-lawyer
    F
    license
    A
    quality
    D
    maintenance
    A local-first document retrieval engine that mounts as an MCP tool for agents to index files, search for relevant passages, and let the agent's own LLM answer.
    4
    -
  • fayna-rag-mcp by fayna-digital

    fayna-rag-mcpofficial

    fayna-digital
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables local knowledge base management with retrieval-augmented generation (RAG), providing semantic search, document reading, listing, and Q&A via MCP tools and REST endpoints, all running locally without cloud dependencies.
    MIT