jsmcp

jsmcp 适用于代理（agent）需要执行的操作不仅仅是单个 MCP 工具调用的情况。

大多数 MCP 客户端在处理单次工具调用时表现出色，但在以下工作场景中会显得笨拙：

• 多次相关的工具调用

• 基于先前结果的分支逻辑

• 循环、重试或结果聚合

• 在下一次调用前转换工具输出

jsmcp 通过将已批准的 MCP 工具公开为 JavaScript 命名空间来解决这个问题。它不再强迫模型处理许多单独的工具调用，而是让模型先发现可用资源，然后编写少量 JavaScript 代码来以编程方式使用这些工具。

实际上，这意味着：

• 代理首先了解有哪些服务器和工具可用，同时 jsmcp 会将访问权限限制为您在预设（preset）中允许的服务器和工具

• 代理随后可以编写 JavaScript 来完成多步骤工作

• 日志与返回值保持分离，使代码更易于理解

配置从 $XDG_CONFIG_HOME/jsmcp/ 读取；如果未设置 XDG_CONFIG_HOME，则从 ~/.config/jsmcp/ 读取。该目录下必须且仅能存在 config.json、config.yaml 或 config.yml 中的一个。

为什么使用

当您希望代理将 MCP 工具视为一个小型的可编程 API 界面，而不是一系列孤立的按钮点击时，请使用 jsmcp。

这在代理需要执行以下操作时特别有用：

• 组合来自多个 MCP 工具的结果

• 跨一个或多个 MCP 服务器编写工作流脚本

• 在代码中做出决策，而不是在工具调用之间反复重新规划

• 将工具访问权限限制在经过审查的预设范围内

Related MCP server: MCPMan

安装

npm install -g @alesya_h/jsmcp

或者在不全局安装的情况下运行：

npx @alesya_h/jsmcp run

运行

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

如果您是从源码检出而不是从已安装的包运行，请将 jsmcp 替换为 node src/index.js，例如 node src/index.js run。

run 直接通过 stdio 启动元 MCP 服务器。

server 在 ws://<bind>:<port>/mcp 上启动一个长驻守护进程，加载选定的预设并保持底层 MCP 服务器连接处于活跃状态。它默认绑定到 0.0.0.0，并接受 --bind <host> 来选择其他绑定地址。

client 公开一个 stdio MCP 服务器，将原始 MCP/JSON-RPC 消息通过 WebSocket 代理到 server。它接受 --host <host> 和 --port <number> 来选择要连接的守护进程，可以选择传递 --profile <name> 以要求守护进程运行预期的预设，并接受 --session-id <id> 以在客户端重新连接时重用相同的守护进程端日志会话。

run、server 和 client 都接受一个可选的预设作为位置参数或 --profile <name>。默认守护进程端口为 41528。如果省略 client --session-id，客户端会生成一个随机会话 ID，并在该客户端进程的重新连接期间重用它。

在首次启动 server 时，jsmcp 会在 $XDG_CONFIG_HOME/jsmcp/api-key.txt（如果未设置 XDG_CONFIG_HOME，则为 ~/.config/jsmcp/api-key.txt）创建一个 API 密钥。守护进程 WebSocket 和 HTTP API 请求必须在 X-JSMCP-API-Key 标头中包含该密钥；未经身份验证的请求将收到 401。

守护进程还通过一个 JSON HTTP 端点公开了五个元工具：

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>

请求体是一个匹配所选 MCP 工具参数的 JSON 对象。HTTP 调用者可以在查询字符串中包含 sessionId 以使用稳定的守护进程端日志会话。他们可以包含 profile 以要求守护进程运行预期的预设；不匹配将返回 409。

使用 jsmcp auth 管理远程服务器的 OAuth。如果不带参数，它会列出启用了 OAuth 的远程服务器。使用服务器名称，它会启动该服务器的 OAuth 流程。

如果未检测到图形环境，或者如果您传递了 --no-browser，jsmcp auth <server> 会打印授权 URL 并等待 localhost 回调或粘贴的回调 URL/代码。

systemd 用户服务

此仓库包含 systemd/jsmcp.service，这是一个从全局安装的 CLI 启动 jsmcp server 的用户单元。

使用以下命令安装它：

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

常用命令：

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

检入的单元在默认守护进程端口上启动默认预设，并通过 getent passwd 从用户的实际登录 shell 解析 jsmcp。

配置

配置文件可以是 JSON 或 YAML，并使用以下顶级键：

• servers: 服务器定义

• presets: 可选的覆盖项，用于指定向代理公开哪些服务器和工具

服务器名称必须是有效的 JavaScript 标识符，因为 execute_code() 会将它们直接公开为全局变量。

jsmcp 接受 OpenCode MCP 配置风格以及重叠的 Claude Code MCP 风格的通用字段：

• 本地服务器: type: "local" 或 type: "stdio"

• 远程服务器: type: "remote"、type: "http" 或 type: "sse"

• 命令: command: ["cmd", "arg1"] 或 command: "cmd" 配合 args: ["arg1"]

• 环境变量: environment 或 env

支持的 servers.<name> 字段：

• type: 必需；local、stdio、remote、http、sse 之一

• description: 可选字符串，在 list_servers() 中显示

• enabled: 可选布尔值；默认为 true

• timeout: 可选数字（毫秒），用于初始工具发现

对于本地 / stdio 服务器：

• command: 必需；非空字符串或非空数组

• args: 可选数组；当 command 为字符串时附加到 command，当 command 为数组时也接受

• env: 可选环境变量对象

• environment: 可选环境变量对象；与 env 合并，重复键时胜出

• cwd: 可选工作目录

对于远程 / HTTP / SSE 服务器：

• url: 必需字符串

• headers: 可选请求头对象

• oauth: 可选 OAuth 配置

支持的 oauth 形式：

• 省略、null 或 true: 启用具有默认行为的 OAuth

• false: 禁用该服务器的 OAuth

• 包含以下任意项的对象：

  • clientId

  • clientSecret

  • scope

字符串字段中支持的值替换：

• {env:NAME}: 从当前环境变量展开

• ${NAME}: Claude Code 风格的环境变量展开

• ${NAME:-default}: 带有回退的 Claude Code 风格展开

• {file:path}: 替换为文件内容

对于 {file:path}：

• 相对路径相对于配置文件目录解析

• ~/... 从用户主目录解析

• 绝对路径按原样使用

如果省略 presets，默认预设包含所有 enabled !== false 的服务器，并允许该服务器的所有工具。

如果存在 presets，它是一个预设名称对象。每个预设都是一个在服务器定义之上分层的每个服务器覆盖对象：

• presets.default: 默认预设的可选覆盖

• 任何其他预设名称，例如 presets.work: 额外的命名预设覆盖

在预设内，服务器规则的工作方式如下：

• 省略服务器规则: 按原样使用服务器定义

• true: 包含该服务器并允许其所有工具

• false: 从该预设中排除该服务器

• "tool_name": 仅包含该精确工具

• 数组条目可以是：

  • 精确的工具名称字符串

  • { "regex": "..." } 选择器

  • { "glob": "..." } 选择器

如果服务器在 servers 中设置了 enabled: false，将其添加到预设中会为该预设启用它。

示例：

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

兼容性说明：

• 支持 Claude Code 风格的 env、type: "stdio"、type: "http"、type: "sse" 以及 command 加 args

• 也支持 OpenCode 风格的 type: "local"、type: "remote"、命令数组和 environment

• 尚不支持 Claude Code 特有的功能，如 headersHelper 以及高级 OAuth 字段（如 callbackPort 或 authServerMetadataUrl）

OAuth 令牌和注册状态存储在 $XDG_DATA_HOME/jsmcp/oauth.json 或 ~/.local/share/jsmcp/oauth.json 中。

公开的工具

• list_servers

• list_tools

• execute_code

• fetch_logs

• clear_logs

行为

• 默认预设中的服务器在 jsmcp 启动时启动

• list_servers() 是必需的第一步，以便代理了解有哪些功能可用

• 在 execute_code() 中使用服务器之前，必须调用 list_tools(server)，以便了解确切的工具名称、别名和模式

• list_tools(server) 仅返回预设中允许该服务器使用的工具

• execute_code({ code, data?, timeoutMs? }) 不管理服务器生命周期；它只能使用已经启动的服务器

• 当工作需要超过单个工具调用时，优先使用 execute_code({ code, ... })

• execute_code() 内部的 console.log、console.info、console.warn 和 console.error 会被存储以供 fetch_logs() 使用

• fetch_logs() 在读取时会清空日志缓冲区

execute_code

execute_code 将 JavaScript 作为异步函数体运行。

已启动的服务器被注入为全局变量。每个允许的 MCP 工具都成为该服务器对象上的一个函数。如果可用，优先使用下划线别名。

如果您传递 data，它将作为全局变量 data 暴露给脚本。这对于在代码字符串内部需要转义的字符串或结构化值非常有用。

在 execute_code() 中使用服务器之前，您应该调用 list_tools(server)。对于多步骤工作，优先编写 JavaScript，而不是试图在脑海中串联多个工具调用。

示例：

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

使用数据：

return data.message;

如果 MCP 工具返回 structuredContent，这就是 JavaScript 调用解析的结果。因此，上面的示例可以返回：

{
 "sum": 7
}

如果工具名称不是有效的 JavaScript 标识符，请优先使用其下划线别名：

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

原始工具名称仍然可以通过括号访问：

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

Maintenance

Resources

• NPM Package
• GitHub Repository
Need Help?Related Servers