项目简介

这是一个专门为AI代理（如Claude、Cursor）设计的Model Context Protocol (MCP) 服务器实现。它利用Rust语言内嵌V8 JavaScript引擎，将一个具备持久化状态能力的JavaScript运行时暴露为AI可调用的工具。通过MCP协议，AI代理可以请求服务器执行任意同步JavaScript代码，并在多次调用之间维持变量和状态，这得益于其支持将V8堆快照存储到AWS S3或本地文件系统。

主要功能点

• V8 JavaScript 执行: 在一个安全、隔离的V8环境中运行AI提供的JavaScript代码。
• 堆快照持久化: 支持将V8运行时的内存状态（堆）保存为快照，并在后续执行时恢复，实现跨调用的状态记忆。
• 多种存储后端: 可以选择将堆快照存储在AWS S3云存储桶中，或存储在本地文件系统的指定目录中。
• 标准MCP协议支持: 完全实现了Model Context Protocol，确保与兼容的AI客户端（如Claude Desktop, Cursor）无缝集成。
• 暴露为AI工具: 主要功能 'run_js' 作为MCP工具注册，AI代理通过调用此工具来执行JavaScript代码并获取结果。

安装步骤

服务器提供了一个简便的安装脚本。打开终端，执行以下命令：

curl -fsSL https://raw.githubusercontent.com/r33drichards/mcp-js/main/install.sh | sudo bash

此脚本会自动下载适合您平台的最新版本服务器二进制文件，并安装到 '/usr/local/bin/mcp-v8'。执行时可能需要输入您的用户密码。

对于高级用户，也可以选择从源代码构建，具体步骤请参考仓库的README文件。

服务器配置 (MCP 客户端配置)

MCP服务器一旦安装，需要由MCP客户端（如AI代理应用）来启动和管理。配置方式通常是在客户端的设置中添加一个MCP服务器定义。这个定义通常包含一个服务器名称、启动服务器的命令及参数。

本服务器的启动命令是安装后生成的二进制文件路径，默认为 '/usr/local/bin/mcp-v8'。它需要一个参数来指定堆快照的存储位置。

客户端配置示例（概念性说明，请根据您的客户端文档进行实际配置）：

• 选择 S3 存储: 使用 '--s3-bucket <bucket-name>' 参数。例如，命令为 '/usr/local/bin/mcp-v8 --s3-bucket my-js-heap-bucket'。您需要替换 'my-js-heap-bucket' 为您实际的S3存储桶名称。使用S3需要确保您的环境已配置AWS凭证。
• 选择本地文件系统存储: 使用 '--directory-path <path>' 参数。例如，命令为 '/usr/local/bin/mcp-v8 --directory-path /path/to/your/local/heaps'。您需要替换 '/path/to/your/local/heaps' 为您希望存储堆快照的本地目录路径。

重要提示: 您必须且只能指定 '--s3-bucket' 或 '--directory-path' 中的一个参数。如果没有指定，服务器将默认使用S3存储，默认存储桶名称为 'test-mcp-js-bucket'。

配置完成后，根据您使用的AI客户端指示重启应用，服务器将由客户端在需要时自动启动。

基本使用方法

一旦服务器在您的AI客户端中配置并启用，您就可以通过与AI代理交互来使用这个JavaScript工具。

例如，您可以直接向AI代理提问：

• “运行这段 JavaScript 代码：'1 + 2'”
• “运行这段代码，并在下次调用时记住 'x' 的值：'try { x = x + 1 } catch (e) { x = 1 } x;'”

请注意，这个JavaScript环境有一些限制：

• 不支持 'async'/'await' 或 Promises。
• 不支持网络请求（如 'fetch'）。
• 'console.log' 的输出不会显示给AI，要返回结果，请确保您希望返回的值是代码的最后一行。
• 不支持文件系统或环境变量访问。
• 不支持安装或导入npm包。
• 不支持定时器（'setTimeout', 'setInterval'）。
• 这不是浏览器环境，不支持DOM或浏览器API。

您的AI代理会通过MCP协议调用服务器的 'run_js' 工具，执行您提供的代码，并将结果返回给您。得益于堆快照功能，如果您在代码中修改了全局变量或创建了对象，这些状态可以在后续对同一“会话”或“堆”的调用中得以保留。