sep-mpc-server

Un servidor para procesar embeddings semánticos, que requiere archivos de datos externos montados mediante un volumen de Docker.

GitHub
1
Prueba este MCPPatrocinado

Documentación

Stanford Encyclopedia of Philosophy MCP Server

Un servidor de Model Context Protocol (MCP) que proporciona acceso a búsqueda semántica a la Stanford Encyclopedia of Philosophy completa mediante incrustaciones vectoriales y ChromaDB.

🎯 Características

  • Base de datos SEP completa: Acceso a todos los ~1840 artículos de filosofía
  • Búsqueda vectorial: Búsqueda semántica usando sentence transformers (all-MiniLM-L6-v2)
  • Contenedor Docker: Fácil despliegue y entorno consistente
  • Integración con Claude Desktop: Integración directa con el cliente Claude Desktop
  • Contenido fragmentado: Fragmentación inteligente de texto para una precisión de recuperación óptima
  • Protocolo MCP: Cumplimiento total del Model Context Protocol

📋 Requisitos previos

  • Python 3.11+
  • Docker Desktop
  • Aplicación Claude Desktop
  • ~10GB de espacio en disco para la base de datos completa
  • Conexión a internet para el scraping inicial y descargas de modelos

🏗️ Estructura del proyecto

SEP_MCP_SERVER/
├── scraper/
│   └── SEP_scraper.py           # Stanford Encyclopedia scraper
├── vectorization/
│   ├── vectorize_html.py        # HTML to vector conversion
│   └── philosophy_vectordb/     # ChromaDB vector database
├── mcp_server/
│   ├── philosophy_mcp_server.py # Main MCP server
│   ├── mcp_vector_interface.py  # Vector search interface  
│   ├── Dockerfile               # Container definition
│   ├── docker-compose.yml       # Docker Compose config
│   ├── docker_helper.sh         # Helper scripts
│   ├── requirements.txt         # Python dependencies
│   └── test_mcp_server.py       # Server tests
└── README.md                    # This file

🚀 Guía de configuración completa

Paso 1: Scrape de la Stanford Encyclopedia of Philosophy

# Navigate to scraper directory
cd scraper

# Install dependencies
pip install requests beautifulsoup4 lxml

# Run the scraper (takes 30-60 minutes)
python SEP_scraper.py

# Verify scraping results
ls ../data/*.html | wc -l  # Should show ~1840 files

Salida esperada: ~1840 archivos HTML en el directorio data/

Paso 2: Vectorizar el contenido de filosofía

# Navigate to vectorization directory
cd ../vectorization

# Install vectorization dependencies
pip install chromadb sentence-transformers beautifulsoup4 torch

# Run vectorization (takes 2-4 hours depending on hardware)
python vectorize_html.py

# Verify database creation
ls -la philosophy_vectordb/

Salida esperada: Base de datos ChromaDB en el directorio philosophy_vectordb/

Paso 3: Construir el contenedor Docker

# Navigate to MCP server directory
cd ../mcp_server

# Build the Docker image
docker build -t philosophy-mcp .

# Verify image was created
docker images | grep philosophy-mcp

Paso 4: Probar el contenedor Docker

# Test database stats
docker run --rm -it \
  -v /absolute/path/to/SEP_MCP_SERVER/vectorization/philosophy_vectordb:/app/philosophy_vectordb:rw \
  philosophy-mcp \
  python3 mcp_vector_interface.py stats

# Test search functionality  
docker run --rm -it \
  -v /absolute/path/to/SEP_MCP_SERVER/vectorization/philosophy_vectordb:/app/philosophy_vectordb:rw \
  philosophy-mcp \
  python3 mcp_vector_interface.py search "consciousness" 3

# List available entries
docker run --rm -it \
  -v /absolute/path/to/SEP_MCP_SERVER/vectorization/philosophy_vectordb:/app/philosophy_vectordb:rw \
  philosophy-mcp \
  python3 mcp_vector_interface.py list

¡Reemplaza /absolute/path/to/SEP_MCP_SERVER con la ruta real de tu proyecto!

Paso 5: Configurar Claude Desktop

Edita la configuración de Claude Desktop:

En macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
En Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "sep": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "-v",
        "/absolute/path/to/SEP_MCP_SERVER/vectorization/philosophy_vectordb:/app/philosophy_vectordb:rw",
        "philosophy-mcp"
      ]
    }
  }
}

**

⚠️

IMPORTANTE**: ¡Reemplaza /absolute/path/to/SEP_MCP_SERVER con tu ruta completa real!

Paso 6: Reiniciar Claude Desktop

  1. Cierra Claude Desktop por completo
  2. Reinicia Claude Desktop
  3. Busca la conexión del servidor MCP en la interfaz

🧪 Probando tu configuración

Comandos de prueba

# Check database statistics
docker run --rm -it \
  -v /your/path/SEP_MCP_SERVER/vectorization/philosophy_vectordb:/app/philosophy_vectordb:rw \
  philosophy-mcp \
  python3 mcp_vector_interface.py stats

# Search for specific topics
docker run --rm -it \
  -v /your/path/SEP_MCP_SERVER/vectorization/philosophy_vectordb:/app/philosophy_vectordb:rw \
  philosophy-mcp \
  python3 mcp_vector_interface.py search "category theory" 5

docker run --rm -it \
  -v /your/path/SEP_MCP_SERVER/vectorization/philosophy_vectordb:/app/philosophy_vectordb:rw \
  philosophy-mcp \
  python3 mcp_vector_interface.py search "free will" 3

Resultados esperados

  • Las estadísticas deberían mostrar: ~1840 entradas, miles de fragmentos
  • La búsqueda debería devolver: Pasajes de filosofía relevantes con puntuaciones de relevancia
  • Claude Desktop debería mostrar: La herramienta SEP disponible en la interfaz

🛠️ Solución de problemas

Problemas comunes

1. Error de "base de datos de solo lectura"

# Solution: Use :rw instead of :ro in volume mount
-v /path/to/philosophy_vectordb:/app/philosophy_vectordb:rw

2. "No such file or directory"

# Solution: Use absolute path, not relative path
# Wrong: -v ./vectorization/philosophy_vectordb:/app/philosophy_vectordb:rw  
# Right: -v /Users/username/SEP_MCP_SERVER/vectorization/philosophy_vectordb:/app/philosophy_vectordb:rw

3. Claude Desktop no se conecta

  • Asegúrate de que Docker esté en ejecución
  • Verifica la ruta y la sintaxis del archivo de configuración
  • Reinicia Claude Desktop por completo
  • Verifica que la ruta del volumen montado sea correcta

4. Resultados de búsqueda vacíos

  • Verifica que la base de datos se haya creado correctamente
  • Comprueba que la vectorización se completó con éxito
  • Prueba primero con los comandos de Docker

Comandos de depuración

# Check if database exists
ls -la vectorization/philosophy_vectordb/

# Test container without volume (should fail gracefully)
docker run --rm -it philosophy-mcp python3 mcp_vector_interface.py stats

# Check Docker container logs
docker run --rm -it philosophy-mcp ls -la /app/

# Verify Python dependencies in container
docker run --rm -it philosophy-mcp pip list

📚 Ejemplos de uso

Una vez conectado a Claude Desktop, puedes hacer preguntas como:

  • "Busca información sobre la conciencia en la Stanford Encyclopedia"
  • "¿Qué dice la SEP sobre el libre albedrío?"
  • "Encuentra artículos relacionados con la teoría de categorías"
  • "Busca contenido sobre fenomenología"

🔧 Configuración avanzada

Ajuste de rendimiento

  • Tamaño de fragmento: Modifica chunk_size en vectorize_html.py para diferente granularidad
  • Selección de modelo: Cambia el modelo de incrustación en el script de vectorización
  • Límites de memoria: Agrega restricciones de memoria de Docker si es necesario

Actualización de contenido

# Re-scrape new/updated articles
cd scraper && python SEP_scraper.py

# Re-vectorize (preserves existing, adds new)
cd vectorization && python vectorize_html.py

# Rebuild container if server code changed
cd mcp_server && docker build -t philosophy-mcp .

🎉 Indicadores de éxito

✅ ~1840 archivos HTML en el directorio data/
✅ Base de datos ChromaDB creada en philosophy_vectordb/
✅ Contenedor Docker se construye correctamente
✅ Comandos de búsqueda devuelven resultados relevantes
✅ Claude Desktop muestra las herramientas SEP disponibles
✅ Servidor MCP responde a consultas de filosofía

📞 Soporte

Si encuentras problemas:

  1. Verifica que todos los requisitos previos estén instalados
  2. Comprueba que las rutas de archivo sean absolutas y correctas
  3. Asegúrate de que Docker Desktop esté en ejecución
  4. Prueba los comandos de Docker antes de la integración con Claude
  5. Verifica la sintaxis de la configuración de Claude Desktop

Tiempo total de configuración: 3-5 horas (mayormente procesamiento automatizado)
Tamaño de la base de datos: ~2-3GB después de la vectorización
Rendimiento: Respuestas de búsqueda en menos de un segundo

Configuración a agregar:

{
  "mcpServers": {
    "sep": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "-v",
        "/Users/claytongroth/DEV/SEP_MCP_SERVER/vectorization/philosophy_vectordb:/app/philosophy_vectordb:rw",
        "philosophy-mcp"
      ]
    }
  }
}