convez.ai
MCP ServerDados & AnalyticsAvançado
michaelkrauty

mcp-docs — Gerenciador de Documentos

michaelkrauty/mcp-docs

Extração, indexação e busca semântica de documentos multi-formato

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server para gestão de documentos com extração multi-formato, busca semântica via Qdrant e deduplicação por hash. Suporta PDF, DOCX, PPTX, XLSX, EPUB e diversos outros formatos, com OCR automático para PDFs digitalizados e rastreamento de integridade de fontes.

Instalação

$npx convez-ai michaelkrauty/mcp-docs

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 2 semanas
Versão
v1.6.6
Issues abertas
3
Contribuidores
1

Casos de uso

  • Indexar e pesquisar em grandes repositórios de documentos heterogêneos
  • Implementar busca semântica e keyword search combinadas em bases documentais
  • Rastrear origem de citações e verificar integridade de fontes em análises

Veredito

Solução robusta para quem precisa gerenciar documentos complexos com busca semântica em produção. Requer infraestrutura externa (Qdrant, embedding API) e é limitado a POSIX (sem Windows), mas oferece recursos avançados como deduplicação, OCR e rastreamento de fontes.

README

A tradução para o português deste README ainda está na fila.

mcp-docs

MCP server for document management with multi-format extraction, semantic search, and source integrity tracking.

Prerequisites

  • Python 3.12+
  • Linux or macOS (uses POSIX file locking via vector-core; not compatible with Windows)
  • Qdrant vector database (default: localhost:6333)
  • An OpenAI-compatible embedding API (e.g., llama.cpp, Ollama, or any /v1/embeddings endpoint; default: localhost:8080)
  • Vision endpoint (optional) — OpenAI-compatible vision model for automatic OCR fallback on scanned PDFs
  • poppler (optional, for OCR) — apt install poppler-utils (Linux) or brew install poppler (macOS)

Installation

Requires vector-core.

pip install git+https://github.com/michaelkrauty/vector-core.git@v1.2.7
pip install git+https://github.com/michaelkrauty/mcp-docs.git

Or clone both repos and install locally:

git clone https://github.com/michaelkrauty/vector-core.git
git clone https://github.com/michaelkrauty/mcp-docs.git
pip install -e vector-core/
pip install -e mcp-docs/

Quick Start

# Register with Claude Code (set env vars to match your setup):
claude mcp add docs \
  -e VECTOR_QDRANT_URL=http://localhost:6333 \
  -e VECTOR_EMBEDDING_URL=http://localhost:8080 \
  -e VECTOR_EMBEDDING_MODEL=your-model-name \
  -e VECTOR_COLLECTION_NAME=my-documents \
  -- mcp-docs

# Or add to your MCP client config (e.g., claude_desktop_config.json):
# {
#   "mcpServers": {
#     "docs": {
#       "command": "mcp-docs",
#       "env": {
#         "VECTOR_QDRANT_URL": "http://localhost:6333",
#         "VECTOR_EMBEDDING_URL": "http://localhost:8080",
#         "VECTOR_EMBEDDING_MODEL": "your-model-name",
#         "VECTOR_COLLECTION_NAME": "my-documents"
#       }
#     }
#   }
# }

Features

  • Multi-Format Extraction: PDF, DOCX, PPTX, XLSX, CSV, EPUB, XML, TXT, Markdown, Jupyter (.ipynb), HTML, RTF
  • Directory Scanning: Register root directories for automatic discovery
  • Semantic Search: Hybrid dense + sparse vector search via Qdrant
  • Keyword Search: Exact keyword/phrase matching in filenames and content
  • Hash Deduplication: SHA-256 content hashes prevent duplicate ingestion
  • Source Tracking: Verify document references for fact integrity
  • Background Processing: Async extraction/indexing with worker queue
  • Filesystem Operations: Move files/directories with automatic registry updates
  • Glossary: Shared term definitions (same store as mcp-notes)

Tools (36 total)

Documents (6)

ToolDescription
register_documentRegister file for indexing with deduplication
get_documentRetrieve document by UUID
get_document_by_hashLookup by SHA-256 content hash
update_document_tagsModify document tags
delete_documentRemove from registry
list_documentsList with tag/status/type/root filters

Processing (4)

ToolDescription
get_processing_statusCheck extraction/indexing progress
list_queued_documentsView processing queue
wait_for_documentBlock until processing completes
cancel_processingStop processing for a document

Search (4)

ToolDescription
search_documentsHybrid semantic search with filters
keyword_searchExact keyword/phrase matching in filenames and content
find_similar_documentsContent-based similarity matching
get_document_chunksRetrieve indexed chunks

Indexing (2)

ToolDescription
index_documentIndex single document
index_all_documentsBatch index with two-pass vocabulary

Root Management (6)

ToolDescription
add_document_rootRegister directory for scanning
list_document_rootsView all roots
get_document_rootInfo on specific root
remove_document_rootUnregister a root
scan_document_rootScan specific root for changes
scan_all_rootsScan all enabled roots

Hash Verification (3)

ToolDescription
lookup_hashFind document by SHA-256
verify_document_referenceCheck document exists and unchanged
batch_verify_referencesVerify multiple hashes

Glossary (6)

ToolDescription
add_glossary_entryAdd term with expansion, definition, domain
lookup_termExact lookup by term or alias
search_glossarySemantic glossary search
list_glossaryList entries with optional domain filter
update_glossary_entryModify entry metadata
delete_glossary_entryDelete entry

Filesystem (5)

ToolDescription
move_fileMove a file and update document registry
create_directoryCreate a directory within a document root
rename_directoryRename a directory and update all document paths
move_directoryMove a directory and update all document paths
delete_directoryDelete an empty directory

Supported Formats

FormatExtensionsNotes
PDF.pdfText extraction via MarkItDown; automatic OCR fallback via vision LLM for scanned/image-based PDFs
Word.docxFull text via MarkItDown + metadata via python-docx
Word (legacy).docRTF-disguised files only; true DOC requires conversion
PowerPoint.pptxSlide text via MarkItDown + metadata via python-pptx
PowerPoint (legacy).pptBest-effort via MarkItDown; may require conversion
Excel.xlsx, .xlsSpreadsheet to markdown table via MarkItDown
CSV.csvMarkdown table representation
EPUB.epubE-book text extraction via MarkItDown
XML.xmlXML content extraction via MarkItDown
Text.txt, .mdDirect text / markdown with title extraction
Jupyter.ipynbMarkdown cells as prose, code cells as language-tagged fenced blocks; outputs and raw cells skipped; title from first H1
HTML.html, .htmMarkdown conversion via MarkItDown
RTF.rtfRich text via striprtf
OpenDocument.odtNot supported; raises error advising conversion to DOCX

Document Status

StatusMeaning
ActivePath exists, hash matches
ModifiedPath exists, different hash
RelocatedFound at different path (same hash)
DeletedFile not found anywhere

Extraction Pipeline

Queued → Processing → Extracted → Indexed
                  ↘ Failed (with error message)

Data Model

Document

id: UUID
path: "/path/to/document.pdf"
content_hash: "sha256:..."
doc_type: "pdf"
status: "active"
extraction_status: "indexed"
tags: ["research", "2024"]
created_at: datetime
indexed_at: datetime

DocumentRoot

path: "/home/user/documents"
name: "My Documents"
recursive: True
enabled: True
added_at: datetime
last_scanned: datetime
file_count: 42

Storage

DataLocation
Document registrydocuments.db in data dir
Extracted contentQdrant collection (set via VECTOR_COLLECTION_NAME)
Glossaryglossary.db in vector-core's shared data dir

Configuration

VariableDefaultDescription
VECTOR_COLLECTION_NAME(required)Qdrant collection name
DOCS_OCR_VISION_URL""OpenAI-compatible vision endpoint for OCR (empty = OCR disabled)
DOCS_OCR_VISION_MODEL""Vision model name (empty = let endpoint decide)
DOCS_OCR_DPI300DPI for PDF page rendering
DOCS_OCR_TIMEOUT180Per-page OCR timeout in seconds
DOCS_OCR_MAX_PAGES200Maximum pages to OCR per document
DOCS_OCR_IMAGE_MAX_DIMENSION1536Max image width/height sent to vision model
DOCS_OCR_IMAGE_FORMATjpegImage format: jpeg (smaller) or png (lossless)
DOCS_OCR_JPEG_QUALITY90JPEG quality (1-100) if using jpeg format
DOCS_OCR_CACHE_ENABLEDtrueCache OCR results by file metadata
DOCS_OCR_CONCURRENCY4Max concurrent OCR page requests
DOCS_MAX_CHUNK_CHARS80000Chunk size (~20k tokens)
DOCS_CHUNK_OVERLAP_CHARS500Overlap between chunks
DOCS_MAX_WORKERS2Background processing workers
DOCS_MAX_TAGS_PER_DOCUMENT20Tag limit
DOCS_MAX_TAG_LENGTH50Maximum length of a single tag

Plus inherited vector-core settings (VECTOR_QDRANT_URL, VECTOR_EMBEDDING_URL, etc.).

Integration with mcp-notes

  • Shared glossary: Same glossary.db, same terms
  • Shared facts.db: Documents can be sources for facts
  • Hash verification: mcp-docs verifies document sources haven't changed

When a fact references a document:

  1. Source stores source_type: "document", source_hash: "sha256:..."
  2. verify_document_reference checks if hash still exists
  3. If file modified/deleted, fact marked as having stale source

Dependencies

Requires vector-core components:

  • EmbeddingClient, GlobalVocabulary (search)
  • QdrantStorage, HybridSearcher (storage)
  • GlossaryStore (glossary)
  • SourceIntegrityManager (fact verification)

External libraries:

  • pypdf (PDF extraction)
  • python-docx (DOCX metadata)
  • python-pptx (PPTX metadata)
  • markitdown (unified text conversion for DOCX, PPTX, XLSX, CSV, EPUB, XML, HTML, TXT)
  • striprtf (RTF extraction)
Ver o original no GitHub

Bom para

Relacionados