Doc Lib MCP

Um servidor MCP para ingestão de documentos, fragmentação, busca semântica e gerenciamento de notas.

GitHubExperimente este MCPPatrocinado

Documentação

Servidor MCP doc-lib-mcp

Um servidor Model Context Protocol (MCP) para ingestão de documentos, fragmentação (chunking), busca semântica e gerenciamento de notas.

Componentes

Recursos

  • Implementa um sistema simples de armazenamento de notas com:
    • Esquema de URI personalizado note:// para acessar notas individuais
    • Cada recurso de nota possui um nome, descrição e tipo MIME text/plain

Prompts

  • Fornece um prompt:
    • summarize-notes: Cria resumos de todas as notas armazenadas
      • Argumento opcional "style" para controlar o nível de detalhe (breve/detalhado)
      • Gera um prompt combinando todas as notas atuais com a preferência de estilo

Ferramentas

O servidor implementa uma ampla gama de ferramentas:

  • add-note: Adiciona uma nova nota ao armazenamento de notas em memória
    • Argumentos: name (string), content (string)
  • ingest-string: Ingere e fragmenta uma string Markdown ou texto simples fornecida via mensagem
    • Argumentos: content (string, obrigatório), source (string, opcional), tags (lista de strings, opcional)
  • ingest-markdown: Ingere e fragmenta um arquivo Markdown (.md)
    • Argumentos: path (string)
  • ingest-python: Ingere e fragmenta um arquivo Python (.py)
    • Argumentos: path (string)
  • ingest-openapi: Ingere e fragmenta um arquivo JSON OpenAPI
    • Argumentos: path (string)
  • ingest-html: Ingere e fragmenta um arquivo HTML
    • Argumentos: path (string)
  • ingest-html-url: Ingere e fragmenta conteúdo HTML de uma URL (opcionalmente usando Playwright para conteúdo dinâmico)
    • Argumentos: url (string), dynamic (booleano, opcional)
  • smart_ingestion: Extrai todo o conteúdo tecnicamente relevante de um arquivo usando Gemini e, em seguida, fragmenta usando lógica robusta de Markdown.
    • Argumentos:
      • path (string, obrigatório): Caminho do arquivo a ser ingerido.
      • prompt (string, opcional): Prompt personalizado a ser usado para o Gemini.
      • tags (lista de strings, opcional): Lista opcional de tags para classificação.
    • Usa Gemini 2.0 Flash 001 para extrair apenas código, configuração, estrutura Markdown e definições técnicas (sem resumos ou comentários).
    • Passa o conteúdo extraído para um fragmentador baseado em mistune 3.x que preserva blocos de código e conteúdo Markdown/narrativo como fragmentos separados.
    • Cada fragmento é incorporado e armazenado para busca semântica e recuperação.
  • search-chunks: Busca semântica sobre o conteúdo ingerido
    • Argumentos:
      • query (string): A consulta de busca semântica.
      • top_k (inteiro, opcional, padrão 3): Número de resultados principais a retornar.
      • type (string, opcional): Filtrar resultados por tipo de fragmento (ex.: code, html, markdown).
      • tag (string, opcional): Filtrar resultados por tag nos metadados do fragmento.
    • Retorna os fragmentos mais relevantes para uma determinada consulta, opcionalmente filtrados por tipo e/ou tag.
  • delete-source: Exclui todos os fragmentos de uma determinada fonte
    • Argumentos: source (string)
  • delete-chunk-by-id: Exclui um ou mais fragmentos por id
    • Argumentos: id (inteiro, opcional), ids (lista de inteiros, opcional)
    • Você pode excluir um único fragmento especificando id, ou excluir vários fragmentos de uma vez especificando ids.
  • update-chunk-type: Atualiza o atributo tipo de um fragmento por id
    • Argumentos: id (inteiro, obrigatório), type (string, obrigatório)
  • ingest-batch: Ingere e fragmenta vários arquivos de documentação (Markdown, OpenAPI JSON, Python) em lote
    • Argumentos: paths (lista de strings)
  • list-sources: Lista todas as fontes exclusivas (caminhos de arquivo) que foram ingeridas e armazenadas em memória, com filtragem opcional por tag ou busca semântica.
    • Argumentos:
      • tag (string, opcional): Filtrar fontes por tag nos metadados do fragmento.
      • query (string, opcional): Consulta de busca semântica para encontrar fontes relevantes.
      • top_k (inteiro, opcional, padrão 10): Número de fontes principais a retornar ao usar consulta.
  • get-context: Recupera fragmentos de conteúdo relevantes (apenas conteúdo) para uso como contexto de IA, com filtragem por tag, tipo e similaridade semântica.
    • Argumentos:
      • query (string, opcional): A consulta de busca semântica.
      • tag (string, opcional): Filtrar resultados por uma tag específica nos metadados do fragmento.
      • type (string, opcional): Filtrar resultados por tipo de fragmento (ex.: 'code', 'markdown').
      • top_k (inteiro, opcional, padrão 5): O número de fragmentos relevantes principais a recuperar.
  • update-chunk-metadata: Atualiza o campo de metadados de um fragmento por id
    • Argumentos: id (inteiro), metadata (objeto)
  • tag-chunks-by-source: Adiciona tags especificadas aos metadados de todos os fragmentos associados a uma determinada fonte (URL ou caminho de arquivo). Mescla com tags existentes.
    • Argumentos: source (string), tags (lista de strings)
  • list-notes: Lista todas as notas atualmente armazenadas e seu conteúdo.

Fragmentação e Extração de Código

  • Arquivos Markdown, Python, OpenAPI e HTML são divididos em fragmentos lógicos para recuperação e busca eficientes.
  • O fragmentador Markdown usa a API AST do mistune 3.x e regex para dividir robustamente o conteúdo por blocos de código e narrativa, preservando toda a formatação original.
  • Tanto blocos de código quanto conteúdo Markdown/narrativo são preservados como fragmentos separados.
  • O fragmentador HTML usa a biblioteca readability-lxml para extrair o conteúdo principal primeiro e, em seguida, extrai trechos de código de bloco das tags <pre> como fragmentos dedicados de "code". O conteúdo inline <code> permanece parte dos fragmentos narrativos.

Busca Semântica

  • A ferramenta search-chunks realiza busca semântica baseada em vetores sobre todo o conteúdo ingerido, retornando os fragmentos mais relevantes para uma determinada consulta.
  • Suporta argumentos opcionais type e tag para filtrar resultados por tipo de fragmento (ex.: code, html, markdown) e/ou por tag nos metadados do fragmento, antes da classificação semântica.
  • Isso permite recuperação altamente direcionada, como "todos os fragmentos de código marcados com 'langfuse' relevantes para 'cost and usage'".

Gerenciamento de Metadados

  • Os fragmentos incluem um campo metadata para categorização e marcação (tagging).
  • A ferramenta update-chunk-metadata permite atualizar metadados de qualquer fragmento pelo seu id.
  • A ferramenta tag-chunks-by-source permite adicionar tags a todos os fragmentos de uma fonte específica em uma única operação. A marcação mescla novas tags com as existentes, preservando tags anteriores.

Configuração

O servidor requer as seguintes variáveis de ambiente (podem ser definidas em um arquivo .env):

Configuração do Ollama

  • OLLAMA_HOST: Hostname para a API do Ollama (padrão: localhost)
  • OLLAMA_PORT: Porta para a API do Ollama (padrão: 11434)
  • RAG_AGENT: Modelo Ollama a ser usado para respostas RAG (padrão: llama3)
  • OLLAMA_MODEL: Modelo Ollama a ser usado para embeddings (padrão: nomic-embed-text-v2-moe)

Configuração do Banco de Dados

  • HOST: Host do banco de dados PostgreSQL (padrão: localhost)
  • DB_PORT: Porta do banco de dados PostgreSQL (padrão: 5432)
  • DB_NAME: Nome do banco de dados PostgreSQL (padrão: doclibdb)
  • DB_USER: Usuário do banco de dados PostgreSQL (padrão: doclibdb_user)
  • DB_PASSWORD: Senha do banco de dados PostgreSQL (padrão: doclibdb_password)

Configuração do Reranker

  • RERANKER_MODEL_PATH: Caminho para o modelo reranker (padrão: /srv/samba/fileshare2/AI/models/bge-reranker-v2-m3)
  • RERANKER_USE_FP16: Se deve usar FP16 para o reranker (padrão: True)

Início Rápido

Instalação

Claude Desktop

No MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json No Windows: %APPDATA%/Claude/claude_desktop_config.json

Configuração de Servidores Não Publicados ``` "mcpServers": { "doc-lib-mcp": { "command": "uv", "args": [ "--directory", "/home/administrator/python-share/doc-lib-mcp", "run", "doc-lib-mcp" ] } } ```
Configuração de Servidores Publicados ``` "mcpServers": { "doc-lib-mcp": { "command": "uvx", "args": [ "doc-lib-mcp" ] } } ```

Desenvolvimento

Compilação e Publicação

Para preparar o pacote para distribuição:

  1. Sincronize as dependências e atualize o lockfile:
uv sync
  1. Compile as distribuições do pacote:
uv build

Isso criará distribuições source e wheel no diretório dist/.

  1. Publique no PyPI:
uv publish

Observação: Você precisará definir as credenciais do PyPI via variáveis de ambiente ou flags de comando:

  • Token: --token ou UV_PUBLISH_TOKEN
  • Ou usuário/senha: --username/UV_PUBLISH_USERNAME e --password/UV_PUBLISH_PASSWORD

Depuração

Como os servidores MCP são executados via stdio, a depuração pode ser desafiadora. Para a melhor experiência de depuração, recomendamos fortemente o uso do MCP Inspector.

Você pode iniciar o MCP Inspector via npm com este comando:

npx @modelcontextprotocol/inspector uv --directory /home/administrator/python-share/doc-lib-mcp run doc-lib-mcp

Ao iniciar, o Inspector exibirá uma URL que você pode acessar no seu navegador para começar a depurar.