Conector Splitwise para ChatGPT

Un servidor MCP solo de datos que conecta ChatGPT con la API oficial de Splitwise. Admite:

• list_groups

• list_friends (incluidos los saldos)

• list_expenses

• get_expense

• create_expense (división igualitaria en grupo o partes explícitas)

El servidor utiliza HTTP Streamable en /mcp. También actúa como un pequeño puente de autorización OAuth 2.1: ChatGPT completa PKCE con este servidor, mientras que este servidor completa el OAuth de Splitwise y mantiene el token de Splitwise fuera de ChatGPT.

Requisitos previos

• Node.js 20 o superior

• Una URL HTTPS pública estable para el despliegue (o un túnel de desarrollo mientras se prueba)

• Una cuenta de Splitwise y una aplicación OAuth de Splitwise

1. Registrar la aplicación de Splitwise

1. Abra https://secure.splitwise.com/apps y cree una aplicación OAuth.

2. Establezca su URL de devolución de llamada en https://YOUR-CONNECTOR-HOST/oauth/splitwise/callback.

3. Copie el ID de cliente y el secreto de cliente. Nunca los incluya en un commit.

Splitwise debe redirigir al conector, no directamente a ChatGPT. El conector reanuda el flujo PKCE independiente de ChatGPT después.

2. Configurar y ejecutar

cp .env.example .env
# Fill in .env, then:
npm install
npm run dev

Variables obligatorias:

Variables opcionales: PORT, SPLITWISE_AUTHORIZE_URL, SPLITWISE_TOKEN_URL y SPLITWISE_API_BASE_URL.

Genere un secreto de sesión con openssl rand -hex 32. Para un contenedor:

docker build -t splitwise-mcp .
docker run --env-file .env -p 3000:3000 splitwise-mcp

3. Flujo OAuth

1. ChatGPT descubre /.well-known/oauth-protected-resource desde el servidor MCP.

2. Descubre los metadatos OAuth de este conector en /.well-known/oauth-authorization-server y registra dinámicamente un cliente público en /register.

3. ChatGPT inicia el flujo de código de autorización + PKCE en /authorize, incluido el valor resource de MCP.

4. El conector redirige al usuario a Splitwise y recibe el resultado en /oauth/splitwise/callback.

5. El conector intercambia el código de Splitwise en el servidor, crea un código de conector cifrado de cinco minutos y redirige a ChatGPT.

6. ChatGPT intercambia ese código en /token usando su verificador PKCE. El conector devuelve un token de acceso autenticado y cifrado que contiene el contexto mínimo de sesión.

7. Cada solicitud /mcp descifra y valida el token, la caducidad, el contexto de alcance y el recurso antes de llamar a Splitwise.

Los registros dinámicos de clientes, los códigos de conector y los tokens de acceso de 30 días son sobres AES-256-GCM sin estado derivados de SESSION_SECRET. Sobreviven a suspensiones, reinicios, redespliegues y múltiples réplicas siempre que cada instancia mantenga el mismo secreto. Rotar SESSION_SECRET invalida intencionadamente todos los registros y conexiones existentes. Este ejemplo no emite tokens de actualización, por lo que se requiere volver a vincular después de 30 días.

4. Probar y conectar con ChatGPT

Ejecute:

npm run build
npm test
npx @modelcontextprotocol/inspector@latest

En el Inspector, elija Streamable HTTP y use https://YOUR-CONNECTOR-HOST/mcp.

En ChatGPT, active el modo Desarrollador en Configuración → Seguridad e inicio de sesión. En la página de Plugins, añada una conexión, elija la opción de endpoint público e introduzca https://YOUR-CONNECTOR-HOST/mcp. Revise las cinco herramientas descubiertas y, a continuación, invoque una herramienta de lectura para iniciar la vinculación de la cuenta.

Comprobaciones sugeridas:

• «Lista mis grupos de Splitwise».

• «Muestra los saldos con mis amigos de Splitwise».

• «Lista los últimos cinco gastos del grupo 123».

• «Obtén los detalles completos del gasto 456».

• «Crea un gasto de cena de 24 USD en el grupo 123, dividido a partes iguales».

Notas de producción

El servidor ejecutable no almacena ningún estado de sesión OAuth. Antes de un despliegue multiusuario más amplio:

• Mantenga SESSION_SECRET estable, secreto e idéntico en todas las réplicas. Para una gestión de claves más sólida, derive u obtenga la clave de cifrado de un KMS gestionado; nunca registre tokens ni secretos en los registros.

• Los códigos de autorización sin estado no pueden marcarse como consumidos sin almacenamiento. PKCE, la vinculación exacta de cliente/redirección/recurso, el cifrado autenticado y la vida útil de cinco minutos limitan la exposición a la reproducción. Si se requiere una aplicación estricta de un solo uso, añada una caché de reproducción compartida de corta duración con clave basada en un identificador de código.

• Restrinja los URI de redirección del registro dinámico a las URL de devolución de llamada exactas de ChatGPT que muestra la página de gestión de la aplicación (además de las devoluciones de llamada de desarrollo configuradas explícitamente).

• Añada limitación de velocidad, registros de seguridad estructurados, rotación de secretos, una política de privacidad y revocación de tokens/desvinculación de cuentas.

• Conserve la vinculación de resource, la verificación PKCE, la vida útil corta del código y la coincidencia exacta del URI de redirección.

• Ejecute detrás de HTTPS. No exponga este servidor de desarrollo directamente a Internet.

La herramienta create_expense está marcada como una escritura no idempotente. Sus instrucciones indican al modelo que resuma el importe exacto, la moneda, el grupo, el pagador y las partes antes de llamarla. Splitwise puede devolver HTTP 200 con un objeto errors a nivel de aplicación, por lo que el conector comprueba ese objeto antes de informar del éxito.