servicios-mcp

Servidor MCP remoto (Streamable HTTP), de SOLO CONSULTA (nunca escribe ni modifica nada en SAP ni en Cisco), que expone la API de SAP Business One Service Layer, la API de contratos de servicio de Cisco (CCWR) y la API de estado de órdenes de Cisco (CCW) usadas por el proyecto Hermes de Trans Industrias Electrónicas.

Pensado para que un cliente externo (otro Claude, en otra cuenta) pueda agregarlo como conector MCP remoto y consultar los mismos datos sin acceso directo al clúster ni a las credenciales reales de SAP/Cisco.

Tools expuestas

Las once tools son exclusivamente de lectura — no existe en este código ninguna tool que pueda crear, modificar o borrar nada en SAP, CCWR ni CCW.

• sap_query(entity, select, filter, orderby, top, skip) — GET genérico contra una colección OData de SAP B1 Service Layer (Orders, DeliveryNotes, PurchaseOrders, PurchaseDeliveryNotes, BusinessPartners, Items, etc.).

• sap_get_entity(entity, entry_id) — GET completo de un documento por clave primaria (necesario para sub-colecciones anidadas como SerialNumbers, que SAP omite si la consulta usa $select).

• ccwr_search(serial_numbers, contract_numbers, instance_numbers, subscription_ids, web_order_ids, so_mso_numbers, po_mpo_numbers, limit, offset) — búsqueda de contratos de servicio de Cisco (soporte/warranty, API CCWR — legacy). 7 criterios de búsqueda válidos en total (los últimos 4 no figuran en el PDF oficial de Cisco, confirmados contra el schema real).

• ccw_order_status(order_search_key, order_search_value, page, page_size) — estado de órdenes de compra/venta de Cisco (API CCW — Commerce GraphQL). Distinto de ccwr_search: contratos y órdenes son dos APIs de Cisco separadas, con credenciales propias cada una.

• ccwr_suscripcion_orden(subscription_id) — dado un Subscription ID de Cisco (ej. Sub2330047, tal cual aparece en el portal CCW Renewals), encadena ccwr_search (subscription_ids) + ccw_order_status en una sola llamada para traer la orden real asociada. Exige ccwr y ccw habilitados en el token.

• ccw_sub_ids_por_orden(order_search_key, order_search_values, page_size) — dada una lista de hasta 200 órdenes (SALES_ORDER_ID o WEB_ORDER_ID), devuelve solo los Subscription ID reales (formato Sub+número) de cada una, con la línea de la orden (linea, el número tal cual lo muestra el portal CCW, ej. "1.1"), el SKU y la descripción de esa línea — útil cuando una orden tiene más de un Sub ID en líneas distintas. Descarta explícitamente cualquier otro identificador que Cisco deje en el mismo campo (ej. SR..., confirmado que NO es un Sub ID real).

• turecibo_resumen(refresh) / turecibo_activos(sector, cargo, refresh) / turecibo_bajas(desde, hasta, refresh) / turecibo_buscar(query, refresh) — padrón de empleados de TuRecibo (Visma), solo lectura. El roster se arma barriendo /users/search con ~114 prefijos frecuentes (TuRecibo no expone un listado completo) — es una heurística incompleta por diseño, y cada respuesta incluye un campo warning aclarándolo. Activo/baja se decide por el campo ingreso (no por fecha_baja, que puede venir vacío). Cache en disco 2h (TURECIBO_CACHE_FILE, permisos 0600).

• turecibo_licencias(query, tipo, estado) — licencias (vacaciones, mudanza, etc.) de una persona puntual (query obligatorio: CUIL, legajo o nombre — nunca lista licencias de toda la empresa). Lee siempre en vivo del endpoint de licencias, sin cache. Solo lectura.

Regla no negociable, heredada de los skills sap-service-layer, ccwr-contract-admin y order-status de Hermes: el servidor nunca arma un POST/PATCH/DELETE contra una entidad de datos de SAP, CCWR o CCW. Las únicas llamadas POST del código son Login/Logout de sesión SAP y los token endpoints OAuth2 de Cisco — todas de autenticación, ninguna de datos.

Related MCP server: sap-mcp

Autenticación

Authorization: Bearer <token> en cada request. Los tokens se gestionan desde el panel web /admin (ver abajo) — cada persona tiene su propio token, independiente de las credenciales reales de SAP/Cisco, así que se puede revocar el acceso de una persona sin tocar nada más ni redeployar.

Dos formas de usar ese mismo token:

• Directo (Claude Code): --header "Authorization: Bearer <token>".

• OAuth2 (Claude Desktop): el servidor implementa su propio Authorization Server OAuth 2.1 (RFC 8414/9728, DCR RFC 7591, vía el soporte nativo del SDK mcp.server.auth) para que Claude Desktop —que solo sabe hablar OAuth, no un Bearer fijo— pueda agregar el conector pegando solo la URL. El flujo: Claude Desktop se autoregistra como cliente OAuth (POST /register), abre el navegador en /oauth/login, la persona pega ahí su token de siempre, y el access_token que se emite es ese mismo token (revocable desde /admin, sin lógica de expiración/refresh propia). No hay usuarios ni contraseñas nuevas.

Panel /admin — gestión de IPs habilitadas

Además de los tokens, /admin permite agregar/quitar IPs y CIDRs de la whitelist de la propia Route (haproxy.router.openshift.io/ip_whitelist) sin correr oc a mano — el cambio se aplica al toque contra la Route real (capa de red/HAProxy, no se movió el bloqueo a la aplicación). El pod necesita permiso de Kubernetes (RBAC) para leer y editar SOLO esa Route puntual (get/patch, acotado por resourceNames — no puede tocar ningún otro objeto del namespace); ver rbac-ip-whitelist.yaml para el ServiceAccount/Role/RoleBinding que hay que aplicar antes de que esta sección del panel funcione. API REST: GET /admin/api/ips, POST /admin/api/ips ({"cidr": "...", "label": "..."}), DELETE /admin/api/ips?cidr=....

Panel /admin — gestión de tokens

GET /admin sirve una página HTML+JS (sin dependencias nuevas) protegida con un login web propio (GET/POST /admin/login, cookie de sesión admin_session httpOnly/Secure, TTL 12h, en memoria del proceso — reemplazó al HTTP Basic Auth original el 2026-08-28; POST /admin/logout hace logout real) validado contra ADMIN_USER/ADMIN_PASSWORD, para generar y revocar tokens de acceso en caliente. Los tokens se persisten en TOKENS_FILE (default /data/tokens.json, pensado para montarse sobre un PVC) — en el primer arranque sobre un archivo inexistente, se siembran automáticamente desde la variable de entorno legacy MCP_ACCESS_TOKENS (token1:etiqueta1,token2:etiqueta2,...), que de ahí en más queda sin efecto real. API REST detrás de la misma sesión de /admin: GET /admin/api/tokens (listar), POST /admin/api/tokens ({"label": "...", "services": ["sap","ccwr","ccw"]} → crea y devuelve el token; services es opcional, si se omite habilita todos), DELETE /admin/api/tokens/{label} (revoca).

Permisos por servicio (qué tools puede usar cada token)

Cada token tiene una lista services (subconjunto de sap, ccwr, ccw) que define a qué tools puede llamar — no es todo o nada. El mapeo es:

Un token que intenta llamar una tool fuera de sus servicios habilitados recibe un error ({"error": "tu token no tiene habilitado el servicio..."}) sin llegar a pegarle a SAP/Cisco, y queda registrado en el audit log como service_forbidden. Se elige al crear el token desde /admin (checkboxes) y se puede cambiar después sin generar un token nuevo, con PATCH /admin/api/tokens/{label}/services ({"services": [...]}) — mismo endpoint que usa la tabla del panel. GET /admin/api/services devuelve el catálogo (id + descripción) que usa el panel para dibujar los checkboxes. Los tokens emitidos antes de este feature (sin services en el JSON) se migran automáticamente al primer arranque con TODOS habilitados — mismo comportamiento que ya tenían, no se corta nada retroactivamente.

Variables de entorno

Correr local

pip install -r requirements.txt
SAP_SL_COMPANY_DB=... SAP_SL_USERNAME=... SAP_SL_PASSWORD=... \
MCP_ACCESS_TOKENS="tok_ejemplo:mi-token" \
python3 src/server.py

Healthcheck sin auth: GET /healthz. Endpoint MCP: POST /mcp.

Despliegue

Corre como Deployment propio en OKD (namespace hermes, componente servicios-mcp — renombrado desde hermes-mcp el 2026-08-14), detrás de una Route pública (servicios-mcp.trans.com.ar) con TLS real, mismo patrón que el resto de los componentes de Hermes en este proyecto (hermes-agent, honcho-api, trilium). Ver el changelog del proyecto Hermes (doc interno, no en este repo) para el detalle de despliegue real.