AI导哈

JavaScript编程工具调用MCP服务器

一个运行JavaScript的编程工具调用（PTC）MCP服务器实现，为大型语言模型（LLM）提供复杂多步工具编排能力，支持在QuickJS WASM沙箱中安全执行。

  • by keyboqrd
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 keyboqrd/js-ptc-mcp

使用说明

调用MCP服务器的JavaScript编程工具

中文文档 (README-CN.md)

MCP服务器实现 程序化工具调用（PTC） 它运行JavaScript。

编程工具使用的概念是由Anthropic Claude API开创的，它允许模型编写代码，在一个回合内协调多个工具。该项目提供了一个 开源、模型无关的替代方案 对于本地PTC不可用的环境，通过标准MCP协议为任何LLM（OpenAI、Gemini、本地模型）带来相同的强大编排功能。

此服务器允许大型语言模型（LLM）在安全、隔离的环境中执行复杂的多步骤工具编排 QuickJS WASM沙盒，将执行逻辑从LLM推理循环转移到确定性本地执行。

为什么选择PTC？

传统的LLM工具使用依赖于连续的往返(原因->调用工具A->等待->原因->调用方法B).PTC将这些多步骤依赖关系压缩到单个程序执行脚本中，提供：

  • 减少延迟：通过在本地执行编排来消除网络和推理开销。
  • 并发：使用以下命令实现多个MCP工具的真正并行执行 Promise.all.
  • 控制流程：直接在沙箱中处理循环、条件和数据聚合，而不依赖于LLM上下文。
  • 上下文效率：仅将最终的蒸馏数据结构返回LLM上下文窗口。

快速开始

看 技能.md 关于使用的简明指南 run_js_code 用于工具编排、并行执行和数据聚合。

用法

PTC MCP支持两种不同的架构，具体取决于您的部署拓扑。

模式A：网关模式（适用于Cursor、Claude Desktop、Gemini CLI等）

使用STDIO作为透明代理运行。它根据配置动态生成本地子MCP服务器，并在内部执行JS微循环。

  1. 配置子服务器：创建一个 sub-mcp-servers.json 在项目根目录中定义底层工具：

    {
  "chrome": {
    "command": "npx",
    "args": ["-y", "chrome-devtools-mcp@latest"]
  },
  "fs": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
  }
}

  2. 添加到您的客户:

    • Gemini CLI：
      gemini mcp add ptc npx -y js-ptc-mcp gateway
    • 克劳德代码：
      claude mcp add ptc npx -y js-ptc-mcp gateway
    • 手册（光标/克劳德桌面）： 将以下内容添加到您的 mcpServers 配置：
      {
  "mcpServers": {
    "js-ptc-mcp": {
      "command": "npx",
      "args": ["-y", "js-ptc-mcp", "gateway"]
    }
  }
}

💡 最佳实践：直接工具曝光 为防止端口冲突和资源耗尽，请执行以下操作 非 注册工具，如 chrome-devtools-mcp 如果它们由PTC网关管理，则直接在您的客户端配置中。网关自动公开所有子工具（例如。， chrome.navigate_page)到LLM。

模式B：远程模式（适用于自定义云代理）

使用SSE（服务器发送事件）作为编排器运行。它本身不执行任何工具，而是依赖于 控制反转（IoC） 暂停执行并请求您的安全后端执行操作。

  1. 设置：复制 .env.example 到 .env 并配置您的 PTC_API_KEY.
  2. 运行服务器:
    npx -y js-ptc-mcp remote --port 3000

工作原理：IoC循环

在远程模式下，您的后端必须实现一个简单的循环来处理来自沙盒的工具请求。当沙盒需要工具时，它会返回 need_client_tool 状态。

工作流程：

  1. 呼叫 run_js_code.
  2. 如果状态为 need_client_tool:
    • 在您的安全环境中执行请求的工具。
    • 呼叫 resume_js_code 结果。
  3. 重复，直到状态为 success.

示例：参见 client-sample/remote/backend-service.js 使用MCP SDK完整实现执行循环。

沙盒环境

QuickJS WASM环境是严格沙盒化的，专注于状态机编排、数据操作和 通用逻辑它既可用于复杂的工具链，也可用于简单的纯JavaScript计算或数据转换。

  • 可用: call_client_tool("alias.tool_name", args), print(data), async/await, Promise.all，以及标准ES2022原语（数学、日期、数组、字符串等）。
  • 约束: 不 fetch, 不 定时器(setTimeout)，以及 不 Node.js/浏览器API。所有外部交互都必须通过 call_client_tool.

LLM脚本示例

场景A：纯JavaScript计算

const fib = (n) => n <= 1 ? n : fib(n - 1) + fib(n - 2);
return { result: fib(10) };

场景B：工具编排

print("1. Starting parallel data fetching...");

// Execute multiple underlying MCP tools concurrently
const [user, config] = await Promise.all([
  call_client_tool("db.get_user", { id: 123 }),
  call_client_tool("fs.read_file", { path: "config.json" })
]);

// Handle conditional logic within the sandbox
if (user.isAdmin) {
  print("2. Admin detected, applying special config...");
  await call_client_tool("db.update", { id: 123, status: "active" });
}

// Return the distilled result to the LLM context
return { 
  username: user.name, 
  settings: config.theme 
};

建筑哲学

Understanding the Two Modes

在集成PTC时，开发人员面临着一个关键的分歧： 底层工具位于何处，由谁执行？

  1. 网关模式（STDIO）：标准客户端（如Cursor）是无状态调度器，无法处理挂起/恢复循环。网关模式通过将微环路保持在内部来解决这个问题。它充当本地子进程的黑匣子路由器，使其成为本地开发环境的理想选择。
  2. 远程模式（SSE）：定制云代理（例如SaaS平台）利用专有后端API。从远程沙箱执行这些操作会带来安全风险。远程模式利用SSE将“挂起/中断”信号流式传输到后端，使您的安全环境能够执行工具并将结果注入回。非常适合分布式web架构。

两种模式共享 100%的底层QuickJS确定性状态机，无论部署策略如何，都能确保内存安全和并发性。

发展结构

  • src/core/：引擎的核心（沙盒、逻辑、状态机）。
  • src/modes/：网关（STDIO）和远程（SSE）服务器的实现。
  • client-sample/：示例Node.js客户端演示每种模式。

许可证

麻省理工学院

相关 MCP