webmcp/README.md

WebMCP - Fork Nucleo Rio Frio

IMPORTANTE: Este es un fork modificado de @jason.today/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 (solo modo dev)

Tool built-in _webmcp_agregar-tool que permite al agente registrar herramientas nuevas en el navegador en tiempo real. Solo disponible en modo desarrollo (--dev).

Parámetros:

Param	Requerido	Tipo	Descripción
nombre	Sí	string	Nombre de la herramienta que Claude verá
descripcion	Sí	string	Qué hace la herramienta (Claude lee esto para decidir cuándo usarla)
codigo	Sí	string	Body de una función JS. Recibe args como parámetro. Debe retornar un string.
parametros	No	string	JSON string con las properties del inputSchema

Flujo de ejecución:

Agente envía nombre + descripcion + codigo + parametros
  → server.js valida y reenvía al WebSocket Server
    → websocket-server.js busca el primer navegador conectado
      → navegador recibe el mensaje 'createTool'
        → webmcp.js ejecuta new Function('args', codigo) para compilar el código
        → webmcp.js llama registerTool() para registrar la herramienta
      → respuesta 'toolResponse' viaja de vuelta
    → websocket-server.js enruta la respuesta al MCP server
  → server.js llama sendToolListChanged()
→ Claude ahora puede usar la nueva herramienta

El código se ejecuta en el contexto del navegador, con acceso a document, window, fetch(), localStorage, navigator, y todas las APIs web. Solo tiene acceso al scope global (no a closures/variables locales de la página, salvo que estén en window).

2. quitar-tool — Eliminación de herramientas (solo modo dev)

Tool built-in _webmcp_quitar-tool con tres modos de operación. Solo disponible en modo desarrollo (--dev).

Parámetros (todos opcionales, pero debe usarse al menos uno):

Param	Tipo	Efecto
listar	boolean	Si true, lista las herramientas activas sin borrar nada
nombre	string	Nombre de la herramienta específica a eliminar
todas	boolean	Si true, elimina todas las herramientas de una vez

Comportamiento por modo:

• listar: true — Se resuelve en websocket-server.js leyendo el toolsRegistry. No toca el navegador. Retorna "Herramientas activas: tool1, tool2".
• nombre: "x" — Busca en toolsRegistry por nombre, la borra, y envía removeTool al navegador correspondiente para que sincronice su estado local.
• todas: true — Borra todo el toolsRegistry, envía removeAllTools a todos los navegadores conectados, y retorna "N herramientas desregistradas".

En los tres casos, después de resolver se llama sendToolListChanged() para que Claude actualice su lista.

3. Eliminación de define-mcp-tool

Se eliminó la built-in _webmcp_define-mcp-tool del upstream por no tener utilidad real en este fork.

4. 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)

5. 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

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

Uso

En tu 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:

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

Modo desarrollo

Las tools agregar-tool y quitar-tool solo están disponibles en modo desarrollo. Para activarlo:

Opción 1: Flag de línea de comandos

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

Opción 2: Variable de entorno

WEBMCP_DEV=true node src/websocket-server.js --mcp

Cuando el modo dev está activo, el servidor muestra una advertencia al iniciar:

[DEV] Modo desarrollo activo — agregar-tool y quitar-tool habilitados

En producción (sin --dev), estas tools no aparecen en el listado de herramientas y si se intentan llamar directamente retornan un error.

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 (requiere --dev)

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)