sep-mpc-server

Um servidor para processamento de embeddings semânticos, que requer arquivos de dados externos montados via volume Docker.

GitHub

Experimente este MCPPatrocinado

Documentação

Servidor MCP da Stanford Encyclopedia of Philosophy

Um servidor Model Context Protocol (MCP) que fornece acesso a busca semântica para a Stanford Encyclopedia of Philosophy completa através de embeddings vetoriais e ChromaDB.

🎯 Recursos

Banco de dados SEP completo: Acesso a todos os ~1840 artigos de filosofia
Busca vetorial: Busca semântica usando sentence transformers (all-MiniLM-L6-v2)
Container Docker: Implantação fácil e ambiente consistente
Integração com Claude Desktop: Integração direta com o cliente Claude Desktop
Conteúdo em blocos: Divisão inteligente de texto para precisão ideal na recuperação
Protocolo MCP: Conformidade total com o Model Context Protocol

📋 Pré-requisitos

Python 3.11+
Docker Desktop
Aplicativo Claude Desktop
~10GB de espaço em disco para o banco de dados completo
Conexão com a internet para a raspagem inicial e download dos modelos

🏗️ Estrutura do Projeto

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

🚀 Guia Completo de Configuração

Passo 1: Raspar a 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

Saída esperada: ~1840 arquivos HTML no diretório data/

Passo 2: Vetorizar o Conteúdo de Filosofia

# 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/

Saída esperada: Banco de dados ChromaDB no diretório philosophy_vectordb/

Passo 3: Construir o Container 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

Passo 4: Testar o Container 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

Substitua /absolute/path/to/SEP_MCP_SERVER pelo caminho real do seu projeto!

Passo 5: Configurar o Claude Desktop

Edite a configuração do Claude Desktop:

No macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
No 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**: Substitua /absolute/path/to/SEP_MCP_SERVER pelo caminho completo real!

Passo 6: Reiniciar o Claude Desktop

Saia completamente do Claude Desktop
Reinicie o Claude Desktop
Procure pela conexão do servidor MCP na interface

🧪 Testando Sua Configuração

Comandos de Teste

# 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

As estatísticas devem mostrar: ~1840 entradas, milhares de blocos
A busca deve retornar: Passagens relevantes de filosofia com pontuações de relevância
O Claude Desktop deve mostrar: Ferramenta SEP disponível na interface

🛠️ Solução de Problemas

Problemas Comuns

1. Erro "readonly database"

# 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 não conectando

Certifique-se de que o Docker está em execução
Verifique o caminho e a sintaxe do arquivo de configuração
Reinicie o Claude Desktop completamente
Verifique se o caminho do volume montado está correto

4. Resultados de busca vazios

Verifique se o banco de dados foi criado corretamente
Confirme se a vetorização foi concluída com sucesso
Teste primeiro com os comandos do Docker

Comandos de Depuração

# 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

📚 Exemplos de Uso

Uma vez conectado ao Claude Desktop, você pode fazer perguntas como:

"Busque informações sobre consciência na Stanford Encyclopedia"
"O que a SEP diz sobre livre-arbítrio?"
"Encontre artigos relacionados à teoria das categorias"
"Busque conteúdo sobre fenomenologia"

🔧 Configuração Avançada

Ajuste de Desempenho

Tamanho do bloco: Modifique chunk_size em vectorize_html.py para diferentes granularidades
Seleção do modelo: Altere o modelo de embedding no script de vetorização
Limites de memória: Adicione restrições de memória do Docker se necessário

Atualizando o Conteúdo

# 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 Sucesso

✅ ~1840 arquivos HTML no diretório data/
✅ Banco de dados ChromaDB criado em philosophy_vectordb/
✅ Container Docker compilado com sucesso
✅ Comandos de busca retornam resultados relevantes
✅ Claude Desktop mostra as ferramentas SEP disponíveis
✅ Servidor MCP responde a consultas de filosofia

📞 Suporte

Se você encontrar problemas:

Verifique se todos os pré-requisitos estão instalados
Confirme se os caminhos dos arquivos são absolutos e corretos
Certifique-se de que o Docker Desktop está em execução
Teste os comandos do Docker antes da integração com o Claude
Verifique a sintaxe da configuração do Claude Desktop

Tempo total de configuração: 3-5 horas (majoritariamente processamento automatizado)
Tamanho do banco de dados: ~2-3GB após a vetorização
Desempenho: Respostas de busca em menos de um segundo

Configuração para adicionar:

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