nadanada_me

Servidor MCP de Phone

Adaptador MCP independiente para lnvpn-web-app/app/api/v2/phone/*.

Este servicio es solo aditivo: no cambia las rutas ni el comportamiento de la API de phone existente.

Lo que expone

Herramientas mapeadas 1:1 a tu API existente:

• phone.purchase.start -> POST /api/v2/phone/purchase
• phone.purchase.complete -> POST /api/v2/phone/complete
• phone.renew.start -> POST /api/v2/phone/renew
• phone.renew.complete -> POST /api/v2/phone/renew/complete
• phone.numbers.list -> GET /api/v2/phone/numbers
• phone.messages.list -> GET /api/v2/phone/messages/{phoneNumber}

Modelo de seguridad

Por defecto, el servidor se ejecuta en modo hmac (MCP_AUTH_MODE=hmac).

Cada solicitud a /mcp debe incluir:

• X-Client-Id
• X-Timestamp (ms unix)
• X-Nonce (UUID recomendado)
• X-Body-SHA256 (sha256 hex del cuerpo JSON estable)
• X-Signature (v1=<hex_hmac>)

Cadena de firma canónica:

{METHOD}\n{PATH}\n{X-Timestamp}\n{X-Nonce}\n{X-Body-SHA256}

Firma:

hex(HMAC_SHA256(canonical, client_secret))

Controles:

• protección contra desviación de marca de tiempo (HMAC_ALLOWED_SKEW_MS)
• protección de reproducción de nonce de un solo uso (Redis recomendado)
• límite de velocidad por cliente
• lista de herramientas permitidas por cliente

Si deseas un endpoint completamente abierto, establece MCP_AUTH_MODE=open. En modo abierto, la autenticación del cliente MCP está deshabilitada y las solicitudes se aceptan sin encabezados HMAC.

Configuración

Crea un archivo .env en la raíz del proyecto y establece valores reales. El servidor carga automáticamente .env al iniciar.

Variables importantes:

• MCP_AUTH_MODE: hmac o open
• MCP_CLIENTS_JSON: requerido en modo hmac

Formato MCP_CLIENTS_JSON:

{
  "agentA": {
    "secret": "replace-with-long-random-secret",
    "allowedTools": [
      "phone.purchase.start",
      "phone.purchase.complete",
      "phone.renew.start",
      "phone.renew.complete",
      "phone.numbers.list",
      "phone.messages.list"
    ],
    "rateLimitPerMinute": 120
  }
}

Ejecución

npm install
npm run dev

Compilar + producción:

npm run build
npm run start

Despliegue

• Plantilla de configuración PM2: ecosystem.config.cjs
• Plantilla de Nginx: nginx.phone-mcp.conf.example

Borde sugerido:

Cloudflare -> Nginx -> phone-mcp (PM2) -> existing phone API