README: documentar fork, parches aplicados y referencia a upstream
This commit is contained in:
200
README.md
200
README.md
@@ -1,141 +1,123 @@
|
||||
# WebMCP
|
||||
# WebMCP - Fork Nucleo Rio Frio
|
||||
|
||||
A proposal and code for websites to support client side LLMs
|
||||
> **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.
|
||||
|
||||
[](https://www.npmjs.com/package/@jason.today/webmcp) [](./LICENSE)
|
||||
## Qué es WebMCP
|
||||
|
||||
WebMCP allows websites to share tools, resources, prompts, etc. to LLMs. In other words, WebMCP allows a website to be an MCP server. No sharing API Keys. Use any model you want.
|
||||
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.
|
||||
|
||||
[Here's a simple website I built that is WebMCP-enabled](https://webmcp.dev)
|
||||
La comunicación funciona así:
|
||||
|
||||
It comes in the form of a widget that a website owner can put on their site and expose tools to give client-side LLMs what they need to provide a great UX for the user or agent.
|
||||
```
|
||||
Agente LLM <-> MCP Server (localhost) <-> WebSocket Server <-> Navegador del usuario
|
||||
```
|
||||
|
||||
_The look, feel, how it's used, and security are all absolutely open for contribution / constructive criticism. MCP Clients directly building WebMCP functionality seems like an ideal outcome._
|
||||
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.
|
||||
|
||||
An end-user can connect to any number of websites at a time - and tools are "scoped" (by name) based on the domain to simplify organization.
|
||||
## Qué cambia este fork
|
||||
|
||||
### Super Quick Demo (20 seconds, Sound on 🔊)
|
||||
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.
|
||||
|
||||
https://github.com/user-attachments/assets/61229470-1242-401e-a7d9-c0d762d7b519
|
||||
### Parches aplicados
|
||||
|
||||
## Getting started (using your LLM with websites using WebMCP)
|
||||
**3 archivos modificados: `src/server.js`, `src/webmcp.js`, `src/websocket-server.js`**
|
||||
|
||||
#### Installation
|
||||
#### 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
|
||||
|
||||
Just specify your MCP client (`claude`, `cursor`, `cline`, `windsurf`, or a path to json)
|
||||
#### 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
|
||||
npx -y @jason.today/webmcp@latest --config claude
|
||||
npm install git+https://gitea.nucleoriofrio.com/nucleo000/webmcp.git
|
||||
```
|
||||
|
||||
_If you're interested in setting it up manually, use the command `npx -y @jason.today/webmcp@latest --mcp`._
|
||||
## Uso
|
||||
|
||||
_Auto-install was inspired by Smithery, but their code is AGPL so I wrote this myself. If it doesn't work for you or you don't see your mcp client, please file an issue._
|
||||
### En tu HTML
|
||||
|
||||
#### Using WebMCP
|
||||
```html
|
||||
<script src="node_modules/@jason.today/webmcp/src/webmcp.js"></script>
|
||||
<script>
|
||||
const webmcp = new WebMCP({
|
||||
color: '#00d4ff',
|
||||
inactivityTimeout: 30 * 60 * 1000
|
||||
});
|
||||
|
||||
When you're ready to connect to a website, you can ask your model to generate you an mcp token.
|
||||
|
||||
Copy the token and paste it to the website's input. As soon as the website registers with it, it's thrown away and cannot be used for subsequent registrations or anything else. The website will receive its own session token for making requests.
|
||||
|
||||
If you'd rather your model / service never see the token, you can manually execute `npx @jason.today/webmcp --new` instead.
|
||||
|
||||
Some MCP clients, including Claude Desktop, need to be restarted to get access to new tools. (at least at time of writing)
|
||||
|
||||
To disconnect, you can close the browser tab, click "disconnect", or shut down the server with `npx @jason.today/webmcp -q`.
|
||||
|
||||
All configuration files are stored in `~/.webmcp` directory.
|
||||
|
||||
## Getting started (adding WebMCP to your website)
|
||||
|
||||
To use WebMCP, simply include [`webmcp.js`](https://github.com/jasonjmcghee/WebMCP/releases) on your page (via src or directly):
|
||||
|
||||
```
|
||||
<script src="webmcp.js"></script>
|
||||
// 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>
|
||||
```
|
||||
|
||||
The WebMCP widget will automatically initialize and appear in the bottom right corner of your page. Clicking on it will ask for a webmcp token which the end-user will generate.
|
||||
### Configuración MCP (Claude Code u otro cliente)
|
||||
|
||||
### Full Demo (3 minutes)
|
||||
En `.claude/settings.json` o settings del proyecto:
|
||||
|
||||
https://github.com/user-attachments/assets/43ad160a-846d-48ad-9af9-f6d537e78473
|
||||
|
||||
## More Info About How It Works
|
||||
|
||||
The bridge between the MCP client and the website is a localhost-only (not accessible to requests outside your computer) websocket server. Because it is configured to allow requests from your local web browser, authentication / token exchange is required, in case you visit a website attempting to abuse this.
|
||||
|
||||
_Ideally the web browser itself would have an explicit permission for this, like webcam or microphone use._
|
||||
|
||||
1. The MCP client connects to the `/mcp` path using the server token from `.env` (auto-generated)
|
||||
2. The server generates a registration token (instigated via the built-in mcp tool by a model or the `--new` command)
|
||||
3. Web clients connect to the `/register` endpoint with this token and its domain.
|
||||
4. Web pages connect to their assigned channel based on their domain.
|
||||
5. When an LLM wants to use a tool / resource / prompt, the request flows from:
|
||||
- MCP Client → MCP Server → WebSocket Server → Web Page with the tool / resource / prompt
|
||||
- (similar for requesting a list of tools / resources / prompts)
|
||||
6. The web page performs the request (e.g. call tool) and sends the result back through the same path
|
||||
7. Multiple web pages can be connected simultaneously, each with their own set of tools and tokens
|
||||
8. The MCP client sees all tools as a unified list, with channel prefixes to avoid name collisions
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User
|
||||
participant MCP as MCP Client
|
||||
participant Server as MCP Server
|
||||
participant WS as WebSocket Server
|
||||
participant Web as Website
|
||||
|
||||
%% Initial connection
|
||||
MCP->>Server: Connect to /mcp with internal server token
|
||||
|
||||
%% Website registration token
|
||||
User->>MCP: Request registration token
|
||||
MCP->>Server: Request registration token
|
||||
Server-->>MCP: Return registration token
|
||||
MCP-->>User: Display registration token
|
||||
|
||||
%% Website registration
|
||||
User->>Web: Paste registration token
|
||||
Web->>WS: Connect to /register with token & domain (registration token deleted)
|
||||
WS-->>Web: Assign channel & session token
|
||||
Web->>WS: Connect to assigned channel
|
||||
|
||||
%% Tool interaction
|
||||
MCP->>Server: Request tools list
|
||||
Server->>WS: Forward request
|
||||
WS->>Web: Request tools
|
||||
Web-->>WS: Return tools list
|
||||
WS-->>Server: Forward tools list
|
||||
Server-->>MCP: Return tools list
|
||||
|
||||
%% Tool execution
|
||||
MCP->>Server: Tool request
|
||||
Server->>WS: Forward request
|
||||
WS->>Web: Execute tool
|
||||
Web-->>WS: Return result
|
||||
WS-->>Server: Forward result
|
||||
Server-->>MCP: Return result
|
||||
|
||||
%% Disconnection
|
||||
User->>Web: Disconnect
|
||||
Web->>WS: Close connection
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"webmcp": {
|
||||
"command": "node",
|
||||
"args": ["node_modules/@jason.today/webmcp/src/websocket-server.js", "--mcp"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Security
|
||||
### Flujo de conexión
|
||||
|
||||
This is a super early project. I'm very interested in hardening security to prevent malicious extensions etc. from being
|
||||
able to perform prompt injection attacks and similar. If you have constructive ideas, please reach out or open an issue.
|
||||
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`
|
||||
|
||||
## Built in tools
|
||||
### Crear herramientas dinámicas desde el agente
|
||||
|
||||
- Token generator (for connecting to WebMCP websites)
|
||||
- MCP Tool Definer (to simplify building the schema of a tool for use with MCP)
|
||||
- You can ask for the javascript (if relevant) in a follow-up message for use with WebMCP
|
||||
Con este fork, el agente puede crear herramientas sin modificar el HTML:
|
||||
|
||||
## Docker
|
||||
```
|
||||
agregar-tool:
|
||||
nombre: "mi-nueva-tool"
|
||||
descripcion: "Que hace"
|
||||
codigo: "return document.title;"
|
||||
parametros: '{"param1":{"type":"string","description":"algo"}}'
|
||||
```
|
||||
|
||||
There is a `Dockerfile` specifically for Smithery deployment.
|
||||
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.
|
||||
|
||||
If you'd like to use docker to run the websocket server, I've added a `docker-compose.yml` for demonstration purposes.
|
||||
## Referencia upstream
|
||||
|
||||
If `--docker` is provided to the mcp client config alongside `--mcp`, it will assume the server is running. This will allow you to dockerize the main process (websocket server), and your mcp client will connect to your docker container via websocket. Similarly, websites will communicate with your docker container.
|
||||
- **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)
|
||||
|
||||
Reference in New Issue
Block a user