MCP Documentation Server

Um servidor para gerenciamento de documentos e busca semântica usando embeddings de IA, com armazenamento local em JSON.

GitHub

342

Experimente este MCPPatrocinado

Documentação

MCP Documentation Server

Gerenciamento de documentos local-first e busca semântica para agentes de codificação de IA. Sem bancos de dados externos, sem APIs em nuvem, sem dependência de fornecedores.

Diferente de outros servidores MCP que são apenas CLI, este vem com um painel web completo — navegue, pesquise, envie e gerencie sua base de conhecimento pelo navegador. Cada ferramenta MCP também é exposta como uma API REST, dando aos agentes de IA uma interface enxuta e sem esquema.

🏠 Funciona totalmente offline — banco vetorial Orama com embeddings de IA locais (Transformers.js)
🌐 Interface Web integrada — inicia automaticamente na porta 3080 junto com o servidor MCP
🔍 Busca híbrida — texto completo + similaridade vetorial com chunking pai-filho
🤖 Busca com IA opcional — Google Gemini para análise avançada de documentos (use sua própria chave)
📁 Uploads por arrastar e soltar — suporte a .txt, .md, .pdf
📦 Publicado no MCP Registry — instalável via npx, sem necessidade de clonar

Início Rápido

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

Abra seu navegador em http://localhost:3080 — a interface web inicia automaticamente.

🤖 Habilidade do Agente (REST API) — recomendado para agentes de IA

Cada ferramenta MCP também é acessível via API REST em http://127.0.0.1:3080/api/. Esta é a forma recomendada de interagir com agentes de IA (Claude Code, OpenCode, Gemini CLI, Cursor) porque evita carregar os esquemas das ferramentas MCP no contexto da conversa — apenas o JSON de resposta entra.

curl -s http://127.0.0.1:3080/api/config
curl -s http://127.0.0.1:3080/api/documents
curl -s -X POST http://127.0.0.1:3080/api/search-all \
  -H "Content-Type: application/json" \
  -d '{"query": "your search", "limit": 5}'

Uma habilidade pronta para uso está incluída em skills/documentation-server/SKILL.md — ela ensina ao seu agente cada endpoint com exemplos. Instale-a:

npx skills add https://github.com/andrea9293/mcp-documentation-server --skill documentation-server

Fluxo de trabalho básico

Adicione documentos usando add_document ou coloque arquivos .txt / .md / .pdf na pasta de uploads e chame process_uploads.
Pesquise em tudo com search_all_documents, ou dentro de um único documento com search_documents.
Use get_context_window para buscar chunks vizinhos e dar ao LLM um contexto mais amplo.

Interface Web

A interface web inicia automaticamente na porta 3080 quando o servidor MCP é iniciado. Pela interface web você pode:

📊 Painel — visão geral de todos os documentos e estatísticas
📄 Documentos — navegue, visualize e exclua documentos
➕ Adicionar Documento — crie documentos com título, conteúdo e metadados
🔍 Pesquisar Tudo — busca semântica em todos os documentos
🎯 Pesquisar no Documento — busca dentro de um documento específico
🤖 Busca com IA — análise com Gemini (se GEMINI_API_KEY estiver definido)
📁 Enviar Arquivos — arraste e solte arquivos e processe-os na base de conhecimento
🪟 Janela de Contexto — explore chunks ao redor de um índice específico

Configurar um cliente MCP

Mínimo

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

Com variáveis de ambiente (todas opcionais)

{
  "mcpServers": {
    "documentation": {
      "command": "npx",
      "args": ["-y", "@andrea9293/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"
      }
    }
  }
}

Todas as variáveis de ambiente são opcionais. Sem GEMINI_API_KEY, apenas as ferramentas de busca baseadas em embeddings locais estão disponíveis.

Ferramentas MCP

O servidor registra as seguintes ferramentas (todas validadas com esquemas Zod):

📄 Gerenciamento de Documentos

Ferramenta	Descrição
`add_document`	Adicionar um documento (título, conteúdo, metadados opcionais)
`list_documents`	Listar todos os documentos com metadados e pré-visualização do conteúdo
`get_document`	Recuperar o conteúdo completo de um documento por ID
`delete_document`	Remover um documento, seus chunks, entradas do banco de dados e arquivos associados

📁 Processamento de Arquivos

Ferramenta	Descrição
`process_uploads`	Processar todos os arquivos na pasta de uploads (chunking + embeddings)
`get_uploads_path`	Retorna o caminho absoluto da pasta de uploads
`list_uploads_files`	Lista arquivos na pasta de uploads com informações de tamanho e formato
`get_ui_url`	Retorna a URL da interface web (ex.: http://localhost:3080) — útil para abrir o painel ou localizar a pasta de uploads pelo navegador

🔍 Busca

Ferramenta	Descrição
`search_documents`	Busca vetorial semântica dentro de um documento específico
`search_all_documents`	Busca híbrida (texto completo + vetorial) entre documentos
`get_context_window`	Retorna uma janela de chunks ao redor de um índice de chunk específico
`search_documents_with_ai`	🤖 Busca com IA usando Gemini (requer `GEMINI_API_KEY`)

Configuração

Configure via variáveis de ambiente ou um arquivo .env na raiz do projeto:

Variável	Padrão	Descrição
`MCP_BASE_DIR`	`~/.mcp-documentation-server`	Diretório base para armazenamento de dados
`MCP_EMBEDDING_MODEL`	`Xenova/all-MiniLM-L6-v2`	Nome do modelo de embeddings
`GEMINI_API_KEY`	—	Chave da API Google Gemini (habilita `search_documents_with_ai`)
`MCP_CACHE_ENABLED`	`true`	Ativar/desativar cache LRU de embeddings
`START_WEB_UI`	`true`	Defina como `false` para desativar a interface web integrada
`WEB_HOST`	`127.0.0.1`	Endereço de vinculação da interface web (use `0.0.0.0` para expor em todas as interfaces)
`WEB_PORT`	`3080`	Porta da interface web
`MCP_STREAMING_ENABLED`	`true`	Ativar leituras em streaming para arquivos grandes
`MCP_STREAM_CHUNK_SIZE`	`65536`	Tamanho do buffer de streaming em bytes (64KB)
`MCP_STREAM_FILE_SIZE_LIMIT`	`10485760`	Limite para alternar para streaming (10MB)

Estrutura de armazenamento

~/.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

Modelos de Embeddings

Defina via MCP_EMBEDDING_MODEL:

Modelo	Dimensões	Observações
`Xenova/all-MiniLM-L6-v2`	384	Padrão — rápido, boa qualidade
`Xenova/paraphrase-multilingual-mpnet-base-v2`	768	Recomendado — melhor qualidade, multilíngue

Os modelos são baixados no primeiro uso (~80–420 MB). A dimensão do vetor é determinada automaticamente pelo provedor.

⚠️ Importante: Alterar o modelo de embeddings requer re-adicionar todos os documentos — embeddings de modelos diferentes são incompatíveis. O banco de dados Orama é recriado automaticamente quando a dimensão muda.

Arquitetura

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 gerencia três instâncias Orama: uma para metadados/conteúdo de documentos, uma para chunks filhos com embeddings vetoriais e uma para chunks pais (seções de contexto). Todas são persistidas em arquivos binários no disco e restauradas na inicialização.
IntelligentChunker implementa o padrão de Chunking Pai-Filho: os documentos são primeiro divididos em chunks pais grandes que preservam o contexto completo (seções, parágrafos), depois cada pai é dividido em chunks filhos pequenos para busca vetorial precisa. No momento da consulta, os resultados são deduplicados por pai para que o LLM receba tanto o fragmento correspondente quanto o contexto mais amplo.
EmbeddingProvider carrega lentamente um modelo Transformers.js para inferência local — sem necessidade de chamadas de API.

Desenvolvimento

git clone https://github.com/andrea9293/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)

Contribuindo

Faça um fork do repositório
Crie um branch de funcionalidade: git checkout -b feature/name
Siga Conventional Commits para mensagens
Abra um pull request

Licença

MIT — veja LICENSE

Suporte

📖 Documentação
🐛 Reportar Problemas
💬 Comunidade MCP
🤖 Google AI Studio — obtenha uma chave da API Gemini

Histórico de Estrelas

Construído com FastMCP, Orama e TypeScript