adolfolopez88/adam-mcp-server

🤖 Adam MCP Server

✨ Características

• 🔗 Web Scraping Inteligente: Extracción robusta de contenido desde cualquier URL
• 🧠 Integración Claude AI: Análisis avanzado de contenido con prompts personalizados
• 🌐 API REST: Endpoints HTTP fáciles de usar con documentación Swagger
• 📋 Protocolo MCP: Implementación completa del Model Context Protocol
• 🐳 Dockerizado: Contenedor listo para producción con mejores prácticas de seguridad
• 📊 Monitoreo: Health checks y métricas integradas
• 🔄 Resiliente: Manejo robusto de errores y fallbacks múltiples

🚀 Inicio Rápido

Con Docker (Recomendado)

# Clonar el repositorio
git clone https://github.com/TU-USUARIO/adam-mcp-server.git
cd adam-mcp-server

# Configurar variables de entorno
cp .env.example .env
# Editar .env con tu CLAUDE_API_KEY

# Ejecutar con Docker Compose
docker-compose up -d

# Verificar que está funcionando
curl http://localhost:8080/api/mcp/health

Acceso Rápido

• 🎯 API Base: http://localhost:8080/api/mcp/
• 📚 Swagger UI: http://localhost:8080/swagger
• ❤️ Health Check: http://localhost:8080/api/mcp/health

📖 Documentación API

POST /api/mcp/process

Extrae contenido de una URL y lo analiza con Claude AI.

curl -X POST "http://localhost:8080/api/mcp/process" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "prompt": "Summarize the main points of this article"
  }'

Respuesta:

{
  "url": "https://example.com",
  "prompt": "Summarize the main points",
  "scraped_content_length": 1250,
  "claude_response": "This article discusses...",
  "processed_at": "2025-08-12T22:30:00Z"
}

GET /api/mcp/health

Verifica el estado del servidor.

curl http://localhost:8080/api/mcp/health

GET /api/mcp/status

Información detallada del servicio.

curl http://localhost:8080/api/mcp/status

🐳 Docker

Ejecución Rápida

# Usando Docker Compose
docker-compose up -d

# O manualmente
docker run -d \
  --name adam-server \
  -p 8080:8080 \
  -e CLAUDE_API_KEY=tu_api_key \
  adam-mcp-server

Comandos Útiles

# Ver logs
docker-compose logs -f

# Reconstruir
docker-compose up -d --build

# Detener
docker-compose down

# Estado de contenedores
docker-compose ps

⚙️ Configuración

Variables de Entorno

Archivo .env

# Copiar el archivo de ejemplo
cp .env.example .env

# Editar con tus valores
CLAUDE_API_KEY=sk-ant-api03-xxxxxxxxxxxxx
MCP_PORT=8080
LOG_LEVEL=Information

🛠️ Desarrollo

Prerrequisitos

• .NET 9.0 SDK
• Docker Desktop
• Claude API Key

Configuración Local

# Clonar repositorio
git clone https://github.com/TU-USUARIO/adam-mcp-server.git
cd adam-mcp-server

# Restaurar dependencias
dotnet restore

# Ejecutar en modo desarrollo
dotnet run --project AdamMCPServer

Comandos de Desarrollo

# Compilar
dotnet build

# Ejecutar tests (cuando estén disponibles)
dotnet test

# Publicar
dotnet publish -c Release -o ./publish

# Análisis de código
dotnet format

🏗️ Arquitectura

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   REST API      │    │   MCP Protocol   │    │   Background    │
│   Controller    │────│   Server         │────│   Tasks         │
└─────────────────┘    └──────────────────┘    └─────────────────┘
         │                        │                        │
         ▼                        ▼                        ▼
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│  Web Scraper    │    │   Claude API     │    │   Logging &     │
│  Service        │    │   Service        │    │   Monitoring    │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Componentes Principales

• MCPController: API REST endpoints
• MCPServer: Protocolo MCP (ejecuta en background)
• WebScraperService: Extracción de contenido web
• ClaudeApiService: Integración con Claude AI

📋 Ejemplos de Uso

Análisis de Noticias

curl -X POST "http://localhost:8080/api/mcp/process" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.bbc.com/news",
    "prompt": "Extract the top 3 headlines and summarize each"
  }'

Análisis de Documentación

curl -X POST "http://localhost:8080/api/mcp/process" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://docs.microsoft.com/en-us/dotnet/",
    "prompt": "List the main .NET features mentioned"
  }'

Extracción de Datos de Producto

curl -X POST "http://localhost:8080/api/mcp/process" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.example-store.com/product/123",
    "prompt": "Extract product name, price, and key features"
  }'

🚨 Resolución de Problemas

Problemas Comunes

• ❌ No se puede acceder a Swagger: Verificar que el contenedor esté ejecutándose en el puerto correcto
• ❌ Error XPath: Solucionado en v1.0 - el scraper ahora es más robusto
• ❌ Claude API Error: Verificar que CLAUDE_API_KEY esté configurada correctamente

Diagnóstico

# Verificar estado del contenedor
docker ps

# Ver logs detallados
docker logs adam-server -f

# Probar conectividad
curl http://localhost:8080/api/mcp/health

# Verificar variables de entorno
docker exec adam-server env | grep CLAUDE

📚 Documentación Adicional

• - Guía completa de Docker
• - Solución de problemas
• - Ejemplos avanzados de API
• - Corrección de errores XPath

🤝 Contribuciones

Las contribuciones son bienvenidas! Por favor:

1. Fork el repositorio
2. Crear una rama para tu feature (git checkout -b feature/AmazingFeature)
3. Commit tus cambios (git commit -m 'Add some AmazingFeature')
4. Push a la rama (git push origin feature/AmazingFeature)
5. Abrir un Pull Request

📄 Licencia

Este proyecto está bajo la Licencia MIT. Ver para más detalles.

🙏 Reconocimientos

• Claude AI por el procesamiento inteligente de texto
• HtmlAgilityPack por el web scraping robusto
• ASP.NET Core por el framework web