PROXIMOS_PASOS.md•7.95 kB
# 🎯 PRÓXIMOS PASOS - JobNimbus MCP Remote Server
## ✅ Lo que ya está hecho
Has recibido una implementación completa y lista para producción:
- ✅ Servidor Express con TypeScript
- ✅ Middleware de seguridad (API key extraction, rate limiting)
- ✅ JobNimbus API client stateless
- ✅ Sistema de tools extensible
- ✅ 3 herramientas de ejemplo (get_jobs, search_jobs, get_contacts)
- ✅ GitHub Actions CI/CD
- ✅ Configuración Render.com
- ✅ Cliente para Claude Desktop
- ✅ Documentación completa
---
## 🚀 FASE 1: Setup Inicial (30 minutos)
### 1. Instalar Dependencias
```bash
cd C:\Users\benito\poweria\jobnimbus\jobnimbus-mcp-remote
npm install
```
**Verificar**: Debe instalar sin errores.
### 2. Probar Localmente
```bash
npm run dev
```
**Verificar**:
- Servidor inicia en http://localhost:3000
- Visitar http://localhost:3000/health retorna JSON con status "healthy"
### 3. Corregir Importaciones si es necesario
Si hay errores de TypeScript, puede ser por:
- Falta `crypto` import en `src/server/index.ts`
- Paths relativos incorrectos
**Solución rápida**:
```typescript
// Agregar al inicio de src/server/index.ts
import { randomUUID } from 'crypto';
// Cambiar línea que usa crypto.randomUUID() a:
const requestId = randomUUID();
```
---
## 🐙 FASE 2: GitHub Setup (15 minutos)
### 1. Inicializar Git
```bash
cd C:\Users\benito\poweria\jobnimbus\jobnimbus-mcp-remote
git init
git add .
git commit -m "Initial commit: JobNimbus MCP Remote Server"
```
### 2. Crear Repositorio en GitHub
1. Ir a https://github.com/new
2. Nombre: `jobnimbus-mcp-remote`
3. Público o Privado (tu elección)
4. NO crear README, .gitignore, o licencia (ya los tienes)
5. Click "Create repository"
### 3. Push al Repositorio
```bash
git remote add origin https://github.com/TU_USUARIO/jobnimbus-mcp-remote.git
git branch -M main
git push -u origin main
```
**Verificar**: Código visible en GitHub.
---
## ☁️ FASE 3: Deploy a Render.com (20 minutos)
### 1. Crear Cuenta Render
1. Ir a https://render.com
2. Sign up (gratis)
3. Conectar GitHub account
### 2. Crear Web Service
1. Click "New +" → "Blueprint"
2. Conectar repositorio `jobnimbus-mcp-remote`
3. Render detectará `render.yaml` automáticamente
4. Click "Apply"
### 3. Esperar Deploy
- Primera vez: ~5-8 minutos
- Render ejecuta: `npm ci && npm run build`
- Luego: `npm run start:prod`
### 4. Obtener URL y Service ID
Después del deploy:
- **URL**: https://jobnimbus-mcp-remote.onrender.com (ejemplo)
- **Service ID**: En URL del dashboard (después de `/services/`)
### 5. Configurar GitHub Secrets
En tu repositorio GitHub:
1. Settings → Secrets and variables → Actions
2. New repository secret:
- `RENDER_API_KEY`: Obtener de Render.com → Account Settings → API Keys
- `RENDER_SERVICE_ID`: El ID del paso anterior
- `RENDER_SERVICE_URL`: Tu URL .onrender.com
**Verificar**:
```bash
curl https://tu-servidor.onrender.com/health
```
Debe retornar JSON con "status": "healthy".
---
## 💻 FASE 4: Configurar Claude Desktop (10 minutos)
### 1. Localizar Config
Windows: `%APPDATA%\Claude\claude_desktop_config.json`
Si no existe, créalo.
### 2. Editar Configuración
```json
{
"mcpServers": {
"jobnimbus-stamford": {
"command": "node",
"args": ["C:/Users/benito/poweria/jobnimbus/jobnimbus-mcp-remote/examples/mcp-client.js"],
"env": {
"MCP_SERVER_URL": "https://tu-servidor.onrender.com",
"JOBNIMBUS_API_KEY": "tu_api_key_stamford_real",
"JOBNIMBUS_INSTANCE": "stamford"
}
},
"jobnimbus-guilford": {
"command": "node",
"args": ["C:/Users/benito/poweria/jobnimbus/jobnimbus-mcp-remote/examples/mcp-client.js"],
"env": {
"MCP_SERVER_URL": "https://tu-servidor.onrender.com",
"JOBNIMBUS_API_KEY": "tu_api_key_guilford_real",
"JOBNIMBUS_INSTANCE": "guilford"
}
}
}
}
```
**Importante**:
- Reemplazar `https://tu-servidor.onrender.com` con tu URL real
- Reemplazar API keys con tus API keys reales de JobNimbus
### 3. Reiniciar Claude Desktop
Cierra y vuelve a abrir Claude Desktop completamente.
### 4. Probar
En Claude Desktop, escribe:
```
Get the first 10 jobs from JobNimbus Stamford
```
Claude debería usar la herramienta `get_jobs` y retornar resultados.
---
## 🛠️ FASE 5: Agregar Más Herramientas (Opcional)
Ver: [docs/ADDING_TOOLS.md](docs/ADDING_TOOLS.md)
Ejemplo rápido - agregar `get_estimates`:
### 1. Crear archivo
`src/tools/estimates/getEstimates.ts`:
```typescript
import { BaseTool } from '../baseTool.js';
import { MCPToolDefinition, ToolContext } from '../../types/index.js';
interface GetEstimatesInput {
from?: number;
size?: number;
}
export class GetEstimatesTool extends BaseTool<GetEstimatesInput, any> {
get definition(): MCPToolDefinition {
return {
name: 'get_estimates',
description: 'Retrieve estimates from JobNimbus',
inputSchema: {
type: 'object',
properties: {
from: { type: 'number', description: 'Start index' },
size: { type: 'number', description: 'Number of records' },
},
},
};
}
async execute(input: GetEstimatesInput, context: ToolContext): Promise<any> {
const result = await this.client.get(
context.apiKey,
'estimates',
{ from: input.from || 0, size: Math.min(input.size || 50, 100) }
);
return result.data;
}
}
```
### 2. Registrar
Editar `src/tools/index.ts`:
```typescript
import { GetEstimatesTool } from './estimates/getEstimates.js';
// En constructor:
this.registerTool(new GetEstimatesTool());
```
### 3. Deploy
```bash
git add .
git commit -m "feat: add get_estimates tool"
git push origin main
```
GitHub Actions despliega automáticamente (~6 min).
---
## 📊 FASE 6: Monitoreo (Opcional)
### Dashboard Render
https://dashboard.render.com
- Ver logs en tiempo real
- Métricas de CPU/memoria
- Deploy history
- Health checks
### Logs
```bash
# Ver logs en Render dashboard o:
curl https://tu-servidor.onrender.com/health
```
---
## 🐛 Troubleshooting Común
### Problema: TypeScript errors al compilar
**Solución**:
```bash
npm run type-check
```
Ver errores específicos y corregir.
### Problema: Servidor no inicia localmente
**Solución**:
```bash
# Verificar Node version
node --version # Debe ser 18+
# Reinstalar
rm -rf node_modules
npm install
```
### Problema: Claude Desktop no conecta
**Verificar**:
1. Ruta de `mcp-client.js` es correcta
2. URL del servidor es correcta
3. API key es válida
4. Reiniciaste Claude Desktop
**Test manual**:
```bash
curl -X POST https://tu-servidor.onrender.com/mcp/tools/list \
-H "X-JobNimbus-Api-Key: tu_api_key" \
-H "Content-Type: application/json"
```
Debe retornar lista de tools.
### Problema: Render deployment falla
**Verificar**:
1. Logs en Render dashboard
2. `render.yaml` es correcto
3. `package.json` tiene scripts correctos
---
## 📚 Recursos
- **Documentación**: `docs/` folder
- **Setup completo**: `docs/SETUP.md`
- **Arquitectura**: `docs/ARCHITECTURE.md`
- **Agregar tools**: `docs/ADDING_TOOLS.md`
---
## ✅ Checklist Final
- [ ] npm install exitoso
- [ ] Servidor corre localmente (localhost:3000)
- [ ] Health check retorna "healthy"
- [ ] Repositorio GitHub creado
- [ ] Código pushed a GitHub
- [ ] Render.com account creado
- [ ] Deploy a Render exitoso
- [ ] Health check remoto funciona
- [ ] GitHub secrets configurados
- [ ] Claude Desktop config actualizado
- [ ] Tools funcionan en Claude Desktop
---
## 🎉 Siguiente Nivel
Una vez que todo funciona:
1. **Agregar todas las ~50 herramientas** de tu servidor MCP local
2. **Configurar custom domain** (opcional)
3. **Agregar más clientes** (otros PCs con Claude Desktop)
4. **Monitorear uso** en Render dashboard
5. **Escalar** si es necesario (upgrade plan)
---
**¿Listo para empezar?** → Ir a FASE 1 ⬆️