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 중 정확히 하나만 존재해야 합니다.

이유

에이전트가 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는 원시 MCP/JSON-RPC 메시지를 WebSocket을 통해 server로 프록시하는 stdio MCP 서버를 노출합니다. --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 엔드포인트를 통해 5개의 메타 도구를 노출합니다:

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를 반환합니다.

원격 서버에 대한 OAuth를 관리하려면 jsmcp auth를 사용하세요. 인자 없이 실행하면 OAuth가 활성화된 원격 서버 목록을 표시합니다. 서버 이름을 지정하면 해당 서버에 대한 OAuth 흐름을 시작합니다.

그래픽 환경이 감지되지 않거나 --no-browser를 전달하면 jsmcp auth <server>는 인증 URL을 출력하고 로컬 호스트 콜백 또는 붙여넣은 콜백 URL/코드를 기다립니다.

systemd 사용자 서비스

이 저장소에는 전역적으로 설치된 CLI에서 jsmcp server를 시작하는 사용자 유닛인 systemd/jsmcp.service가 포함되어 있습니다.

다음 명령어로 설치하세요:

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의 사용자 실제 로그인 셸을 통해 jsmcp를 확인합니다.

설정

설정 파일은 JSON 또는 YAML일 수 있으며 다음 최상위 키를 사용합니다:

• servers: 서버 정의

• presets: 에이전트에 노출되는 서버 및 도구에 대한 선택적 재정의

execute_code()가 서버들을 전역 변수로 직접 노출하므로 서버 이름은 유효한 JavaScript 식별자여야 합니다.

jsmcp는 공통 필드에 대해 OpenCode MCP 설정 스타일과 중복되는 Claude Code MCP 스타일을 모두 허용합니다:

• 로컬 서버: type: "local" 또는 type: "stdio"

• 원격 서버: type: "remote", type: "http" 또는 type: "sse"

• 명령어: command: ["cmd", "arg1"] 또는 args: ["arg1"]이 포함된 command: "cmd"

• 환경 변수: environment 또는 env

지원되는 servers.<name> 필드:

• type: 필수; local, stdio, remote, http, sse 중 하나

• description: list_servers()에 표시되는 선택적 문자열

• enabled: 선택적 불리언; 기본값은 true

• timeout: 초기 도구 검색에 사용되는 밀리초 단위의 선택적 숫자

로컬 / stdio 서버의 경우:

• command: 필수; 비어 있지 않은 문자열 또는 배열

• args: 선택적 배열; 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도 지원됩니다.

• headersHelper와 같은 Claude Code 전용 기능이나 callbackPort 또는 authServerMetadataUrl과 같은 고급 OAuth 필드는 아직 지원되지 않습니다.

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