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)

Configurar variables de entorno:

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

Cargar variables (PowerShell):

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

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

Fork el proyecto
Crea una rama: git checkout -b feature/nueva-funcionalidad
Commit: git commit -m 'feat: agregar nueva funcionalidad'
Push: git push origin feature/nueva-funcionalidad
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

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

Related Resources

Need Help?

Report Issue