jsmcp

jsmcp existe para casos en los que un agente necesita hacer más que una sola llamada a una herramienta MCP.

La mayoría de los clientes MCP son excelentes para realizar una llamada a una herramienta a la vez, pero resultan incómodos cuando el trabajo requiere:

• varias llamadas a herramientas relacionadas

• lógica de ramificación basada en resultados anteriores

• bucles, reintentos o agregación de resultados

• transformar la salida de una herramienta antes de la siguiente llamada

jsmcp resuelve esto exponiendo las herramientas MCP aprobadas como espacios de nombres de JavaScript. En lugar de obligar al modelo a hacer malabarismos con muchas invocaciones de herramientas por separado, puede descubrir qué hay disponible y luego escribir una pequeña cantidad de JavaScript para usar esas herramientas programáticamente.

En la práctica, esto significa:

• el agente primero aprende qué servidores y herramientas están disponibles, mientras que jsmcp restringe el acceso a los servidores y herramientas que usted permita en un ajuste preestablecido (preset)

• el agente puede entonces escribir JavaScript para trabajos de varios pasos

• los registros (logs) se mantienen separados de los valores de retorno para que el código sea más fácil de razonar

La configuración se lee desde $XDG_CONFIG_HOME/jsmcp/ o, si XDG_CONFIG_HOME no está configurado, ~/.config/jsmcp/. Debe existir exactamente uno de los siguientes archivos: config.json, config.yaml o config.yml.

Por qué

Use jsmcp cuando desee que los agentes traten las herramientas MCP más como una pequeña superficie de API programable que como una secuencia de pulsaciones de botones aisladas.

Esto es especialmente útil cuando un agente necesita:

• combinar resultados de varias herramientas MCP

• crear flujos de trabajo mediante scripts a través de uno o más servidores MCP

• tomar decisiones en el código en lugar de volver a planificar repetidamente entre llamadas a herramientas

• mantener el acceso a las herramientas restringido a un ajuste preestablecido revisado

Related MCP server: MCPMan

Instalación

npm install -g @alesya_h/jsmcp

O ejecútelo sin instalarlo globalmente:

npx @alesya_h/jsmcp run

Ejecución

jsmcp run
jsmcp run work
jsmcp server work --port 3000 --bind 0.0.0.0
jsmcp client --profile work --host 127.0.0.1 --port 3000
jsmcp client --profile work --port 3000 --session-id my-agent-session
jsmcp auth
jsmcp auth firefox_devtools

Si está ejecutando desde una descarga del código fuente en lugar de un paquete instalado, reemplace jsmcp con node src/index.js, por ejemplo node src/index.js run.

run inicia el servidor meta-MCP directamente sobre stdio.

server inicia un demonio de larga duración en ws://<bind>:<port>/mcp, cargando el ajuste preestablecido elegido una vez y manteniendo calientes las conexiones subyacentes del servidor MCP. Se vincula a 0.0.0.0 de forma predeterminada y acepta --bind <host> para elegir otra dirección de enlace.

client expone un servidor MCP stdio que redirige los mensajes MCP/JSON-RPC sin procesar al server a través de WebSocket. Acepta --host <host> y --port <number> para elegir a qué demonio conectarse, puede pasar opcionalmente --profile <name> para requerir que el demonio esté ejecutando el ajuste preestablecido esperado, y acepta --session-id <id> para reutilizar la misma sesión de registro del lado del demonio a través de reconexiones del cliente.

run, server y client aceptan un ajuste preestablecido opcional ya sea como un argumento posicional o --profile <name>. El puerto predeterminado del demonio es 41528. Si se omite client --session-id, el cliente genera un ID de sesión aleatorio y lo reutiliza para las reconexiones durante ese proceso del cliente.

En el primer inicio de server, jsmcp crea una clave de API en $XDG_CONFIG_HOME/jsmcp/api-key.txt, o ~/.config/jsmcp/api-key.txt si XDG_CONFIG_HOME no está configurado. Las solicitudes de API HTTP y WebSocket del demonio deben incluirla en el encabezado X-JSMCP-API-Key; las solicitudes no autenticadas reciben 401.

El demonio también expone las cinco metaherramientas a través de un punto final HTTP JSON:

POST /api/call?tool=list_servers&profile=<name>
POST /api/call?tool=list_tools&profile=<name>
POST /api/call?tool=execute_code&sessionId=<id>&profile=<name>
POST /api/call?tool=fetch_logs&sessionId=<id>
POST /api/call?tool=clear_logs&sessionId=<id>

El cuerpo de la solicitud es un objeto JSON que coincide con los argumentos de la herramienta MCP seleccionada. Los llamadores HTTP pueden incluir sessionId en la cadena de consulta para usar una sesión de registro estable del lado del demonio. Pueden incluir profile para requerir que el demonio esté ejecutando el ajuste preestablecido esperado; las discrepancias devuelven 409.

Use jsmcp auth para gestionar OAuth para servidores remotos. Sin argumentos, enumera los servidores remotos que tienen OAuth habilitado. Con un nombre de servidor, inicia el flujo de OAuth para ese servidor.

Si no se detecta un entorno gráfico, o si pasa --no-browser, jsmcp auth <server> imprime la URL de autorización y espera la devolución de llamada de localhost o una URL/código de devolución de llamada pegado.

Servicio de usuario de systemd

Este repositorio incluye systemd/jsmcp.service, una unidad de usuario que inicia jsmcp server desde la CLI instalada globalmente.

Instálelo con:

npm install -g .
mkdir -p ~/.config/systemd/user
ln -sfn "$PWD/systemd/jsmcp.service" ~/.config/systemd/user/jsmcp.service
systemctl --user daemon-reload
systemctl --user enable --now jsmcp.service

Comandos útiles:

systemctl --user status jsmcp.service
journalctl --user -u jsmcp.service -f
systemctl --user restart jsmcp.service

La unidad registrada inicia el ajuste preestablecido predeterminado en el puerto del demonio predeterminado y resuelve jsmcp a través del shell de inicio de sesión real del usuario desde getent passwd.

Configuración

El archivo de configuración puede ser JSON o YAML y utiliza estas claves de nivel superior:

• servers: definiciones de servidor

• presets: anulaciones opcionales para qué servidores y herramientas se exponen al agente

Los nombres de los servidores deben ser identificadores de JavaScript válidos porque execute_code() los expone directamente como globales.

jsmcp acepta tanto el estilo de configuración MCP de OpenCode como el estilo MCP de Claude Code superpuesto para los campos comunes:

• servidores locales: type: "local" o type: "stdio"

• servidores remotos: type: "remote", type: "http" o type: "sse"

• comandos: ya sea command: ["cmd", "arg1"] o command: "cmd" con args: ["arg1"]

• variables de entorno: ya sea environment o env

Campos admitidos en servers.<name>:

• type: obligatorio; uno de local, stdio, remote, http, sse

• description: cadena opcional que se muestra en list_servers()

• enabled: booleano opcional; el valor predeterminado es true

• timeout: número opcional en milisegundos utilizado para el descubrimiento inicial de herramientas

Para servidores locales / stdio:

• command: obligatorio; cadena no vacía o matriz no vacía

• args: matriz opcional; se añade a command cuando command es una cadena, y también se acepta cuando command es una matriz

• env: objeto opcional de variables de entorno

• environment: objeto opcional de variables de entorno; se fusiona con env, y prevalece en caso de claves duplicadas

• cwd: directorio de trabajo opcional

Para servidores remotos / HTTP / SSE:

• url: cadena obligatoria

• headers: objeto opcional de encabezados de solicitud

• oauth: configuración de OAuth opcional

Formas de oauth admitidas:

• omitido, null o true: habilitar OAuth con comportamiento predeterminado

• false: deshabilitar OAuth para ese servidor

• objeto con cualquiera de:

  • clientId

  • clientSecret

  • scope

Sustituciones de valores admitidas en campos de cadena:

• {env:NAME}: expandir desde el entorno actual

• ${NAME}: expansión de entorno al estilo Claude Code

• ${NAME:-default}: expansión al estilo Claude Code con alternativa

• {file:path}: reemplazar con el contenido del archivo

Para {file:path}:

• las rutas relativas se resuelven en relación con el directorio del archivo de configuración

• ~/... se resuelve desde el directorio de inicio del usuario

• las rutas absolutas se utilizan tal cual

Si se omite presets, el ajuste preestablecido predeterminado incluye todos los servidores con enabled !== false y permite todas las herramientas de ese servidor.

Si presets está presente, es un objeto de nombres de ajustes preestablecidos. Cada ajuste preestablecido es un objeto de anulaciones por servidor superpuestas sobre las definiciones del servidor:

• presets.default: anulaciones opcionales para el ajuste preestablecido predeterminado

• cualquier otro nombre de ajuste preestablecido, como presets.work: anulaciones adicionales con nombre

Dentro de un ajuste preestablecido, las reglas del servidor funcionan así:

• regla de servidor omitida: usar la definición del servidor tal cual

• true: incluir ese servidor y permitir todas sus herramientas

• false: excluir ese servidor de ese ajuste preestablecido

• "tool_name": incluir solo esa herramienta exacta

• las entradas de la matriz pueden ser:

  • cadenas de nombres de herramientas exactas

  • selectores { "regex": "..." }

  • selectores { "glob": "..." }

Si un servidor tiene enabled: false en servers, añadirlo a un ajuste preestablecido lo habilita para ese ajuste preestablecido.

Ejemplo:

{
 "servers": {
 "math": {
 "type": "stdio",
 "description": "Basic arithmetic tools",
 "command": "node",
 "args": ["/absolute/path/to/math-server.js"],
 "env": {
 "LOG_LEVEL": "debug"
 },
 "cwd": "${PWD}"
 },
 "docs": {
 "type": "http",
 "description": "Documentation search and retrieval",
 "url": "https://example.com/mcp",
 "headers": {
 "Authorization": "Bearer ${DOCS_TOKEN}"
 },
 "oauth": {
 "scope": "docs.read"
 }
 }
 },
 "presets": {
 "default": {
 "math": ["add", { "glob": "mul_*" }],
 "docs": [{ "regex": "(search|fetch)" }]
 },
 "work": {
 "docs": true
 }
 }
}

Notas de compatibilidad:

• Se admiten env, type: "stdio", type: "http", type: "sse" y command más args al estilo Claude Code

• También se admiten type: "local", type: "remote", matrices de comandos y environment al estilo OpenCode

• Aún no se admiten características específicas de Claude Code como headersHelper y campos avanzados de OAuth como callbackPort o authServerMetadataUrl

Los tokens de OAuth y el estado de registro se almacenan en $XDG_DATA_HOME/jsmcp/oauth.json o ~/.local/share/jsmcp/oauth.json.

Herramientas expuestas

• list_servers

• list_tools

• execute_code

• fetch_logs

• clear_logs

Comportamiento

• los servidores en el ajuste preestablecido predeterminado se inician cuando se inicia jsmcp

• list_servers() es el primer paso obligatorio para que el agente pueda aprender qué capacidades están disponibles

• debe llamar a list_tools(server) antes de usar un servidor en execute_code() para conocer los nombres exactos de las herramientas, alias y esquemas

• list_tools(server) devuelve solo las herramientas permitidas para ese servidor en el ajuste preestablecido

• execute_code({ code, data?, timeoutMs? }) no gestiona el ciclo de vida del servidor; solo puede usar servidores que ya estén iniciados

• prefiera execute_code({ code, ... }) siempre que el trabajo requiera más de una sola llamada a una herramienta

• console.log, console.info, console.warn y console.error dentro de execute_code() se almacenan para fetch_logs()

• fetch_logs() vacía el búfer de registro al leer

execute_code

execute_code ejecuta JavaScript como el cuerpo de una función asíncrona.

Los servidores iniciados se inyectan como globales. Cada herramienta MCP permitida se convierte en una función en ese objeto de servidor. Prefiera los alias con guion bajo cuando estén disponibles.

Si pasa data, se expone al script como la variable global data. Esto es útil para cadenas o valores estructurados que de otro modo necesitarían escape dentro de la cadena de código.

Debe llamar a list_tools(server) antes de usar un servidor en execute_code(). Para trabajos de varios pasos, prefiera escribir JavaScript en lugar de intentar encadenar mentalmente varias llamadas a herramientas.

Ejemplo:

return await math.add({ a: 2, b: 5 });

Con datos:

return data.message;

Si la herramienta MCP devuelve structuredContent, eso es a lo que se resuelve la llamada de JavaScript. Por lo tanto, el ejemplo anterior puede devolver:

{
 "sum": 7
}

Si un nombre de herramienta no es un identificador de JavaScript válido, prefiera su alias con guion bajo:

return await math.tool_name({ value: 1 });

El nombre original de la herramienta sigue funcionando con el acceso entre corchetes:

return await math["tool-name"]({ value: 1 });

Maintenance

Resources

• NPM Package
• GitHub Repository
Need Help?Related Servers