# lexmex-mcp-server

Servidor [MCP](https://modelcontextprotocol.io) oficial de [LexMex](https://lex-mex.xyz) — inteligencia jurídica sobre legislación federal mexicana (316 leyes indexadas, citas verificadas contra el DOF).

Endpoint público: `https://lex-mex.xyz/mcp`

## Qué es este repo

Este repo contiene el **código fuente real y sin modificar** del servidor MCP de producción de LexMex y de su capa de autenticación OAuth 2.0 + PKCE (RFC 6749, RFC 7591, RFC 8414, RFC 9728). Se publica para que cualquiera pueda auditar exactamente cómo se maneja la autenticación y qué hace cada tool antes de conectar su cliente MCP.

**Lo que es real (código de producción, sin cambios):**
- `mcp_service.py` — el proceso que sirve el protocolo MCP (Resource Server)
- `mcp_agentic.py` — definición del servidor y las tools (`consultar_ley_mexicana`, `consultar_precios`, `ver_catalogo_leyes`, `como_obtener_acceso`)
- `mcp_auth_provider.py` — implementación de `OAuthAuthorizationServerProvider` del SDK `mcp`
- `mcp_oauth_routes.py` — pantalla de consentimiento humano + introspección interna de tokens
- `db/mcp_oauth.py` — capa de datos (clientes registrados, códigos de autorización, PKCE)

**Lo que es un stub documentado (no es el código real):** `config.py`, `auth/`, `agentic_routes.py` (salvo una función pública) y `db/usuarios.py`. Son las dependencias hacia el backend privado de LexMex — el sistema de usuarios, planes de suscripción y validación de sesión, con ~2200 líneas de lógica y RLS de Postgres que no se publican. Cada stub trae un docstring explicando qué reemplaza. Sin ellos, este repo no arranca de forma standalone — es intencional: el servidor MCP real siempre corre contra el backend de producción, nunca de forma aislada.

## Arquitectura — dos servidores, dos roles

```
Cliente MCP (Claude, VS Code, etc.)
        │
        │  HTTPS
        ▼
┌─────────────────────┐         ┌──────────────────────────┐
│   LexMex (app.py)    │  HTTP   │   lexmex-mcp              │
│   Authorization       │◄───────►│   (mcp_service.py)        │
│   Server               │ privada │   Resource Server          │
│   /authorize /token    │        │   /mcp                      │
│   /register /revoke    │        │                              │
│   /mcp-oauth/consent   │        │   Verifica cada Bearer token │
│   /mcp-oauth/introspect│        │   vía introspección HTTP     │
└─────────────────────┘         └──────────────────────────┘
```

- El **Authorization Server** (no incluido en este repo — vive en el backend principal) maneja login, consentimiento y emite tokens.
- El **Resource Server** (`mcp_service.py`, este repo) nunca toca Postgres directamente — verifica cada token preguntándole al AS por red privada.
- El access token emitido **es** la API key real de LexMex — no hay un tipo de credencial paralelo que auditar (ver el docstring de `mcp_auth_provider.py`).

## Flujo de autenticación

1. Un cliente MCP se registra dinámicamente (`POST /register`, RFC 7591).
2. Redirige al humano a `/authorize` con PKCE (`code_challenge`, S256).
3. El humano ve una pantalla de consentimiento (`mcp_oauth_routes.py`), inicia sesión si hace falta, y aprueba o rechaza.
4. El cliente canjea el `code` por un `access_token` en `POST /token`.
5. Cada llamada MCP subsecuente lleva ese token en `Authorization: Bearer` — `mcp_service.py` lo valida vía introspección antes de ejecutar cualquier tool.

## Privacidad y retención de datos

- Los códigos de autorización expiran en 2 minutos y son de un solo uso (ver `db/mcp_oauth.py`, canje atómico anti-replay).
- Las API keys nunca se guardan en texto plano — solo su hash SHA-256.
- `mcp_service.py` no persiste nada — es un proceso sin estado más allá de la sesión MCP activa en memoria.

## Licencia

Código publicado con fines de auditoría y transparencia. No es software libre de uso general — es el servidor de producción de un servicio comercial (LexMex).