Servicialo Protocol Spec v0.9.0
Referencia autocontenida para desarrolladores y agentes IA que evalúan o implementan el protocolo. 8 dimensiones, 9 estados, 34 herramientas.
Self-contained reference for developers and AI agents evaluating or implementing the protocol. 8 dimensions, 9 states, 34 tools.
Las 8 dimensiones / The 8 Dimensions
Todo servicio se modela a través de 8 dimensiones canónicas, universales para todas las verticales.
Every service is modeled across 8 canonical dimensions, universal across verticals.
| # | Dimensión / Dimension | Qué captura / What it captures | Campos ejemplo / Example fields |
|---|---|---|---|
| 1 | Identidad (Qué) Identity (What) | La actividad o resultado entregado The activity or outcome being delivered | type, vertical, name, duration_minutes, requirements |
| 2 | Proveedor (Quién entrega) Provider (Who Delivers) | Profesional o entidad que entrega el servicio Professional or entity delivering the service | provider.id, credentials, trust_score, organization_id |
| 3 | Cliente (Quién recibe) Client (Who Receives) | Beneficiario del servicio; el pagador se separa explícitamente Beneficiary of the service; payer is explicitly separated | client.id, client.payer_id |
| 4 | Agenda (Cuándo) Schedule (When) | Ventana temporal del servicio Temporal window for the service | requested_at, scheduled_for, duration_expected |
| 5 | Ubicación (Dónde) Location (Where) | Ubicación física o virtual; puede referenciar un Recurso Physical or virtual location; may reference a Resource entity | type (in_person/remote), address, resource_id, coordinates |
| 6 | Ciclo de vida (Estados) Lifecycle (States) | Posición actual en el ciclo de 9 estados Current position in the 9-state lifecycle | current_state, transitions[], exceptions[] |
| 7 | Evidencia (Prueba) Evidence (Proof) | Cómo el servicio prueba que ocurrió How the service proves it occurred | checkin, checkout, duration_actual, evidence[] |
| 8 | Facturación (Pago) Billing (Payment) | Liquidación financiera, independiente del ciclo de vida Financial settlement, independent from lifecycle | amount, payer, status, payment_id, tax_document |
Un Recurso (espacio físico/equipamiento) es una entidad de primera clase con capacity, buffer_minutes, su propio calendario de disponibilidad y lista de equipos. Opcional — prácticas individuales funcionan sin él.
A Resource (physical space/equipment) is a first-class entity with capacity, buffer_minutes, its own availability schedule, and equipment list. Optional — solo practices work without it.
Los 9 estados del ciclo de vida / The 9 Lifecycle States
Requested → Scheduled → Confirmed → In Progress → Completed → Documented → Invoiced → Collected → Verified| # | Estado / State | Disparador / Trigger | Notas / Notes |
|---|---|---|---|
| 1 | requested | Cliente/agente envía solicitud Client/agent submits request | Punto de entrada Entry point |
| 2 | scheduled | Sistema encuentra disponibilidad (proveedor, opcionalmente recurso) System matches availability (provider, optionally resource) | Compromiso triple si hay recurso asignado Three-way commitment if resource assigned |
| 3 | confirmed | Ambas partes confirman Both parties acknowledge | Proveedor + cliente confirman Provider + client confirm |
| 4 | in_progress | Check-in detectado (GPS + timestamp) Check-in detected (GPS + timestamp) | Comienza la entrega Delivery begins |
| 5 | completed | Proveedor marca entrega completa Provider marks delivery complete | Duración auto-calculada desde checkin/checkout Duration auto-calculated from checkin/checkout |
| 6 | documented | Nota clínica, reporte o evidencia archivada Clinical note, report, or evidence filed | Schema de evidencia por vertical aplicado Vertical-specific evidence schema applied |
| 7 | invoiced | Documento tributario emitido Tax document emitted | Dimensión de facturación actualizada Billing dimension updated |
| 8 | collected | Pago recibido y confirmado Payment received and confirmed | Solo sesiones collected cuentan para liquidación Only collected sessions count toward payroll |
| 9 | verified | Cliente confirma OK, o ventana de silencio expira (auto-verify) Client confirms OK, or silence window expires (auto-verify) | Estado terminal del camino feliz Terminal happy-path state |
Reglas: Los estados son estrictamente ordenados — no se pueden saltar. Cada transición registra from, to, at, by, method (auto/manual/agent), y metadata. Cuando method = agent, mandate_id es obligatorio.
Rules: States are strictly ordered — no skipping. Each transition records from, to, at, by, method (auto/manual/agent), and metadata. When method = agent, mandate_id is required.
Las dos entidades / The Two Entities
Servicio (Unidad atómica) / Service (Atomic Unit)
La unidad atómica de entrega de servicios profesionales. Modelada en las 8 dimensiones. Puede existir de forma independiente o dentro de una Orden de Servicio.
The atomic unit of professional service delivery. Modeled across the 8 dimensions. May exist standalone or within a Service Order.
Orden de Servicio (Acuerdo comercial) / Service Order (Commercial Agreement)
Un acuerdo bilateral para entregar un conjunto de servicios bajo términos comerciales definidos.
A bilateral agreement to deliver a set of services under defined commercial terms.
| Eje / Axis | Qué define / What it defines |
|---|---|
| Alcance / Scope | Tipos de servicio autorizados, límites de cantidad/horas, condición de expiración / Authorized service types, quantity/hours limits, expiry condition |
| Precio / Pricing | Modelo (fijo / tiempo y materiales / tarifa / mixto), moneda, tarifas / Model (fixed / time & materials / rate card / mixed), currency, rates |
| Calendario de pagos / Payment schedule | Cuándo se mueve el dinero (anticipado / hito / periódico / contra entrega / personalizado) / When money moves (upfront / milestone / periodic / on delivery / custom) |
Ciclo de vida de la Orden de Servicio / Service Order lifecycle:
draft → proposed → negotiating → active → paused → completed | cancelledUna cotización ES una Orden de Servicio en estado draft o proposed — no existe un objeto de cotización separado.A quote IS a Service Order in draft or proposed state — no separate quote object.
Libro mayor computado / Computed Ledger (read-only, on the Service Order)
| Campo / Field | Significado / Meaning |
|---|---|
services_verified | Cantidad de servicios en estado verified Count of services in verified state |
hours_consumed | Total de horas en servicios verificados Total hours across verified services |
amount_consumed | Valor consumido a tarifas del modelo de precio Value consumed at pricing model rates |
amount_billed | Total facturado a la fecha Total invoiced to date |
amount_collected | Total de pagos recibidos Total payments received |
amount_remaining | Alcance autorizado aún no consumido Authorized scope not yet consumed |
Relación (Principio 6): Orden de Servicio = lo acordado. Servicio atómico = lo entregado. El libro mayor conecta ambos.Relationship (Principle 6): Service Order = what was agreed. Atomic Service = what was delivered. The ledger bridges both.
Flujos de excepción / Exception Flows
6 flujos de excepción de primera clase. Cualquiera puede redirigir fuera del camino feliz.
6 first-class exception flows. Any of these may redirect out of the happy path.
| Excepción / Exception | Disparador / Trigger | Desde / From | Hacia / To | Regla clave / Key rule |
|---|---|---|---|---|
| No-show del cliente Client no-show | Cliente ausente pasado el periodo de gracia Client absent past grace period | confirmed | cancelled (no_show) | Cobrar penalidad según política; liberar slot del proveedor Charge penalty per policy; free provider slot |
| No-show del proveedor Provider no-show | Proveedor ausente o cancelación de último minuto Provider absent or last-minute cancel | confirmed | reassigning → scheduled | Buscar reemplazo automáticamente; notificar cliente; marcar proveedor Auto-find replacement; notify client; flag provider |
| Cancelación Cancellation | Cualquier parte cancela pre-entrega Either party cancels pre-delivery | Any pre-delivery | cancelled | Aplicar política de cancelación según tiempo restante Apply cancellation policy by time remaining |
| Disputa de calidad Quality dispute | Cliente disputa dentro de ventana de disputa Client disputes within dispute window | completed | disputed | Congelar cobro; solicitar evidencia adicional; resolver a verified o cancelled Freeze charge; request additional evidence; resolve to verified or cancelled |
| Reprogramación Rescheduling | Cualquier parte necesita horario diferente Either party needs different time | scheduled/confirmed | rescheduling → scheduled | Mantener mismo proveedor si es posible; manejar conflictos de recurso Maintain same provider when possible; handle resource conflicts |
| Entrega parcial Partial delivery | Servicio no puede completarse en su totalidad Service cannot be completed in full | in_progress | partial | Documentar lo entregado; ajustar factura proporcionalmente Document what was delivered; adjust invoice proportionally |
Herramientas MCP por fase / MCP Tools by Phase
34 herramientas implementadas en @servicialo/mcp-server v0.8.0. 9 públicas (sin auth) + 25 autenticadas (API key + org ID).
34 tools implemented in @servicialo/mcp-server v0.8.0. 9 public (no auth) + 25 authenticated (API key + org ID).
Fase 0 / Phase 0 — Resoluci\u00f3n DNS / DNS Resolution (3 public tools)
| Tool | Descripción / Description | Auth |
|---|---|---|
resolve.lookup | Resolver orgSlug → endpoint + nivel de confianza / Resolve orgSlug → endpoint + trust level | No |
resolve.search | Buscar resolver global por país y vertical / Search global resolver by country and vertical | No |
trust.get_score | Puntaje de confianza (0–100), nivel, última actividad / Trust score (0–100), level, last activity | No |
Fase 1 / Phase 1 — Descubrimiento / Discovery (6 public tools)
| Tool | Descripción / Description | Auth |
|---|---|---|
registry.search | Buscar organizaciones por vertical, ubicación, país / Search organizations by vertical, location, country | No |
registry.get_organization | Detalles públicos: servicios, proveedores, config de reserva / Public details: services, providers, booking config | No |
registry.manifest | Manifiesto del servidor: capacidades, versión, metadata / Server manifest: capabilities, protocol version, metadata | No |
scheduling.check_availability | Slots disponibles (3 variables: proveedor ∧ cliente ∧ recurso) / Available slots (3-variable: provider ∧ client ∧ resource) | No |
services.list | Catálogo público de servicios de una organización / Public service catalog of an organization | No |
a2a.get_agent_card | Agent Card A2A para descubrimiento inter-agente / A2A Agent Card for inter-agent discovery | No |
Fase 2 / Phase 2 — Entender / Understand (2 tools)
| Tool | Descripción / Description | Scopes |
|---|---|---|
service.get | Las 8 dimensiones completas de un servicio / Full 8 dimensions of a service | service:read |
contract.get | Términos del contrato: evidencia requerida, política de cancelación, ventana de disputa / Contract terms: evidence required, cancellation policy, dispute window | service:read order:read |
Fase 3 / Phase 3 — Comprometer / Commit (3 tools)
| Tool | Descripción / Description | Scopes |
|---|---|---|
clients.get_or_create | Buscar o crear cliente por email/teléfono / Find or create client by email/phone | patient:write |
scheduling.book | Reservar sesión → requested. resource_id opcional / Book session → requested. Optional resource_id | schedule:write |
scheduling.confirm | Confirmar reserva → confirmed / Confirm booking → confirmed | schedule:write |
Fase 4 / Phase 4 — Ciclo de vida / Lifecycle (4 tools)
| Tool | Descripción / Description | Scopes |
|---|---|---|
lifecycle.get_state | Estado actual, transiciones disponibles, historial / Current state, available transitions, history | service:read |
lifecycle.transition | Ejecutar transición de estado con evidencia / Execute state transition with evidence | service:write |
scheduling.reschedule | Reprogramar (política de contrato puede aplicar) / Reschedule (contract policy may apply) | schedule:write |
scheduling.cancel | Cancelar (política de cancelación aplicada) / Cancel (cancellation policy applied) | schedule:write |
Fase 5 / Phase 5 — Verificar entrega / Verify Delivery (3 tools)
| Tool | Descripción / Description | Scopes |
|---|---|---|
delivery.checkin | Check-in: GPS + timestamp → in_progress | evidence:write |
delivery.checkout | Check-out: GPS + timestamp → completed (duración auto-calculada / duration auto-calculated) | evidence:write |
delivery.record_evidence | Registrar evidencia: gps, firma, foto, documento, duración, notas / Record evidence: gps, signature, photo, document, duration, notes | evidence:write |
Fase 6 / Phase 6 — Cerrar / Close (4 tools)
| Tool | Descripción / Description | Scopes |
|---|---|---|
documentation.create | Generar registro de servicio → documented / Generate service record → documented | document:write |
payments.create_sale | Crear cobro → invoiced / Create charge → invoiced | payment:write |
payments.record_payment | Registrar pago recibido / Record payment received | payment:write |
payments.get_status | Estado de pago o saldo del cliente / Payment status or client account balance | payment:read |
Gesti\u00f3n de recursos / Resource Management (6 tools)
| Tool | Descripción / Description | Scopes |
|---|---|---|
resource.list | Listar recursos físicos por organización / List physical resources by organization | resource:read |
resource.get | Detalles del recurso + slots disponibles / Resource details + availability slots | resource:read |
resource.create | Crear recurso (sala, box, equipo) / Create resource (room, box, equipment) | resource:write |
resource.update | Actualizar recurso (patch semantics) / Update resource (patch semantics) | resource:write |
resource.delete | Eliminación lógica (is_active = false) / Soft delete (is_active = false) | resource:write |
resource.get_availability | Disponibilidad por rango de fechas / Availability by date range | resource:read |
Administraci\u00f3n del resolver / Resolver Administration (3 tools)
| Tool | Descripción / Description | Scopes |
|---|---|---|
resolve.register | Registrar org en resolver global / Register org in global resolver | resolve:write |
resolve.update_endpoint | Actualizar endpoints (portabilidad de backend) / Update endpoints (backend portability) | resolve:write |
telemetry.heartbeat | Heartbeat: nodo activo / Heartbeat: node is alive | telemetry:write |
Requisitos mínimos / Minimum Implementation Requirements
Para ser listado como una implementación compatible de Servicialo:
To be listed as a compatible Servicialo implementation:
| # | Requisito / Requirement | Referencia / Reference | Obligatorio / Mandatory |
|---|---|---|---|
| 1 | Modelar servicios usando las 8 dimensiones Model services using the 8 dimensions | §5 | Sí / Yes |
| 2 | Implementar los 9 estados del ciclo de vida Implement the 9 lifecycle states | §6 | Sí / Yes |
| 3 | Manejar al menos 3 flujos de excepción Handle at least 3 exception flows | §7 | Sí / Yes |
| 4 | Exponer una API a la que un servidor MCP pueda conectarse Expose an API that an MCP server can connect to | §13 | Sí / Yes |
| 5 | Modelar Órdenes de Servicio (schema §8) Model Service Orders (§8 schema) | §8 | No |
| 6 | Implementar el Modelo de Agencia Delegada Implement the Delegated Agency Model | §10 | No |
| 7 | Implementar Perfiles de Proveedor Implement Provider Profiles | §12 | No |
| 8 | Contribuir a la Inteligencia de Red Contribute to Network Intelligence | §14 | No |
Superficie de API / API Surface
El servidor MCP se conecta a un backend via adaptador. El backend debe exponer endpoints cubriendo estas operaciones. Las rutas HTTP no son prescritas por el protocolo — cada implementación elige su propia superficie REST.
The MCP server connects to a backend via an adapter. The backend must expose endpoints covering these operations. HTTP routes are not prescribed by the protocol — each implementation chooses its own REST surface.
Descubrimiento / Discovery (público, sin auth / public, no auth)
| Operación / Operation | Input | Output |
|---|---|---|
| Buscar organizaciones / Search organizations | vertical, location, country | Lista de organizaciones / Organization list |
| Obtener detalles / Get organization details | org_id or slug | Perfil público, servicios, proveedores / Public profile, services, providers |
| Obtener manifiesto / Get server manifest | — | Capacidades, versión, metadata / Capabilities, protocol version, org metadata |
| Verificar disponibilidad / Check availability | service_id, provider_id?, resource_id?, date_from, date_to | Slots disponibles con puntaje de confianza / Available time slots with confidence scores |
| Listar servicios / List services | org_id | Catálogo de servicios / Service catalog |
| Obtener agent card A2A / Get A2A agent card | org_id | A2A Agent Card JSON |
Resolución DNS / DNS Resolution (público, sin auth / public, no auth)
| Operación / Operation | Input | Output |
|---|---|---|
| Buscar endpoint de org / Lookup org endpoint | org_slug | URL de endpoint MCP/REST, nivel de confianza / MCP/REST endpoint URL, trust level |
| Buscar en resolver / Search resolver | country, vertical | Organizaciones coincidentes / Matching organizations |
| Obtener puntaje de confianza / Get trust score | org_slug | Puntaje 0–100, nivel, última actividad / Score 0–100, level, last activity |
Operaciones autenticadas / Authenticated operations (API key + org ID)
| Operación / Operation | Input | Output |
|---|---|---|
| Obtener servicio (8 dimensiones) / Get service (8 dimensions) | service_id | Objeto servicio completo / Full service object |
| Obtener contrato / Get contract | service_id or order_id | Términos del contrato / Contract terms |
| Obtener o crear cliente / Get or create client | email or phone, name | Registro de cliente / Client record |
| Reservar sesión / Book session | service_id, provider_id, client_id, datetime, resource_id? | Reserva en estado requested / Booking in requested state |
| Confirmar sesión / Confirm session | booking_id | Reserva en estado confirmed / Booking in confirmed state |
| Obtener estado / Get lifecycle state | session_id | Estado actual + transiciones + historial / Current state + transitions + history |
| Transicionar estado / Transition state | session_id, to_state, evidence? | Estado actualizado / Updated state |
| Reprogramar / Reschedule | session_id, new_datetime | Sesión reprogramada / Rescheduled session |
| Cancelar / Cancel | session_id, reason? | Sesión cancelada / Cancelled session |
| Check-in | session_id, gps, timestamp | Sesión en in_progress / Session in in_progress |
| Check-out | session_id, gps, timestamp | Sesión en completed / Session in completed |
| Registrar evidencia / Record evidence | session_id, type, payload | Evidencia adjunta / Evidence attached |
| Crear documentación / Create documentation | session_id, content | Sesión en documented / Session in documented |
| Crear cobro / Create sale | session_id, amount? | Venta/factura creada / Sale/invoice created |
| Registrar pago / Record payment | sale_id, method, amount | Pago registrado / Payment recorded |
| Estado de pago / Get payment status | sale_id or client_id | Estado de pago / saldo / Payment status / balance |
| CRUD recursos / CRUD resources | resource_id?, fields | Entidad recurso / Resource entity |
| Disponibilidad de recurso / Resource availability | resource_id, date_from, date_to | Slots disponibles / Available slots |
| Registrar en resolver / Register in resolver | org_slug, endpoints | Registro confirmado / Registration confirmed |
| Actualizar endpoint / Update endpoint | org_slug, endpoints | Endpoints actualizados / Endpoints updated |
| Enviar heartbeat / Send heartbeat | org_slug | Heartbeat confirmado / Heartbeat acknowledged |
Autenticación: Todas las operaciones autenticadas requieren X-API-Key + X-Org-Id como headers. Cuando actor.type = agent, un ServiceMandate válido con los scopes apropiados es adicionalmente requerido.
Authentication: All authenticated operations require X-API-Key + X-Org-Id headers. When actor.type = agent, a valid ServiceMandate with appropriate scopes is additionally required.
Esta página refleja la Servicialo Protocol Spec v0.9.0 completa. Para la especificación completa incluyendo JSON Schemas, gobernanza y extensiones por vertical, consulta el repositorio en GitHub.
This page mirrors the full Servicialo Protocol Spec v0.9.0. For the complete protocol specification including JSON Schemas, governance, and vertical-specific extensions, see the GitHub repository.