JobNimbus MCP Client

Connect Claude Desktop to your remote JobNimbus MCP server from any computer

This package provides an MCP (Model Context Protocol) client that connects Claude Desktop to a remote JobNimbus MCP server. No local installation or repository cloning required!

✨ Características

• 🔒 Zero Storage Security: API keys NUNCA almacenadas en el servidor
• 🌐 Multi-Cliente: Soporta múltiples clientes simultáneos
• ⚡ Stateless: Cada request es independiente
• 🚦 Rate Limiting: Protección automática por cliente
• 🛠️ Extensible: Agregar nuevas herramientas en ~10 minutos
• 🔄 CI/CD Automático: Deploy con git push
• 📊 Monitoreo: Health checks y logs sanitizados

🎯 Arquitectura

Claude Desktop (API Key) → Render.com Server → JobNimbus API
         ↓                         ↓
   Local Config            Valida temporalmente
   (Nunca sale)            (Nunca almacena)

Principio clave: El servidor es un proxy stateless. Las API keys vienen del cliente en cada request y se limpian de memoria inmediatamente después de usarlas.

📦 Instalación Rápida

1. Clonar e Instalar

cd jobnimbus-mcp-remote
npm install

2. Configurar Entorno Local

cp .env.example .env

3. Ejecutar Localmente

npm run dev

Visitar: http://localhost:3000/health

4. Desplegar a Render.com

Ver: docs/SETUP.md para guía completa de deployment.

🔧 Herramientas Disponibles (48 TOTAL)

Básicas (11)

• get_system_info - Info del sistema
• validate_api_key - Validar API key
• get_jobs, search_jobs, get_job - Trabajos
• get_contacts, search_contacts, create_contact - Contactos
• get_estimates - Estimados
• get_activities, create_activity - Actividades

Analytics (16)

• analyze_insurance_pipeline - Análisis de pipeline de seguros
• analyze_retail_pipeline - Análisis de pipeline retail
• analyze_services_repair_pipeline - Servicios y reparaciones
• analyze_public_adjuster_pipeline - Ajustadores públicos
• analyze_duplicate_contacts, analyze_duplicate_jobs - Duplicados
• analyze_pricing_anomalies, analyze_revenue_leakage - Anomalías
• Y 8 más...

Performance & Revenue (8)

• get_sales_rep_performance - Performance por rep
• get_revenue_report - Reporte de ingresos
• get_margin_analysis - Análisis de márgenes
• get_pricing_optimization - Optimización de precios
• get_profitability_dashboard - Dashboard de rentabilidad
• Y 3 más...

Advanced (13)

• get_optimal_door_routes - Rutas óptimas puerta a puerta
• get_pipeline_forecasting - Pronósticos
• get_automated_followup - Seguimiento automático
• get_smart_scheduling - Programación inteligente
• Y 9 más...

Ver lista completa: Las 48 herramientas están implementadas y listas. Agregar más: Ver docs/ADDING_TOOLS.md

💻 Configuración Claude Desktop

Ubicación: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "jobnimbus-stamford": {
      "command": "node",
      "args": ["C:/ruta/a/examples/mcp-client.js"],
      "env": {
        "MCP_SERVER_URL": "https://tu-servidor.onrender.com",
        "JOBNIMBUS_API_KEY": "tu_api_key_stamford",
        "JOBNIMBUS_INSTANCE": "stamford"
      }
    }
  }
}

Ver ejemplo completo: examples/claude-desktop-config.json

📚 Documentación

• 📖 Setup Guide - Instalación y deployment
• 🏗️ Arquitectura - Diseño técnico completo
• 🛠️ Agregar Herramientas - Cómo crear nuevas tools

🔐 Seguridad

✅ Lo que HACE el servidor:

• Extrae API key del header X-JobNimbus-Api-Key
• Valida formato del API key
• Usa el API key para llamar a JobNimbus
• Limpia el API key de memoria inmediatamente

❌ Lo que NO HACE el servidor:

• Almacenar API keys en base de datos
• Guardar API keys en archivos
• Loggear API keys
• Cachear API keys
• Compartir API keys entre clientes

Verificación de Seguridad

# Buscar si hay API keys hardcodeados (debe retornar vacío)
grep -r "api[_-]key.*=" src/

# Audit de dependencias
npm audit

# Tests de seguridad en CI
npm run lint

🚀 Deployment

Automático (Recomendado)

git add .
git commit -m "feat: nueva funcionalidad"
git push origin main

GitHub Actions despliega automáticamente a Render.com.

Manual

npm run build
npm run start:prod

🧪 Testing

Health Check

curl https://tu-servidor.onrender.com/health

Listar Herramientas

curl -X POST https://tu-servidor.onrender.com/mcp/tools/list \
  -H "X-JobNimbus-Api-Key: tu_api_key" \
  -H "Content-Type: application/json"

Ejecutar Herramienta

curl -X POST https://tu-servidor.onrender.com/mcp/tools/call \
  -H "X-JobNimbus-Api-Key: tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name":"get_jobs","arguments":{"size":10}}'

📊 Monitoreo

Health Check Endpoint

• GET /health - Estado del servidor

Rate Limit Headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1234567890

Logs

Todos los logs están sanitizados - no incluyen API keys ni información sensible.

🛠️ Desarrollo

Estructura del Proyecto

jobnimbus-mcp-remote/
├── src/
│   ├── server/         # Express server
│   ├── middleware/     # Auth, rate limiting
│   ├── tools/          # MCP tools
│   ├── services/       # JobNimbus client
│   ├── config/         # Configuración
│   ├── types/          # TypeScript types
│   └── utils/          # Logger, errors
├── .github/workflows/  # CI/CD
├── docs/               # Documentación
├── scripts/            # Scripts útiles
└── examples/           # Ejemplos de uso

Comandos Disponibles

npm run dev          # Desarrollo con hot reload
npm run build        # Compilar TypeScript
npm run start        # Ejecutar producción
npm run lint         # Linter
npm run type-check   # Verificar tipos
npm test             # Tests

🤝 Contribuir

1. Fork el proyecto
2. Crea una rama: git checkout -b feature/nueva-funcionalidad
3. Commit: git commit -m 'feat: agregar nueva funcionalidad'
4. Push: git push origin feature/nueva-funcionalidad
5. Abre un Pull Request

📄 Licencia

MIT

🆘 Soporte

• Documentación: Ver carpeta docs/
• Issues: GitHub Issues
• Logs: Render.com dashboard

✅ Estado del Proyecto

• [x] Estructura base
• [x] Servidor Express con MCP
• [x] Middleware de seguridad
• [x] JobNimbus API client
• [x] Sistema de tools extensible
• [x] 48 herramientas COMPLETAS ✅
• [x] GitHub Actions CI/CD
• [x] Render.com config
• [x] Documentación completa
• [x] Cliente para Claude Desktop
• [x] Factory pattern para extensibilidad
• [ ] Tests unitarios (próximo)
• [ ] Métricas y monitoring avanzado (opcional)

Hecho con ❤️ para acceso remoto seguro a JobNimbus desde Claude Desktop