GOC MCP Server

Servidor MCP (Model Context Protocol) para el sistema GOC — plataforma de gestión de construcción. Permite a Claude y otros agentes de IA consultar datos de GOC en tiempo real mediante lenguaje natural.

¿Qué es esto?

Este servidor expone herramientas de consulta y administración que Claude puede usar para responder preguntas como:

• "¿Cuántas asistencias tuvo Juan García este mes?"

• "¿Cómo va el pedido #450?"

• "¿Qué empleados están asignados a la obra Torre Norte?"

• "¿Quién asistió hoy en la obra 12?"

Related MCP server: QC Database MCP Server

Arquitectura

Cliente MCP (Claude Code / Claude.ai)
        │
        │  HTTPS (Bearer JWT)
        ▼
  GOC MCP Server  ──────────────────────►  goc_api (Express + Prisma)
  (Este servidor)                              │
        │                                      ▼
        │  OAuth 2.0                      PostgreSQL
        ▼
  Página de login
  (browser del usuario)

Transporte: HTTP Streamable (especificación MCP 2025)
Autenticación: OAuth 2.0 Authorization Code Flow
Modo: Stateless — cada request es independiente
Acceso: Exclusivo para administradores activos. Consultas y edición de permisos mediante la API GOC.

Herramientas disponibles

Empleados

Asistencias

Pedidos

Obras

Permisos — solo administradores

Ejemplos de argumentos:

{"query":{"scope":"modules","page":1,"limit":25}}

{"query":{"scope":"roles","userIds":[7,8],"moduleIds":[10],"action":"edit"}}

{"query":{"scope":"users","moduleIds":[10],"action":"edit","page":1,"limit":25}}

{"query":{"scope":"project","projectModule":"tools","projectId":12,"roleIds":[3]}}

{"edit":{"scope":"roles","roleId":3,"permissions":[{"moduleId":10,"edit":true}]}}

{"edit":{"scope":"project","projectId":12,"projectModule":"tools","userIds":[7,8],"permissionType":"edit"}}

{"edit":{"scope":"project","projectId":12,"projectModule":"orders","roleIds":[3],"permissionType":null}}

• Los IDs son ejemplos: consultar primero los valores reales. Las respuestas paginadas incluyen hasMore.

• Los cambios generales de un rol afectan a todos sus usuarios. Las acciones y módulos omitidos se conservan.

• Las acciones no admitidas por un módulo se desactivan; se aplican las dependencias de lectura/escritura y estados de la web. El resultado incluye valores anteriores y finales.

• Los ámbitos por obra existentes son orders, tools y employees; los niveles son read y edit. null revoca la asignación.

• Al seleccionar roles para una obra se resuelven sus usuarios actuales; no se crea herencia para usuarios futuros. Se omiten usuarios inactivos al asignar, pero se permite revocarles acceso. Máximo 500 destinatarios por edición.

• Retirar permisos de empleados conserva las relaciones de la obra. Retirar una asignación no elimina los accesos especiales de administrador ni otros permisos generales.

• Las ediciones se ejecutan en transacciones serializables. Ante un conflicto concurrente o fallo, consultar nuevamente el estado antes de reintentar.

Despliegue y base de datos

Desplegar primero el backend y después el MCP. Esta funcionalidad reutiliza las tablas existentes y no necesita migraciones ni registros iniciales. No se realizan cambios manuales en producción. Cualquier cambio futuro de esquema o datos iniciales debe versionarse mediante migraciones y ejecutarse por el pipeline al hacer merge a main. Las asignaciones solicitadas por administradores son operaciones funcionales de la API, no migraciones por cada edición.

Flujo de autenticación

El backend verifica firma y expiración del JWT y consulta el rol y estado actuales del usuario. El MCP comprueba acceso administrativo al iniciar sesión, intercambiar códigos, renovar tokens y en cada petición a /mcp, antes de exponer herramientas. Las herramientas de permisos y sus endpoints también exigen esta validación. Un cambio de rol o desactivación impide las peticiones posteriores aunque el JWT no haya vencido.

El servidor implementa OAuth 2.0 Authorization Code Flow. Los clientes MCP compatibles (Claude Code, Claude.ai) abren el browser automáticamente al primer uso.

1. Usuario agrega el MCP con solo la URL
2. Claude Code abre el browser → página de login GOC
3. Usuario inicia sesión con sus credenciales GOC
4. El MCP genera un auth_code temporal (TTL 5 min)
5. Claude Code lo intercambia por el JWT de GOC
6. El JWT se envía como Bearer en cada llamada futura

Requisitos

• Node.js 20+

• goc_api corriendo y accesible

• Cuenta GOC activa con rol Administrador

• Backend con /permissions/admin-access, POST /permissions/query y PATCH /permissions/manage desplegados

Instalación

git clone git@github.com:Lalopa/goc_mcp.git
cd goc_mcp
npm install
cp .env.example .env
# Editar .env con los valores correctos

Variables de entorno

GOC_API_URL=https://api.goc.com/api/v2   # URL del backend GOC
MCP_BASE_URL=https://mcp.goc.com         # URL pública de este servidor
PORT=3002

Ver .env.example para referencia.

Desarrollo local

npm run dev      # tsx watch — recarga automática

El servidor queda en http://localhost:3002.

Para probar el flujo OAuth localmente:

1. Abrir en browser: http://localhost:3002/oauth/authorize?redirect_uri=http://localhost:9999/callback&state=test

2. Iniciar sesión con credenciales GOC

3. Capturar el code de la URL de callback

4. Intercambiar: POST /oauth/token con grant_type=authorization_code

Producción (EC2 + pm2 + nginx)

npm run build                                    # Compila TypeScript → dist/
pm2 start dist/index.js --name goc-mcp          # Registrar en pm2
pm2 save                                         # Persistir en reinicios

Ver docs de despliegue para la configuración completa de nginx.

Configuración en Claude Code

{
  "mcpServers": {
    "goc": {
      "type": "http",
      "url": "https://mcp.goc.com/mcp"
    }
  }
}

Al primer uso, Claude Code detecta OAuth y abre el browser automáticamente.

Estructura del proyecto

goc_mcp/
├── src/
│   ├── index.ts          # Entry point — Express + rutas MCP
│   ├── api-client.ts     # Cliente HTTP hacia goc_api
│   ├── mcp-server.ts     # Factory del MCP server con tools registradas
│   ├── oauth/            # Implementación OAuth 2.0
│   │   ├── routes.ts     # Endpoints OAuth
│   │   ├── store.ts      # Store en memoria de auth codes
│   │   └── login-page.ts # Página HTML de login
│   └── tools/            # Herramientas MCP por dominio
│       ├── employees.ts
│       ├── attendance.ts
│       ├── orders.ts
│       └── projects.ts
├── .env.example
├── package.json
└── tsconfig.json

Endpoints del servidor