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 (88 TOTAL - Optimizado)

Core CRUD (27 herramientas)

• Validación: validate_api_key - Validar API key

• Jobs (7): get_jobs, search_jobs, search_jobs_enhanced, get_job, search_job_notes, get_job_tasks

• Status Search (13): search_jobs_by_status, get_leads, get_pending_approval, get_lost_jobs, get_in_progress, get_completed, get_paid_closed, get_estimating, get_signed_contracts, get_scheduled, get_appointments, get_invoiced, get_deposits

• Contactos (3): get_contacts, search_contacts, create_contact

• Otros (3): get_estimates, get_activities, create_activity, get_calendar_activities, get_timeline_data

Analytics (35 herramientas)

• Insurance & Retail (3): analyze_insurance_pipeline, analyze_retail_pipeline, analyze_services_repair_pipeline

• Financial (6): get_sales_rep_performance, get_performance_metrics, get_automated_followup, get_revenue_report, get_margin_analysis, analyze_revenue_leakage, get_profitability_dashboard

• Performance (2): get_seasonal_trends, get_pipeline_forecasting

• Territory (5): get_job_summary, get_optimal_door_routes, get_territory_heat_maps, get_jobs_distribution, get_door_knocking_scripts_by_area, get_seasonal_door_timing, get_estimates_with_addresses

• Productivity (9): get_activities_analytics, get_task_management_analytics, get_user_productivity_analytics, get_lead_scoring_analytics, get_communication_analytics, get_conversion_funnel_analytics, get_resource_allocation_analytics, get_customer_satisfaction_analytics, get_time_tracking_analytics

• Business (8): get_project_management_analytics, get_marketing_campaign_analytics, get_financial_forecasting_analytics, get_customer_segmentation_analytics, get_operational_efficiency_analytics, get_sales_velocity_analytics, get_competitive_analysis_analytics

Materials (11 herramientas)

• Tracking: get_estimate_materials, analyze_material_costs, get_material_usage_report, get_material_inventory_insights

• Calculations: calculate_roofing_materials, calculate_siding_materials, estimate_materials_from_job, calculate_waste_factors, optimize_material_orders, get_material_specifications, compare_material_alternatives

Attachments & Business Intelligence (6 herramientas)

• Attachments (4): get_attachments, get_file_by_id, analyze_job_attachments, get_job_attachments_distribution

• Business (1): search_insurance_jobs

• Invoices (1): get_invoices

System (2 herramientas)

• get_tasks, get_users

📦 Herramientas Archivadas/Experimentales

Se removieron 14 herramientas obsoletas o no funcionales para optimizar rendimiento:

• Ver /src/tools/archived/ - 11 herramientas sin valor operativo

• Ver /src/tools/experimental/ - 7 herramientas con endpoints no verificados

Beneficios: ~40% reducción en uso de tokens, descubrimiento de herramientas más rápido. Agregar más: Ver docs/ADDING_TOOLS.md

💻 Configuración MCP

Opción 1: Claude Code (Recomendado)

1. Configurar variables de entorno:

cp .env.mcp.example .env.mcp
# Edita .env.mcp con tus API keys

2. Cargar variables (PowerShell):

Get-Content .env.mcp | ForEach-Object {
    if ($_ -match '^([^=]+)=(.+)$') {
        [Environment]::SetEnvironmentVariable($matches[1], $matches[2], 'Process')
    }
}

3. Verificar:

/mcp

Ver guía completa: MCP_SETUP.md

Opción 2: 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

• 🔌 MCP Setup - Configuración de MCP para Claude Code

• 🏗️ 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

• Estructura base

• Servidor Express con MCP

• Middleware de seguridad

• JobNimbus API client

• Sistema de tools extensible

• 88 herramientas CONSOLIDADAS ✅ (14 archivadas/experimentales)

• GitHub Actions CI/CD

• Render.com config

• Documentación completa

• Cliente para Claude Desktop

• Factory pattern para extensibilidad

• Redis cache integration para optimización

• Consolidación de herramientas (enero 2025)

• Tests unitarios (próximo)

• Métricas y monitoring avanzado (opcional)

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