Files

josedario87 78e1e72b89 Renombrar paquete a @nucleoriofrio/webmcp y fix crash de stdin

- Renombrar de @jason.today/webmcp a @nucleoriofrio/webmcp en package.json, config.js, websocket-server.js, build/index.js y README
- Fix crash de stdin cuando no hay TTY: agregar check process.stdin.isTTY y try/catch en setRawMode
- Bump version a 0.2.0

2026-02-12 23:54:07 -06:00

5.4 KiB

Raw Blame History

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 (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

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"]
        }
    }
}

Flujo de conexión

El agente ejecuta get-token para generar un token de conexión
El usuario pega el token en el widget azul (esquina inferior derecha de la página)
La página se conecta al WebSocket server y registra sus herramientas
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)

5.4 KiB Raw Blame History