Knowledge Vault Search

Pesquise em um cofre de conhecimento pessoal usando correspondência híbrida semântica e por palavras-chave.

GitHubExperimente este MCPPatrocinado

Documentação

Ferramenta de Busca no Knowledge Vault MCP

Esta ferramenta fornece um servidor MCP (Model Context Protocol) que permite buscar em seu knowledge vault pessoal usando correspondência híbrida semântica e por palavras-chave. O servidor se conecta à API do Fondu Knowledge Vault para recuperar informações relevantes de sua base de conhecimento pessoal.

Recursos

  • Busca Híbrida: Combina busca vetorial semântica com correspondência por palavras-chave
  • Reordenamento: Usa modelos de reordenamento para priorizar os resultados mais relevantes
  • Autenticação Flexível: Múltiplos métodos de autenticação com resolução baseada em prioridade
  • Pronto para Produção: Tratamento abrangente de erros e registro de logs
  • Compatível com MCP: Funciona com Claude Desktop e outros clientes MCP
  • Transporte SSE: Server-Sent Events para comunicação em tempo real

Pré-requisitos

  • Python 3.8+
  • Acesso à API do Fondu Knowledge Vault
  • Token de autenticação válido

Instalação

  1. Clone este repositório:
git clone <repository-url>
cd mcp_tools
  1. Configure o ambiente virtual e instale as dependências:
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Configuração de Autenticação

O servidor suporta múltiplos métodos de autenticação com a seguinte ordem de prioridade:

1. Parâmetro Explícito (Maior Prioridade)

Passe o token diretamente ao chamar a ferramenta.

2. Variáveis de Ambiente

Defina uma destas variáveis de ambiente:

export FONDU_AUTH_TOKEN="your-token-here"
# or
export FONDU_API_TOKEN="your-token-here"

3. Arquivos de Configuração

Crie um arquivo de configuração em um destes locais:

  • ~/.fondu/config.yaml (recomendado)
  • ~/.config/fondu/config.yaml
  • config.yaml (no diretório do projeto)

Exemplo de arquivo de configuração:

fondu:
  auth_token: "your-token-here"
  base_url: "https://api.youfondu.com"

server:
  host: "127.0.0.1"
  port: 8080
  debug: true

4. Arquivos de Token

Salve seu token em um destes arquivos:

  • ~/.fondu/token
  • ~/.config/fondu/token
  • .fondu_token

Iniciando o Servidor MCP

Método 1: Python Direto (Recomendado)

source .venv/bin/activate
python mcp_fondu_search_user_context/server.py --host 127.0.0.1 --port 8080

Método 2: Usando o script de execução

./run.sh

O servidor iniciará em http://127.0.0.1:8080 com os seguintes endpoints:

  • / - Página inicial
  • /health - Verificação de saúde
  • /sse - Endpoint Server-Sent Events para MCP
  • /messages/ - Endpoint de manipulação de mensagens

Configuração do Claude Desktop

Para usar com o Claude Desktop, adicione isto ao seu ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "knowledge_vault": {
      "command": "python",
      "args": ["/absolute/path/to/mcp_tools/mcp_fondu_search_user_context/server.py"],
      "env": {
        "FONDU_AUTH_TOKEN": "your-auth-token-here"
      }
    }
  }
}

Alternativa usando o script de execução:

{
  "mcpServers": {
    "knowledge_vault": {
      "command": "/absolute/path/to/mcp_tools/run.sh",
      "env": {
        "FONDU_AUTH_TOKEN": "your-auth-token-here"
      }
    }
  }
}

Ferramentas Disponíveis

gather_relevant_user_knowledge

Busque em seu knowledge vault usando correspondência híbrida semântica e por palavras-chave.

Parâmetros:

  • query (string, obrigatório): Consulta em linguagem natural para busca semântica e reordenamento
  • auth_token (string, opcional): Token de autenticação (se não definido via env/config)
  • keywords (string, opcional): Termos específicos para priorizar na correspondência por palavras-chave
  • top_k (inteiro, opcional): Número de resultados a retornar (padrão: 10)

Retornos: Uma string formatada contendo os resultados mais relevantes do seu knowledge vault, incluindo informações de origem e metadados quando disponíveis.

Exemplo de Resposta:

Found 3 relevant results in your knowledge vault:

1. Quantum computing uses quantum mechanical phenomena like superposition and entanglement to perform calculations...
Source: quantum_computing_notes.md
Metadata: {'tags': ['physics', 'computing'], 'date': '2024-01-15'}

2. The fundamental principle behind quantum algorithms is the ability to exist in multiple states simultaneously...
Source: research_papers/quantum_algorithms.pdf
Metadata: {'author': 'Dr. Smith', 'year': 2023}

Testes

Teste de Saúde do Servidor

curl http://127.0.0.1:8080/health

Teste de Funcionalidade da Ferramenta

Crie um script de teste para verificar se a ferramenta funciona:

import asyncio
import sys
sys.path.append('mcp_fondu_search_user_context')

from server import gather_relevant_user_knowledge

async def test_tool():
    result = await gather_relevant_user_knowledge(
        query="machine learning algorithms",
        auth_token="your-token-here",
        top_k=5
    )
    print(result)

asyncio.run(test_tool())

Exemplos de Configuração

Arquivos de configuração de exemplo são fornecidos:

  • config.yaml.example - Modelo de configuração do servidor
  • claude_desktop_config.json.example - Modelo de configuração do Claude Desktop

Copie estes arquivos e personalize com suas configurações:

cp config.yaml.example ~/.fondu/config.yaml
# Edit with your auth token and preferences

Tratamento de Erros e Registro de Logs

O servidor fornece tratamento abrangente de erros:

  • Token de Autenticação Ausente: Mensagem de erro clara com instruções de configuração
  • Erros de API: Tratamento adequado de problemas de rede e falhas de API
  • Tokens Inválidos: Tratamento adequado de erro 403
  • Registro de Depuração: Logs detalhados para solução de problemas

Os logs são gravados em:

  • Saída de erro padrão (visível ao executar o servidor)
  • /tmp/error_log.txt (registro de erro de fallback)

Configuração da API

O servidor se conecta a:

  • API de Produção: https://api.youfondu.com/v1/knowledge/search_knowledge_vault
  • Protocolo: HTTPS com autenticação por token Bearer
  • Tempo limite: 30 segundos para solicitações de API
  • Formato: JSON de solicitação/resposta

Solução de Problemas

Problemas Comuns

  1. Erros de Autenticação

    • Verifique se seu token é válido e não expirou
    • Verifique se o token está configurado corretamente via variável de ambiente ou arquivo de configuração
    • Certifique-se de que não há espaços extras nos arquivos de token

  2. Problemas de Conexão

    • Verifique a conectividade com a internet
    • Verifique se o endpoint da API está acessível: curl -I https://api.youfondu.com
    • Certifique-se de que nenhum firewall bloqueie HTTPS de saída

  3. Problemas com Cliente MCP

    • Reinicie o Claude Desktop após alterações de configuração
    • Verifique se caminhos absolutos são usados na configuração
    • Verifique se o ambiente virtual Python está ativado corretamente

  4. Problemas de Inicialização do Servidor

    • Certifique-se de que todas as dependências estão instaladas: pip install -r requirements.txt
    • Verifique se a porta 8080 não está em uso
    • Verifique se Python 3.8+ está sendo usado

Modo de Depuração

Para habilitar o registro de depuração, defina a variável de ambiente:

export PYTHONPATH=/path/to/mcp_tools
export DEBUG=1
python mcp_fondu_search_user_context/server.py

Testando Métodos de Autenticação

Você pode testar diferentes métodos de autenticação:

# Test with environment variable
export FONDU_AUTH_TOKEN="your-token"
python test_auth.py

# Test with config file
echo "fondu:\n  auth_token: your-token" > ~/.fondu/config.yaml
python test_auth.py

# Test with token file
echo "your-token" > ~/.fondu/token
python test_auth.py

Desenvolvimento

Para contribuir ou modificar o servidor:

  1. Configurar Ambiente de Desenvolvimento

    python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

  2. Executar Testes

    python test_mcp_server.py
python test_tool_functionality.py

  3. Estrutura do Código

    • mcp_fondu_search_user_context/server.py - Implementação principal do servidor
    • requirements.txt - Dependências Python
    • run.sh - Script de conveniência para iniciar o servidor
    • config.yaml.example - Modelo de configuração
    • claude_desktop_config.json.example - Modelo de configuração do Claude Desktop

Dependências

Dependências principais:

  • fastapi>=0.109.2 - Framework web
  • uvicorn>=0.27.1 - Servidor ASGI
  • httpx>=0.26.0 - Cliente HTTP
  • mcp>=1.3.0 - Model Context Protocol
  • PyYAML>=6.0 - Suporte a configuração YAML

Consulte requirements.txt para a lista completa de dependências.

Implantação

AWS App Runner

Este servidor está pronto para implantação no AWS App Runner. Consulte DEPLOYMENT.md para instruções detalhadas de implantação.

Implantação Rápida:

  1. Envie o código para seu repositório Git
  2. Crie um serviço App Runner apontando para seu repositório
  3. Defina a variável de ambiente FONDU_AUTH_TOKEN
  4. Implante!

O servidor inclui:

  • ✅ Configuração do App Runner (apprunner.yaml)
  • ✅ Suporte a Docker (Dockerfile)
  • ✅ Endpoint de verificação de saúde (/health)
  • ✅ Configuração por variáveis de ambiente
  • ✅ Registro de logs pronto para produção
  • ✅ Suporte a auto-escala

Outras Plataformas de Nuvem

O servidor pode ser implantado em qualquer plataforma que suporte:

  • Python 3.8+
  • Variáveis de ambiente
  • Tráfego HTTP/HTTPS na porta 8080

Plataformas testadas:

  • AWS App Runner ✅
  • Contêineres Docker ✅
  • Hospedagem VPS tradicional ✅

Licença

[Adicione suas informações de licença aqui]