# @servicialo/mcp-server

**La interfaz MCP a nivel de protocolo para el estándar Servicialo — la capa de destino para servicios humanos en la era de agentes de IA.**
HTTP hizo los documentos direccionables. Servicialo hace los servicios direccionables. MCP y A2A son el transporte. Servicialo es el destino al que los agentes llegan.

Este paquete es la interfaz MCP a nivel de protocolo para **cualquier backend compatible con Servicialo** — no un conector a una plataforma específica. Coordinalo es la implementación de referencia (y el default), pero puedes conectar tu propio backend.

> **Protocolo:** v0.10 (draft) · **Spec:** [servicialo.com/spec](https://servicialo.com/spec) · Este paquete versiona independiente del protocolo (`0.9.x` hasta 1.0).

## Road to 1.0

El protocolo Servicialo entra en **fase de estabilización**. El primer cohort formal de RFCs está **abierto a comentarios** durante una ventana mínima de 4 semanas antes de pasar a Final Comment Period. Hasta 1.0, los releases siguen siendo `0.9.x` patch y cualquier cambio breaking al protocolo requiere su RFC merged y comunicación previa.

- **RFC cohort (PR #13):** [servicialo/mcp-server#13](https://github.com/servicialo/mcp-server/pull/13)
- **Proceso 1.0 / Discusión:** [servicialo/mcp-server#14](https://github.com/servicialo/mcp-server/discussions/14)

### Hitos pendientes hacia 1.0

| Hito | Estado |
|---|---|
| RFC-001 — RFC Process & Deprecation Policy | Draft / Open for Comment |
| RFC-002 — Prepayment & Client Credit Balance | Draft / Open for Comment |
| RFC-003 — Refunds & Credit Notes (Forward-Only Ledger) | Draft / Open for Comment |
| RFC-004 — PII / PHI Classification Framework | Draft / Open for Comment |
| Declaración de Core estable (8 dimensiones · ciclo 6+3 · 6 flujos · 7 principios) con garantías de backwards-compat | Pendiente |
| ≥ 3 implementaciones independientes en producción | En progreso |

## Arquitectura

```
@servicialo/mcp-server  →  interfaz MCP a nivel de protocolo
        ↓ se conecta a cualquier backend compatible con Servicialo
Coordinalo              →  implementación de referencia (default)
Tu implementación       →  trae tu propio backend
```

## El Problema

Los agentes de IA pueden navegar la web, escribir código y mantener conversaciones. Pero pídele a uno que reserve una sesión de kinesiología, verifique que ocurrió, y procese el pago — y se desmorona.

Hoy, cada plataforma es un silo. No hay estándar para:

- **Descubrimiento** — qué prestador, en qué organización, ofrece lo que necesito?
- **Identidad** — en nombre de quién actúa este agente, y qué está autorizado a hacer?
- **Ciclo de vida** — en qué estado está este servicio? Quién confirmó? Quién asistió?
- **Prueba de entrega** — ocurrió realmente la sesión? Por cuánto tiempo? Dónde?
- **Liquidación** — cuánto, a quién, bajo qué términos contractuales?

Sin un protocolo compartido, cada integración es artesanal. Cada conexión agente-plataforma es un API custom. Esto no escala.

## Qué es Servicialo

Servicialo es un **protocolo abierto**, no una plataforma. Define cómo los servicios profesionales se mueven a través de su ciclo de vida — desde el descubrimiento hasta el pago — de una forma que cualquier agente de IA o plataforma puede implementar.

La relación es como HTTP con Apache, o SMTP con Gmail: Servicialo define las reglas, las implementaciones les dan vida.

El protocolo modela cada servicio a través de **8 dimensiones**, **un ciclo de vida 6+3** (6 estados core + 3 financieros opcionales), **6 flujos de excepción** y **7 principios fundamentales** — universales entre verticales (salud, legal, educación, servicios domiciliarios):

```
Solicitado → Agendado → Confirmado → En Curso → Completado → Documentado → Facturado → Cobrado → Verificado
```

Cualquier servicio, en cualquier vertical, sigue esta secuencia. La lógica específica del vertical vive *dentro* de cada estado, pero la máquina de estados es invariante.

## Qué Hace Este MCP Server

Este paquete expone el protocolo Servicialo como 40 herramientas MCP organizadas por las **7 fases** del ciclo de vida de un servicio (0–6, incluyendo el resolver de descubrimiento — análogo a DNS, sobre HTTP), más gestión de recursos, administración del resolver, **inteligencia de red** (`market.*`) y **descubrimiento cold-start** (`registry.list_*` para conocer la taxonomía sin saberla previamente). Un agente no llama endpoints por entidad de base de datos — sigue el flujo natural de coordinar un servicio.

### Fase 0 — Resolución DNS (3 herramientas, sin auth)

| Herramienta | Descripción |
|---|---|
| `resolve.lookup` | Resolver un orgSlug a su endpoint MCP/REST y nivel de confianza (equivalente a DNS lookup) |
| `resolve.search` | Buscar organizaciones registradas por país y vertical en el resolver global |
| `trust.get_score` | Obtener puntaje de confianza de una organización (score 0-100, nivel, última actividad) |

### Fase 1 — Descubrimiento (6 herramientas, sin auth)

| Herramienta | Descripción |
|---|---|
| `registry.search` | Buscar organizaciones por vertical, ubicación, país |
| `registry.get_organization` | Obtener detalles públicos: servicios, prestadores, configuración de reservas |
| `registry.manifest` | Obtener manifiesto del servidor: capacidades, versión del protocolo, metadata de organización |
| `scheduling.check_availability` | Consultar disponibilidad (3 variables: prestador ∧ cliente ∧ recurso) |
| `services.list` | Listar el catálogo público de servicios de una organización |
| `a2a.get_agent_card` | Obtener la Agent Card A2A de una organización para descubrimiento inter-agente |

### Fase 2 — Entender (2 herramientas)

| Herramienta | Descripción | Scopes |
|---|---|---|
| `service.get` | Obtener las 8 dimensiones de un servicio | `service:read` |
| `contract.get` | Obtener términos del contrato: evidencia requerida, política de cancelación, ventana de disputa | `service:read` `order:read` |

### Fase 3 — Comprometer (3 herramientas)

| Herramienta | Descripción | Scopes |
|---|---|---|
| `clients.get_or_create` | Resolver identidad del cliente por email/teléfono — buscar o crear en una sola llamada | `patient:write` |
| `scheduling.book` | Reservar sesión → estado `solicitado`. `resource_id` opcional para recursos físicos | `schedule:write` |
| `scheduling.confirm` | Confirmar sesión reservada → estado `confirmado` | `schedule:write` |

### Fase 4 — Ciclo de Vida (4 herramientas)

| Herramienta | Descripción | Scopes |
|---|---|---|
| `lifecycle.get_state` | Obtener estado actual, transiciones disponibles e historial | `service:read` |
| `lifecycle.transition` | Ejecutar transición de estado con evidencia | `service:write` |
| `scheduling.reschedule` | Reagendar a nueva fecha/hora (política contractual puede aplicar) | `schedule:write` |
| `scheduling.cancel` | Cancelar sesión (se aplica política de cancelación del contrato) | `schedule:write` |

### Fase 5 — Verificar Entrega (3 herramientas)

| Herramienta | Descripción | Scopes |
|---|---|---|
| `delivery.checkin` | Check-in con GPS + timestamp → estado `en_curso` | `evidence:write` |
| `delivery.checkout` | Check-out con GPS + timestamp → estado `entregado` (duración auto-calculada) | `evidence:write` |
| `delivery.record_evidence` | Registrar evidencia: `gps`, `firma`, `foto`, `documento`, `duración`, `notas` | `evidence:write` |

### Fase 6 — Cerrar (4 herramientas)

| Herramienta | Descripción | Scopes |
|---|---|---|
| `documentation.create` | Generar registro del servicio (nota clínica, informe de inspección, etc.) → estado `documentado` | `document:write` |
| `payments.create_sale` | Crear cargo por servicio documentado → estado `cobrado` | `payment:write` |
| `payments.record_payment` | Registrar pago recibido contra una venta | `payment:write` |
| `payments.get_status` | Obtener estado de pago de una venta o saldo de cuenta del cliente | `payment:read` |

### Gestión de Recursos (6 herramientas)

| Herramienta | Descripción | Scopes |
|---|---|---|
| `resource.list` | Listar recursos físicos de una organización | `resource:read` |
| `resource.get` | Obtener detalles de un recurso con sus slots de disponibilidad | `resource:read` |
| `resource.create` | Crear un nuevo recurso físico (sala, box, equipamiento) | `resource:write` |
| `resource.update` | Actualizar recurso (patch semántico) | `resource:write` |
| `resource.delete` | Desactivar recurso (soft delete: `is_active = false`) | `resource:write` |
| `resource.get_availability` | Consultar disponibilidad de un recurso por rango de fechas | `resource:read` |

### Administración del Resolver (3 herramientas)

| Herramienta | Descripción | Scopes |
|---|---|---|
| `resolve.register` | Registrar organización en el resolver global con endpoints MCP/REST | `resolve:write` |
| `resolve.update_endpoint` | Actualizar endpoints registrados (portabilidad entre backends) | `resolve:write` |
| `telemetry.heartbeat` | Enviar heartbeat al resolver indicando que el nodo está activo | `telemetry:write` |

### Inteligencia de Red (2 herramientas, sin auth)

Benchmarks de mercado anonimizados sobre la telemetría operacional contribuida por los nodos. Política **contribuir-para-acceder** (k-anonimato ≥ 5):

| Herramienta | Descripción |
|---|---|
| `market.list_segments` | Listar segmentos `(event_type × vertical × region)` con datos disponibles (filtra por k-anon ≥ 5 distintos contribuidores) |
| `market.get_benchmark` | Obtener la distribución de buckets de un segmento (p. ej. share de cada `price_band` para `payment_settled` en `health/CL`). Tier 0/1 ven datos con 90 días de delay; tier 2 (≥ 50 eventos en 30 días) ven real-time |

### Discovery de Taxonomía (3 herramientas, sin auth)

Cold-start: el agente no necesita conocer la taxonomía del protocolo de antemano. Empezar acá si llega sin contexto:

| Herramienta | Descripción |
|---|---|
| `registry.list_verticals` | Verticals presentes en la red (declarados + observados en telemetría 30d) |
| `registry.list_regions` | Países/regiones ISO 3166-1 alpha-2 con actividad en la red |
| `registry.list_event_types` | Catálogo de los 4 tipos de eventos de telemetría operacional + sus `payload_fields` |

### Documentación (1 herramienta, sin auth)

| Herramienta | Descripción |
|---|---|
| `docs.quickstart` | Obtener los 5 pasos del quickstart como JSON estructurado — onboarding de agentes sin contexto previo |

## Quickstart — 5 pasos para estar en la red

### Paso 1. Instalar el servidor MCP

```bash
npx -y @servicialo/mcp-server
```

Modo descubrimiento — 15 herramientas públicas, sin credenciales. Pruébalo de inmediato:

```json
{
  "tool": "registry.search",
  "arguments": { "vertical": "kinesiologia", "location": "santiago" }
}
```

### Paso 2. Crear tu organización

Registra tu organización en [coordinalo.com/signup](https://coordinalo.com/signup). Coordinalo es la implementación de referencia del protocolo Servicialo.

### Paso 3. Obtener credenciales MCP

En Coordinalo: **Settings → Servicialo → Generar credenciales MCP**. Obtendrás dos valores:

- `SERVICIALO_ORG_ID` — slug de tu organización (ej: `clinica-dental-sur`)
- `SERVICIALO_API_KEY` — bearer token para autenticación

### Paso 4. Configurar el cliente MCP

Agregar a la configuración de Claude Desktop, Cursor o cualquier cliente MCP:

```json
{
  "mcpServers": {
    "servicialo": {
      "command": "npx",
      "args": ["-y", "@servicialo/mcp-server"],
      "env": {
        "SERVICIALO_API_KEY": "<tu_api_key>",
        "SERVICIALO_ORG_ID": "<tu_org_slug>"
      }
    }
  }
}
```

Omitir el bloque `env` para modo solo-descubrimiento (15 herramientas públicas).

### Paso 5. Publicar en la red Servicialo

En Coordinalo: **Settings → Servicialo → Publicar**. Tu organización aparece en [servicialo.com/network](https://servicialo.com/network) y es descubrible por otros agentes.

> **Tip:** Un agente puede obtener estos 5 pasos como JSON estructurado llamando la herramienta `docs.quickstart`.

## Red / Network

La red Servicialo es el registro global de organizaciones que implementan el protocolo. Cada nodo autenticado envía un heartbeat periódico, y cualquier agente puede descubrir organizaciones por país, vertical y puntaje de confianza.

- **Explorar la red:** [servicialo.com/network](https://servicialo.com/network)
- **Buscar por vertical:** `registry.search({ vertical: "kinesiologia", country: "cl" })`
- **Resolver un org:** `resolve.lookup({ org_slug: "clinica-dental-sur" })`

## Credenciales

### Esenciales

| Variable | Requerida | Default | Descripción |
|---|---|---|---|
| `SERVICIALO_API_KEY` | No | — | Bearer token. Habilita modo autenticado (25 tools adicionales = 40 total) |
| `SERVICIALO_ORG_ID` | No | — | Slug de organización. Habilita modo autenticado |
| `SERVICIALO_BASE_URL` | No | `http://localhost:3000` | Endpoint del API de la plataforma compatible con Servicialo |
| `SERVICIALO_ADAPTER` | No | `coordinalo` | Adapter de backend: `coordinalo` o `http` |
| `SERVICIALO_TELEMETRY` | No | `true` | Setear a `false` para desactivar telemetría anónima del nodo (heartbeat) |

`SERVICIALO_API_KEY` y `SERVICIALO_ORG_ID` deben configurarse juntas. Si solo una está presente, el servidor cae a modo descubrimiento con un warning.

### Telemetría operacional + benchmarks (opcional)

Estas variables habilitan que tu nodo contribuya eventos anonimizados a los benchmarks de la red y acceda a datos en tiempo real (tier 2). Ver [docs/telemetry-operational.md](https://github.com/servicialo/mcp-server/blob/main/docs/telemetry-operational.md):

| Variable | Requerida | Default | Descripción |
|---|---|---|---|
| `SERVICIALO_VERTICAL` | No | `unspecified` | Tu vertical (e.g. `health`, `legal`, `home`). Necesario para que los eventos se agreguen al segmento correcto |
| `SERVICIALO_REGION` | No | `CL` | ISO 3166-1 alpha-2 del país operativo. Los eventos se etiquetan con esto |
| `SERVICIALO_NODE_TOKEN` | No | — | `ownership_token` de tu nodo en el registry. Se envía como header `X-Servicialo-Node-Token` en los calls `market.*` para identificar tu tier (incluye tier 2 = real-time access) |
| `SERVICIALO_OPERATIONAL_TELEMETRY` | No | `true` | Setear a `false` para desactivar la emisión automática de eventos operacionales (booking_created, service_completed, dispute_opened, payment_settled) |
| `SERVICIALO_PROTOCOL_VERSION` | No | `0.9` | Versión del protocolo declarada en los eventos emitidos |
| `SERVICIALO_TELEMETRY_BASE_URL` | No | `https://servicialo.com` | Endpoint receptor de telemetría operacional (sólo cambiar para testing) |

> **Cómo se relaciona con tiers de benchmarks:** un nodo que emite ≥ 50 eventos operacionales en 30 días automáticamente alcanza tier 2 y `market.get_benchmark` devuelve datos en tiempo real (en lugar del default tier 0/1 con 90 días de delay). Política completa: [GOVERNANCE.md#contribute-to-access-policy-v01](https://github.com/servicialo/mcp-server/blob/main/GOVERNANCE.md#contribute-to-access-policy-v01).

Las credenciales se obtienen en [coordinalo.com](https://coordinalo.com) → Settings → Servicialo → Generar credenciales MCP.

## Conectar una implementación propia

Este MCP server soporta cualquier backend compatible con Servicialo a través de la capa de adaptadores pluggable. Dos adaptadores están incluidos:

- **`coordinalo`** (default) — se conecta a un backend Coordinalo/Digitalo con rutas org-scoped bajo `/api/organizations/{orgId}`.
- **`http`** — se conecta a cualquier implementación que exponga los endpoints canónicos de `HTTP_PROFILE.md` bajo `/v1/*`.

### 3 pasos para conectar tu implementación

**Paso 1.** Implementar los endpoints REST definidos en [`HTTP_PROFILE.md`](../../HTTP_PROFILE.md) en tu plataforma.

**Paso 2.** Configurar el MCP server para usar el adaptador HTTP:

```bash
SERVICIALO_ADAPTER=http \
SERVICIALO_BASE_URL=https://tu-plataforma.com \
SERVICIALO_API_KEY=tu_key \
npx -y @servicialo/mcp-server
```

**Paso 3.** Agregar a la configuración de tu cliente MCP:

```json
{
  "mcpServers": {
    "servicialo": {
      "command": "npx",
      "args": ["-y", "@servicialo/mcp-server"],
      "env": {
        "SERVICIALO_ADAPTER": "http",
        "SERVICIALO_BASE_URL": "https://tu-plataforma.com",
        "SERVICIALO_API_KEY": "tu_api_key",
        "SERVICIALO_ORG_ID": "tu_org_id"
      }
    }
  }
}
```

El adaptador HTTP traduce las rutas internas a endpoints canónicos `/v1/*` y envía el contexto de organización via el header `X-Servicialo-Org`. Consulta `HTTP_PROFILE.md` para el contrato REST completo.

## Modelo de Agencia Delegada

El protocolo trata a los agentes de IA como actores de primera clase — pero nunca confía en ellos implícitamente. Cada acción de agente requiere un **ServiceMandate**: una delegación explícita de capacidad de un humano principal a un agente.

### Cómo funciona

1. Un humano (profesional, paciente u organización) emite un mandato a un agente
2. El mandato especifica **para quién** actúa el agente, **qué** puede hacer (scopes), y **por cuánto tiempo**
3. En cada tool call, el MCP server valida el mandato contra 8 checks antes de ejecutar
4. Cada acción produce una entrada de auditoría — éxito o fallo

### Ejemplo de mandato

```json
{
  "mandate_id": "550e8400-e29b-41d4-a716-446655440000",
  "principal_id": "dra_barbara",
  "principal_type": "professional",
  "agent_id": "agent_booking_bot",
  "agent_name": "Asistente de Agendamiento",
  "acting_for": "professional",
  "context": "org:clinica-kinesia",
  "scopes": ["schedule:read", "schedule:write", "patient:write"],
  "constraints": {
    "max_actions_per_day": 50,
    "allowed_hours": {
      "start": "08:00",
      "end": "20:00",
      "timezone": "America/Santiago"
    },
    "require_confirmation_above": {
      "amount": 100000,
      "currency": "CLP"
    }
  },
  "issued_at": "2026-03-01T00:00:00Z",
  "expires_at": "2026-06-01T00:00:00Z",
  "status": "active"
}
```

### Uso de mandatos en tool calls

Cuando `actor.type` es `"agent"`, incluir el `mandate_id`:

```json
{
  "tool": "scheduling.book",
  "arguments": {
    "service_id": "srv_123",
    "provider_id": "prov_111",
    "client_id": "cli_789",
    "starts_at": "2026-03-03T10:00:00",
    "actor": {
      "type": "agent",
      "id": "agent_booking_bot",
      "mandate_id": "550e8400-e29b-41d4-a716-446655440000"
    }
  }
}
```

### Los 8 checks de validación

Cada tool call de un agente se valida contra:

| # | Check | Qué previene |
|---|---|---|
| 1 | **Estado** — mandato debe ser `active` | Uso de mandatos revocados o expirados |
| 2 | **Validez temporal** — `issued_at ≤ now < expires_at` | Ataques basados en tiempo |
| 3 | **Identidad del agente** — `mandate.agent_id === agente solicitante` | Suplantación de agente |
| 4 | **Cobertura de scopes** — scopes del mandato cubren los requisitos de la herramienta | Escalación de privilegios |
| 5 | **Contexto** — contexto del mandato coincide con la solicitud | Acceso cross-org a datos |
| 6 | **Conflicto de interés** — agente no puede actuar para ambas partes | Violaciones de doble agencia |
| 7 | **Restricciones** — horarios permitidos, límites diarios, umbrales financieros | Agentes sobre-autónomos |
| 8 | **Auditoría** — cada acción registrada con inputs sanitizados | No repudio |

Actores no-agente (`client`, `provider`, `organization`) no pasan por validación de mandato.

## Descubrimiento de Prestadores

Los agentes pueden buscar en el registro y hacer matching de prestadores con las necesidades de un paciente usando consultas estructuradas.

### Buscar en el registro

```json
{
  "tool": "registry.search",
  "arguments": {
    "vertical": "kinesiologia",
    "location": "santiago",
    "country": "cl"
  }
}
```

Retorna organizaciones que coinciden con sus servicios y prestadores.

### Consultar disponibilidad

```json
{
  "tool": "scheduling.check_availability",
  "arguments": {
    "org_slug": "clinica-kinesia",
    "service_id": "srv_rehab_pelvica",
    "provider_id": "prov_111",
    "date_from": "2026-03-10",
    "date_to": "2026-03-14"
  }
}
```

El scheduler de 3 variables verifica disponibilidad de prestador, cliente y recurso físico simultáneamente.

### Ejemplo de punta a punta

```
1. registry.search({ vertical: "kinesiologia", location: "santiago" })
   → encuentra org "clinica-kinesia"

2. services.list({ org_slug: "clinica-kinesia" })
   → lista servicios disponibles

3. scheduling.check_availability({ org_slug: "clinica-kinesia", date_from: "2026-03-10", date_to: "2026-03-14" })
   → retorna slots disponibles

4. contract.get({ service_id: "srv_123", org_id: "org_456" })
   → cancelación: 0% si >24h, 50% si 2-24h, 100% si <2h
   → evidencia requerida: check_in + check_out + registro_clinico

5. clients.get_or_create({ email: "maria@mail.com", name: "Maria", last_name: "Lopez" })
   → client_id: "cli_789"

6. scheduling.book({ service_id: "srv_123", provider_id: "prov_111", client_id: "cli_789", starts_at: "2026-03-12T10:00:00" })
   → session_id: "ses_001", estado: "solicitado"

7. scheduling.confirm({ session_id: "ses_001" })
   → estado: "confirmado"

8. delivery.checkin({ session_id: "ses_001", location: { lat: -33.45, lng: -70.66 } })
   → estado: "en_curso"

9. delivery.checkout({ session_id: "ses_001", location: { lat: -33.45, lng: -70.66 } })
   → estado: "entregado", duración: 42min

10. documentation.create({ session_id: "ses_001", content: "Sesión de rehabilitación de piso pélvico..." })
    → estado: "documentado"

11. payments.create_sale({ client_id: "cli_789", service_id: "srv_123", unit_price: 35000 })
    → sale_id: "sale_001", estado: "cobrado"

12. lifecycle.transition({ session_id: "ses_001", to_state: "verified" })
    → estado: "verificado" ✓
```

## Especificación del Protocolo

La especificación completa del protocolo Servicialo está disponible en:

- **Repositorio:** [github.com/servicialo/protocol](https://github.com/servicialo/protocol)
- **Sitio web:** [servicialo.com](https://servicialo.com)
- **Versión estable actual:** 0.9
- **JSON Schemas:** [`service.schema.json`](https://github.com/servicialo/protocol/blob/main/schema/service.schema.json), [`service-order.schema.json`](https://github.com/servicialo/protocol/blob/main/schema/service-order.schema.json), [`service-mandate.schema.json`](https://github.com/servicialo/protocol/blob/main/schema/service-mandate.schema.json), [`resolution.schema.json`](https://github.com/servicialo/protocol/blob/main/schema/resolution.schema.json), [`servicialo-config.schema.json`](https://github.com/servicialo/protocol/blob/main/schema/servicialo-config.schema.json)

La spec cubre las 8 dimensiones del servicio, el ciclo de vida 6+3, 6 flujos de excepción, 7 principios fundamentales, la arquitectura de dos entidades (Servicio atómico + Orden de Servicio), el Modelo de Agencia Delegada, resolución DNS, e interoperabilidad A2A.

## Implementación de Referencia

**Digitalo** es la primera implementación en producción del protocolo Servicialo, operando en salud en Chile. Implementa el ciclo de vida completo — desde descubrimiento de prestadores hasta liquidación de pagos — y sirve como terreno de validación para la evolución del protocolo.

Este MCP server se conecta a cualquier backend compatible con Servicialo a través de `SERVICIALO_BASE_URL`. Digitalo es uno de esos backends. El protocolo está diseñado para que cualquier CRM, HIS, o plataforma lo implemente como un nodo soberano.

## Contribuir al Protocolo

Servicialo sigue versionado semántico para la especificación del protocolo:

- **Patch** (0.7.x) — clarificaciones, correcciones de typos, adiciones no-breaking
- **Minor** (0.x.0) — nuevos campos opcionales, nuevas definiciones de herramientas, nuevos flujos de excepción
- **Major** (x.0.0) — cambios breaking a schemas, máquina de estados, o semántica core

### Cómo proponer cambios

1. Abrir un issue describiendo el problema y la solución propuesta
2. Para cambios significativos, escribir un RFC en `spec/` con el número de sección que afecta
3. Los cambios al protocolo requieren al menos una implementación de referencia antes de merge
4. Los cambios a schemas deben incluir JSON Schema actualizado y tipos Zod en el MCP server

### Áreas buscando input activamente

- Requisitos de evidencia específicos por vertical (más allá de salud)
- Soporte multi-idioma para nombres de estados del ciclo de vida
- Federación inter-nodo (cómo dos implementaciones Servicialo interoperan)
- Patrones de Agent SDK para Python y TypeScript

## Telemetría

Al iniciar, el MCP server envía un único POST anónimo a `https://servicialo.com/api/telemetry/instance` con:

```json
{
  "event": "node_initialized",
  "version": "0.9.8",
  "node_id": "a1b2c3d4-...",
  "ts": 1711300000000
}
```

| Campo | Descripción |
|---|---|
| `event` | Siempre `"node_initialized"` |
| `version` | Versión del paquete |
| `node_id` | UUID persistente almacenado en `~/.servicialo/node_id` |
| `ts` | Timestamp en milisegundos |

**Esto es todo lo que se envía.** No se transmite información de organización, API keys, datos de pacientes ni ningún identificador personal. La IP se hashea (SHA-256) en el servidor antes de almacenarse. El ping es fire-and-forget: si falla, el error se descarta silenciosamente y nunca bloquea la operación del servidor.

La primera vez que se ejecuta con telemetría activa, el servidor imprime un aviso en stderr indicando qué se envía y cómo desactivarlo.

### Desactivar telemetría

```bash
SERVICIALO_TELEMETRY=false npx -y @servicialo/mcp-server
```

O en la configuración MCP:

```json
{
  "env": {
    "SERVICIALO_TELEMETRY": "false"
  }
}
```

Más detalles: [servicialo.com/network](https://servicialo.com/network)

## Únete a la red

Al instalar `@servicialo/mcp-server`, tu nodo se registra automáticamente en la [telemetría de la red](https://servicialo.com/network). Esto ayuda al ecosistema a medir adopción real del protocolo — sin recopilar datos personales ni de tus clientes.

La telemetría reporta únicamente: versión del paquete, un UUID de nodo persistente, y un hash de IP (para geolocalización aproximada — no almacenamos IPs). Puedes desactivarla en cualquier momento con `SERVICIALO_TELEMETRY=false`.

## Avisos de arranque

El servidor escribe dos avisos informativos en **stderr** — nunca en stdout, que transporta JSON-RPC y se corrompe con cualquier otra cosa:

- **La ventana de comentarios de RFC-005**, mientras siga abierta. Tiene la expiración incorporada: deja de imprimirse después del 2026-09-13, el cierre del período final de comentarios. Un nodo instalado en octubre no ve un anuncio muerto.
- **Si tu nodo es anónimo**, cómo identificarlo (abajo).

Ambos se imprimen una vez por proceso y se silencian con `SERVICIALO_QUIET=true`:

```json
{
  "env": {
    "SERVICIALO_QUIET": "true"
  }
}
```

Esa variable afecta **solo a estos dos avisos**. El banner de modo y el aviso de primera ejecución de telemetría mantienen su comportamiento anterior.

## Identifica tu nodo

Por defecto tu nodo es anónimo: el ping lleva evento, versión, `node_id` y timestamp, nada más. Si operas una implementación propia del protocolo, estas tres variables opcionales la identifican y la postulan a **implementador verificado**:

```bash
SERVICIALO_IMPL_NAME="Mi Plataforma"        # Nombre de tu implementación
SERVICIALO_IMPL_URL="https://example.com"   # Tu sitio web o repositorio
SERVICIALO_IMPL_CONTACT="admin@example.com" # Email de contacto — se hashea antes de salir
```

### Qué sale de tu máquina bajo cada variable

| Variable | Qué viaja | Qué no viaja |
|---|---|---|
| `SERVICIALO_IMPL_NAME` | El nombre en texto plano, como `impl_name`. Es público: se muestra en `/implementors` una vez verificado. | — |
| `SERVICIALO_IMPL_URL` | La URL en texto plano, como `impl_url`. También pública una vez verificada. | — |
| `SERVICIALO_IMPL_CONTACT` | Únicamente `impl_contact_hash`: el SHA-256 del email en minúsculas y sin espacios, calculado **en tu máquina** antes de cualquier petición de red. | El email. No sale del host, no se loguea, no se almacena y no se muestra en ninguna parte. |

Sin variables configuradas, ninguno de estos campos aparece en el ping. Un nodo sin configurar se comporta exactamente igual que antes de esta versión.

### El ciclo de verificación

`anonymous` → `pending` → `verified`

1. **`anonymous`** — sin variables configuradas. Es el estado por defecto, y un nodo anónimo es plenamente conforme.
2. **`pending`** — la primera vez que aparece un `impl_name` nuevo, el registro queda pendiente y el equipo recibe una notificación con el nombre, la URL y el país. El hash de contacto no va en esa notificación, y no podría ir: no serviría de nada.
3. **`verified`** — tras revisión manual contra la checklist de conformance, tu implementación aparece en [servicialo.com/implementors](https://servicialo.com/implementors) con su nivel y el número de hosts que reporta.

La verificación es manual hoy. La suite automatizada de conformance está en el roadmap; no es una capacidad actual.

**Para qué sirve el hash de contacto — y para qué no.** Es un digest de una sola vía: nadie puede escribirte a partir de él, y configurarlo no te suscribe a ningún anuncio ni lista. Sirve para lo contrario: cuando *vos* escribís sobre tu implementación, el hash de tu email confirma que sos el operador que envió esos pings.

### Cómo dejar de enviarlo

Elimina las variables de tu configuración MCP (o `unset SERVICIALO_IMPL_NAME SERVICIALO_IMPL_URL SERVICIALO_IMPL_CONTACT`) y reinicia el servidor. El siguiente ping vuelve a ser anónimo, sin ningún campo de identidad. Los pings ya enviados conservan lo que enviaron; para pedir la eliminación de registros existentes, abre un issue en el [repositorio](https://github.com/servicialo/mcp-server/issues).

### Capacidad adyacente: snapshots semanales

El registry emite `benchmark.weekly_snapshot` cada lunes a las 00:00 UTC hacia los endpoints suscritos, con payload firmado por HMAC-SHA256. **Estas tres variables no lo activan.** Requiere una entrada en el registry y una suscripción explícita vía la [Webhooks API](https://github.com/servicialo/mcp-server/blob/main/WEBHOOKS.md), y entrega datos de benchmarks, no anuncios del protocolo.

## Licencia

Apache-2.0 — cualquier implementación, comercial o no, es bienvenida. Ver [LICENSE](./LICENSE).