jsmcp

jsmcp существует для случаев, когда агенту нужно выполнить больше, чем один вызов инструмента MCP.

Большинство клиентов MCP отлично справляются с вызовом одного инструмента за раз, но становятся неудобными, когда работа требует:

• нескольких связанных вызовов инструментов

• логики ветвления на основе предыдущих результатов

• циклов, повторных попыток или агрегации результатов

• преобразования вывода инструмента перед следующим вызовом

jsmcp решает эту проблему, предоставляя одобренные инструменты MCP в виде пространств имен JavaScript. Вместо того чтобы заставлять модель выполнять множество отдельных вызовов инструментов, она может узнать, что доступно, а затем написать небольшой фрагмент кода JavaScript для программного использования этих инструментов.

На практике это означает:

• агент сначала узнает, какие серверы и инструменты доступны, в то время как jsmcp ограничивает доступ только теми серверами и инструментами, которые вы разрешили в пресете

• затем агент может написать JavaScript для многоэтапной работы

• логи остаются отделенными от возвращаемых значений, поэтому код легче анализировать

Конфигурация считывается из $XDG_CONFIG_HOME/jsmcp/ или, если XDG_CONFIG_HOME не задан, из ~/.config/jsmcp/. Там должен существовать ровно один файл: config.json, config.yaml или config.yml.

Зачем

Используйте jsmcp, когда хотите, чтобы агенты относились к инструментам MCP скорее как к небольшой программируемой поверхности API, чем как к последовательности изолированных нажатий кнопок.

Это особенно полезно, когда агенту нужно:

• объединить результаты нескольких инструментов 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 запускает мета-сервер MCP напрямую через stdio.

server запускает долгоживущий демон на ws://<bind>:<port>/mcp, загружая выбранный пресет один раз и поддерживая соединения с базовым сервером MCP в активном состоянии. По умолчанию он привязывается к 0.0.0.0 и принимает --bind <host> для выбора другого адреса привязки.

client предоставляет stdio-сервер MCP, который проксирует необработанные сообщения MCP/JSON-RPC на server через WebSocket. Он принимает --host <host> и --port <number> для выбора демона, к которому нужно подключиться, может опционально передать --profile <name>, чтобы потребовать, чтобы демон запускал ожидаемый пресет, и принимает --session-id <id> для повторного использования одного и того же сеанса логов на стороне демона при переподключениях клиента.

run, server и client принимают необязательный пресет в качестве позиционного аргумента или --profile <name>. Порт демона по умолчанию — 41528. Если client --session-id опущен, клиент генерирует случайный идентификатор сеанса и повторно использует его для переподключений в течение этого процесса клиента.

При первом запуске server jsmcp создает ключ API в $XDG_CONFIG_HOME/jsmcp/api-key.txt или ~/.config/jsmcp/api-key.txt, если XDG_CONFIG_HOME не задан. Запросы к 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>

Тело запроса — это объект JSON, соответствующий аргументам выбранного инструмента MCP. HTTP-вызывающие могут включить sessionId в строку запроса, чтобы использовать стабильный сеанс логов на стороне демона. Они могут включить profile, чтобы потребовать, чтобы демон запускал ожидаемый пресет; при несовпадении возвращается 409.

Используйте jsmcp auth для управления OAuth для удаленных серверов. Без аргументов он перечисляет удаленные серверы, для которых включен OAuth. С именем сервера он запускает процесс OAuth для этого сервера.

Если графическая среда не обнаружена или если вы передали --no-browser, jsmcp auth <server> выводит URL авторизации и ожидает либо локальный обратный вызов, либо вставленный URL/код обратного вызова.

Пользовательская служба systemd

Этот репозиторий включает systemd/jsmcp.service, пользовательский юнит, который запускает jsmcp server из глобально установленного CLI.

Установите его с помощью:

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

Добавленный юнит запускает пресет по умолчанию на порту демона по умолчанию и разрешает jsmcp через фактическую оболочку входа пользователя из getent passwd.

Конфигурация

Файл конфигурации может быть в формате 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": "..." }

Если сервер имеет enabled: false в servers, добавление его в пресет включает его для этого пресета.

Пример:

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

Примечания о совместимости:

• поддерживаются env, type: "stdio", type: "http", type: "sse" и command плюс args в стиле Claude Code

• также поддерживаются type: "local", type: "remote", массивы команд и environment в стиле OpenCode

• функции, специфичные для 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() — обязательный первый шаг, чтобы агент мог узнать, какие возможности доступны

• вы должны вызвать list_tools(server) перед использованием сервера в execute_code(), чтобы знать точные имена инструментов, псевдонимы и схемы

• list_tools(server) возвращает только инструменты, разрешенные для этого сервера в пресете

• execute_code({ code, data?, timeoutMs? }) не управляет жизненным циклом сервера; он может использовать только те серверы, которые уже запущены

• отдавайте предпочтение execute_code({ code, ... }) всякий раз, когда работа требует больше одного вызова инструмента

• console.log, console.info, console.warn и console.error внутри execute_code() сохраняются для fetch_logs()

• fetch_logs() очищает буфер логов при чтении

execute_code

execute_code выполняет JavaScript как тело асинхронной функции.

Запущенные серверы внедряются как глобальные переменные. Каждый разрешенный инструмент MCP становится функцией в этом объекте сервера. Отдавайте предпочтение псевдонимам с подчеркиванием, если они доступны.

Если вы передаете data, она предоставляется скрипту как глобальная переменная data. Это полезно для строк или структурированных значений, которые в противном случае потребовали бы экранирования внутри строки кода.

Вам следует вызвать list_tools(server) перед использованием сервера в execute_code(). Для многоэтапной работы предпочтительнее писать 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 });