webmcp/README.md

# WebMCP - Fork Nucleo Rio Frio

> **IMPORTANTE: Este es un fork modificado de [@jason.today/webmcp](https://github.com/jasonjmcghee/webmcp) v0.1.13, renombrado a `@nucleoriofrio/webmcp`.**
> La documentación original, diagramas de arquitectura y explicaciones detalladas del protocolo se encuentran en el repositorio upstream.
> Las APIs base deberían ser idénticas — si encontrás discrepancias entre este fork y la documentación original, reportalo porque se supone que deben ser compatibles salvo por los parches descritos abajo.

## Qué es WebMCP

WebMCP permite que una página web actúe como un servidor MCP (Model Context Protocol). Un agente LLM (Claude Code, Cursor, etc.) puede ejecutar herramientas, leer recursos y usar prompts que corren directamente en el navegador del usuario.

La comunicación funciona así:

```
Agente LLM <-> MCP Server (localhost) <-> WebSocket Server <-> Navegador del usuario
```

El navegador expone herramientas (funciones JS) que el agente puede invocar remotamente. Las herramientas tienen acceso completo al DOM, APIs del browser, y todo lo que JavaScript puede hacer en una página web.

## Qué cambia este fork

Este fork agrega **registro dinámico de herramientas desde el agente**, algo que la versión original no soporta. En la versión original, las herramientas se registran únicamente desde la página web. En este fork, el agente puede crear y eliminar herramientas en tiempo real sin tocar el código de la página.

### Parches aplicados

**3 archivos modificados: `src/server.js`, `src/webmcp.js`, `src/websocket-server.js`**

#### 1. `agregar-tool` — Registro dinámico de herramientas (server.js, websocket-server.js, webmcp.js)
- Tool built-in `_webmcp_agregar-tool` que permite al agente registrar herramientas nuevas en el navegador en tiempo real
- El agente envía nombre, descripción, parámetros (JSON schema) y código JavaScript
- El código se compila con `new Function('args', codigo)` en el navegador y se registra como tool
- El flujo es: Agente -> MCP Server -> WebSocket Server -> Navegador (createTool) -> respuesta de vuelta
- Después de registrar, se emite `sendToolListChanged()` para que el MCP client refresque su lista

#### 2. `quitar-tool` — Eliminación de herramientas (server.js, websocket-server.js, webmcp.js)
- Tool built-in `_webmcp_quitar-tool` con tres modos:
  - `listar: true` — lista las herramientas activas registradas en el navegador
  - `nombre: "x"` — elimina una herramienta específica por nombre
  - `todas: true` — elimina todas las herramientas de una vez
- Notifica al navegador para que sincronice su estado local

#### 3. Manejo de mensajes nuevos en el cliente web (webmcp.js)
- `createTool` — recibe la definición de herramienta del server, la compila y registra localmente
- `removeTool` — elimina una herramienta específica del registro local
- `removeAllTools` — limpia todas las herramientas del registro local
- `clipboardCopy` — permite copiar texto al portapapeles del usuario (usado para tokens)

#### 4. Ruteo en WebSocket Server (websocket-server.js)
- `handleCreateTool()` — recibe la petición del MCP server, encuentra un navegador conectado y le reenvía la instrucción de crear la herramienta
- `handleRemoveTool()` — maneja listar/eliminar herramientas, sincroniza entre el registry del server y los navegadores conectados

## Instalación

```bash
npm install git+https://gitea.nucleoriofrio.com/nucleo000/webmcp.git
```

## Uso

### En tu HTML

```html
<script src="node_modules/@nucleoriofrio/webmcp/src/webmcp.js"></script>
<script>
    const webmcp = new WebMCP({
        color: '#00d4ff',
        inactivityTimeout: 30 * 60 * 1000
    });

    // Registrar herramientas desde la página (igual que upstream)
    webmcp.registerTool('mi-tool', 'Hace algo', {
        type: 'object',
        properties: {
            param: { type: 'string', description: 'Un parametro' }
        }
    }, function(args) {
        // Tiene acceso completo al DOM y APIs del browser
        return 'Resultado: ' + args.param;
    });
</script>
```

### Configuración MCP (Claude Code u otro cliente)

En `.claude/settings.json` o settings del proyecto:

```json
{
    "mcpServers": {
        "webmcp": {
            "command": "node",
            "args": ["node_modules/@nucleoriofrio/webmcp/src/websocket-server.js", "--mcp"]
        }
    }
}
```

### Flujo de conexión

1. El agente ejecuta `get-token` para generar un token de conexión
2. El usuario pega el token en el widget azul (esquina inferior derecha de la página)
3. La página se conecta al WebSocket server y registra sus herramientas
4. El agente puede usar las herramientas de la página y crear nuevas dinámicamente con `agregar-tool`

### Crear herramientas dinámicas desde el agente

Con este fork, el agente puede crear herramientas sin modificar el HTML:

```
agregar-tool:
  nombre: "mi-nueva-tool"
  descripcion: "Que hace"
  codigo: "return document.title;"
  parametros: '{"param1":{"type":"string","description":"algo"}}'
```

El código JavaScript recibe `args` como parámetro y debe retornar un string. Se ejecuta en el contexto del navegador, con acceso a `document`, `window`, `navigator`, `fetch`, `WebAssembly`, `canvas`, y todas las APIs web.

## Referencia upstream

- **Repositorio original:** https://github.com/jasonjmcghee/webmcp
- **npm (original):** https://www.npmjs.com/package/@jason.today/webmcp
- **Versión base:** 0.1.13
- **Licencia:** MIT (sin cambios)