124 lines
5.3 KiB
Markdown
124 lines
5.3 KiB
Markdown
# WebMCP - Fork Nucleo Rio Frio
|
|
|
|
> **IMPORTANTE: Este es un fork modificado de [@jason.today/webmcp](https://github.com/jasonjmcghee/webmcp) v0.1.13.**
|
|
> 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/@jason.today/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/@jason.today/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:** https://www.npmjs.com/package/@jason.today/webmcp
|
|
- **Versión base:** 0.1.13
|
|
- **Licencia:** MIT (sin cambios)
|