Knowledge Vault Search

Busca en un vault de conocimiento personal utilizando coincidencia híbrida semántica y por palabras clave.

GitHubPrueba este MCPPatrocinado

Documentación

Herramienta de Búsqueda en Knowledge Vault MCP

Esta herramienta proporciona un servidor MCP (Model Context Protocol) que le permite buscar en su knowledge vault personal utilizando coincidencias híbridas semánticas y de palabras clave. El servidor se conecta a la API de Fondu Knowledge Vault para recuperar información relevante de su base de conocimiento personal.

Características

  • Búsqueda Híbrida: Combina la búsqueda vectorial semántica con la coincidencia de palabras clave
  • Reordenamiento: Utiliza modelos de reordenamiento para priorizar los resultados más relevantes
  • Autenticación Flexible: Múltiples métodos de autenticación con resolución basada en prioridad
  • Listo para Producción: Manejo integral de errores y registro de actividades
  • Compatible con MCP: Funciona con Claude Desktop y otros clientes MCP
  • Transporte SSE: Eventos enviados por el servidor para comunicación en tiempo real

Requisitos Previos

  • Python 3.8+
  • Acceso a la API de Fondu Knowledge Vault
  • Token de autenticación válido

Instalación

  1. Clone este repositorio:
git clone <repository-url>
cd mcp_tools
  1. Configure el entorno virtual e instale las dependencias:
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Configuración de Autenticación

El servidor admite múltiples métodos de autenticación con el siguiente orden de prioridad:

1. Parámetro Explícito (Mayor Prioridad)

Pase el token directamente al llamar a la herramienta.

2. Variables de Entorno

Establezca una de estas variables de entorno:

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

3. Archivos de Configuración

Cree un archivo de configuración en una de estas ubicaciones:

  • ~/.fondu/config.yaml (recomendado)
  • ~/.config/fondu/config.yaml
  • config.yaml (en el directorio del proyecto)

Ejemplo de archivo de configuración:

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

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

4. Archivos de Token

Guarde su token en uno de estos archivos:

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

Iniciando el Servidor MCP

Método 1: Python Directo (Recomendado)

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

Método 2: Usando el script de ejecución

./run.sh

El servidor se iniciará en http://127.0.0.1:8080 con los siguientes endpoints:

  • / - Página de inicio
  • /health - Verificación de estado
  • /sse - Endpoint de eventos enviados por el servidor para MCP
  • /messages/ - Endpoint de manejo de mensajes

Configuración de Claude Desktop

Para usar con Claude Desktop, agregue esto a su ~/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 el script de ejecución:

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

Herramientas Disponibles

gather_relevant_user_knowledge

Busque en su knowledge vault utilizando coincidencias híbridas semánticas y de palabras clave.

Parámetros:

  • query (cadena, obligatorio): Consulta en lenguaje natural para búsqueda semántica y reordenamiento
  • auth_token (cadena, opcional): Token de autenticación (si no se establece mediante entorno/configuración)
  • keywords (cadena, opcional): Términos específicos para priorizar en la coincidencia de palabras clave
  • top_k (entero, opcional): Número de resultados a devolver (predeterminado: 10)

Devuelve: Una cadena formateada que contiene los resultados más relevantes de su knowledge vault, incluida información de origen y metadatos cuando estén disponibles.

Ejemplo de Respuesta:

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}

Pruebas

Prueba de Estado del Servidor

curl http://127.0.0.1:8080/health

Prueba de Funcionalidad de la Herramienta

Cree un script de prueba para verificar que la herramienta 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())

Ejemplos de Configuración

Se proporcionan archivos de configuración de ejemplo:

  • config.yaml.example - Plantilla de configuración del servidor
  • claude_desktop_config.json.example - Plantilla de configuración de Claude Desktop

Copie estos archivos y personalícelos con su configuración:

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

Manejo de Errores y Registro de Actividades

El servidor proporciona un manejo integral de errores:

  • Token de Autenticación Faltante: Mensaje de error claro con instrucciones de configuración
  • Errores de API: Manejo adecuado de problemas de red y fallos de API
  • Tokens Inválidos: Manejo adecuado de errores 403
  • Registro de Depuración: Registros detallados para solución de problemas

Los registros se escriben en:

  • Salida de error estándar (visible al ejecutar el servidor)
  • /tmp/error_log.txt (registro de errores de respaldo)

Configuración de API

El servidor se conecta a:

  • API de Producción: https://api.youfondu.com/v1/knowledge/search_knowledge_vault
  • Protocolo: HTTPS con autenticación de token Bearer
  • Tiempo de espera: 30 segundos para solicitudes de API
  • Formato: Solicitud/respuesta JSON

Solución de Problemas

Problemas Comunes

  1. Errores de Autenticación

    • Verifique que su token sea válido y no haya expirado
    • Compruebe que el token esté configurado correctamente mediante variable de entorno o archivo de configuración
    • Asegúrese de que no haya espacios en blanco adicionales en los archivos de token

  2. Problemas de Conexión

    • Verifique la conectividad a Internet
    • Compruebe si el endpoint de API es accesible: curl -I https://api.youfondu.com
    • Asegúrese de que no haya un firewall bloqueando HTTPS saliente

  3. Problemas con el Cliente MCP

    • Reinicie Claude Desktop después de los cambios de configuración
    • Compruebe que se utilicen rutas absolutas en la configuración
    • Verifique que el entorno virtual de Python esté activado correctamente

  4. Problemas de Inicio del Servidor

    • Asegúrese de que todas las dependencias estén instaladas: pip install -r requirements.txt
    • Compruebe que el puerto 8080 no esté ya en uso
    • Verifique que se esté utilizando Python 3.8+

Modo de Depuración

Para habilitar el registro de depuración, establezca la variable de entorno:

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

Prueba de Métodos de Autenticación

Puede probar diferentes métodos de autenticación:

# 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

Desarrollo

Para contribuir o modificar el servidor:

  1. Configurar el Entorno de Desarrollo

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

  2. Ejecutar Pruebas

    python test_mcp_server.py
python test_tool_functionality.py

  3. Estructura del Código

    • mcp_fondu_search_user_context/server.py - Implementación principal del servidor
    • requirements.txt - Dependencias de Python
    • run.sh - Script de conveniencia para iniciar el servidor
    • config.yaml.example - Plantilla de configuración
    • claude_desktop_config.json.example - Plantilla de configuración de Claude Desktop

Dependencias

Dependencias principales:

  • fastapi>=0.109.2 - Marco web
  • uvicorn>=0.27.1 - Servidor ASGI
  • httpx>=0.26.0 - Cliente HTTP
  • mcp>=1.3.0 - Model Context Protocol
  • PyYAML>=6.0 - Soporte de configuración YAML

Consulte requirements.txt para obtener la lista completa de dependencias.

Implementación

AWS App Runner

Este servidor está listo para implementarse en AWS App Runner. Consulte DEPLOYMENT.md para obtener instrucciones detalladas de implementación.

Implementación Rápida:

  1. Envíe el código a su repositorio de Git
  2. Cree un servicio de App Runner que apunte a su repositorio
  3. Establezca la variable de entorno FONDU_AUTH_TOKEN
  4. ¡Implemente!

El servidor incluye:

  • ✅ Configuración de App Runner (apprunner.yaml)
  • ✅ Soporte de Docker (Dockerfile)
  • ✅ Endpoint de verificación de estado (/health)
  • ✅ Configuración de variables de entorno
  • ✅ Registro de actividades listo para producción
  • ✅ Soporte de escalado automático

Otras Plataformas en la Nube

El servidor se puede implementar en cualquier plataforma que admita:

  • Python 3.8+
  • Variables de entorno
  • Tráfico HTTP/HTTPS en el puerto 8080

Plataformas probadas:

  • AWS App Runner ✅
  • Contenedores Docker ✅
  • Alojamiento VPS tradicional ✅

Licencia

[Agregue aquí su información de licencia]