# propyte-mejoras-mcp

Puente stdio para el **tablero de Mejoras IA de Propyte**. Deja que Claude Desktop, Claude Code y
cualquier cliente MCP que hable stdio lean y escriban el tablero de `hub.propyte.com`.

## Qué es y qué no es

Este paquete **no implementa ninguna tool**. Traduce transporte y nada más: el cliente habla
JSON-RPC por líneas en stdin, la puerta del Hub lo habla por POST.

```
Claude Desktop / Claude Code
        │  stdio (JSON-RPC por líneas)
        ▼
  propyte-mejoras-mcp          ← este paquete: 250 líneas, cero dependencias
        │  HTTPS POST + Authorization: Bearer
        ▼
  hub.propyte.com/api/mcp/mejoras
        │
        ▼
  el tablero (ai_tasks)
```

Las tools, su validación y su relectura después de escribir viven **en el Hub**. Dos consecuencias
prácticas:

- Cuando el Hub publique tools nuevas, **aparecen solas** en tu cliente. No hay que actualizar este
  paquete.
- No hay una segunda copia de las reglas del tablero que pueda quedar desincronizada con la del Hub.

Si usas **Claude Cowork o claude.ai**, no necesitas esto: ahí se agrega la URL directamente como
conector personalizado. Este puente existe para los clientes que solo hablan stdio.

## Instalación

Requiere **Node 20 o superior**. No hay que compilar nada ni instalar dependencias.

### 1. Consigue el token

Se copia desde **[hub.propyte.com/mejoras/conectar](https://hub.propyte.com/mejoras/conectar)**
(hace falta ser `ADMIN` o `DIRECTOR`). Esa pantalla también muestra la fecha de la última rotación.

No pidas el token por chat ni lo copies de un documento: la pantalla es la única fuente que sabe si
el secreto sigue vigente.

### 2. Configura tu cliente

**Claude Desktop** — `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "propyte-mejoras": {
      "command": "npx",
      "args": ["-y", "github:Propyte-Luis/propyte-mejoras-mcp"],
      "env": {
        "MCP_MEJORAS_TOKEN": "el-token-de-/mejoras/conectar"
      }
    }
  }
}
```

**Claude Code** — una línea:

```bash
claude mcp add propyte-mejoras \
  --env MCP_MEJORAS_TOKEN=el-token-de-/mejoras/conectar \
  -- npx -y github:Propyte-Luis/propyte-mejoras-mcp
```

### 3. Comprueba que arrancó

Reinicia el cliente y pide la lista de tools. Deberías ver las del tablero (`mejoras_list_tasks`,
`mejoras_get_task`, `mejoras_create_task`, `mejoras_update_task`).

Si prefieres probarlo a mano, sin cliente:

```bash
export MCP_MEJORAS_TOKEN=...
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | npx -y github:Propyte-Luis/propyte-mejoras-mcp
```

## Configuración

| Variable | Obligatoria | Default |
|---|---|---|
| `MCP_MEJORAS_TOKEN` | **sí** | — |
| `MCP_MEJORAS_URL` | no | `https://hub.propyte.com/api/mcp/mejoras` |

`MCP_MEJORAS_URL` solo se cambia para apuntar a un Hub local (`http://localhost:3001/api/mcp/mejoras`).

**Sin `MCP_MEJORAS_TOKEN` el puente no arranca**, y sale con código 1 diciendo cuál variable falta.
Es deliberado: un puente que arrancara sin token dejaría al cliente con un servidor que contesta «no
autorizado» a todo, y eso se lee como «el Hub está caído» — que manda a mirar el lugar equivocado.

⚠️ `MCP_MEJORAS_TOKEN` **no es** `MCP_BLOG_TOKEN` ni `MCP_API_TOKEN`. Son tres secretos distintos
para tres puertas distintas.

## Qué se puede hacer con las tools

| Tool | Escribe | Para qué |
|---|---|---|
| `mejoras_list_tasks` | no | Ver el tablero filtrado por proyecto, estado o prioridad |
| `mejoras_get_task` | no | Una tarea completa, con su verificación y su evidencia |
| `mejoras_create_task` | sí | Registrar una mejora encontrada |
| `mejoras_update_task` | sí | Cambiar estado, prioridad o evidencia |

Dos reglas que impone el servidor, no este puente:

- **`resumen_humano` tiene que decir qué cambió para alguien que no ve el código.** Un resumen
  genérico se rechaza con ejemplos de lo que sí sirve.
- **`estado = 'desplegada'` exige evidencia.** Un badge verde sin evidencia es justo lo que el panel
  existe para impedir.

## Seguridad

- **El secreto viaja por cabecera**, no en la ruta. La puerta acepta las dos formas —la ruta existe
  porque Cowork no puede mandar cabeceras— pero la ruta queda escrita en los logs de acceso del
  servidor, y un proceso local no tiene por qué pagar ese costo. Hay un test que lo verifica.
- **En `stdout` solo salen mensajes JSON-RPC.** Todo lo demás va a `stderr`; cualquier otra cosa en
  `stdout` la lee el cliente como protocolo y cierra la conexión.
- Es un **token compartido**, rotable desde `/mejoras/conectar`. No es una credencial de la base de
  datos, y ninguna tool de esta puerta escribe en el CRM.

## Desarrollo

```bash
npm test    # 13 tests, cero dependencias
```

Los tests corren contra una puerta MCP falsa en `localhost`, y dos de ellos ejercitan el **binario
como proceso** —no el módulo— porque un shebang roto o un `console.log` olvidado no lo caza ningún
test de unidad y el síntoma en el cliente es «el servidor no arranca», sin más información.

Lo que verifican: que `tools/list` pase íntegro sin que el puente invente ni recorte tools, que el
token no aparezca en la URL, que una notificación no produzca respuesta, que un mensaje partido
entre dos trozos de stdin no se corrompa, que una respuesta SSE se desenvuelva ignorando los pings
de keepalive, y que un 401 o un 500 lleguen al cliente como error con su motivo en vez de silencio.