mcp-v8: 基于V8 JavaScript的MCP服务器

这是一个基于Rust的模型上下文协议（MCP）服务器，它提供了一个V8 JavaScript运行时作为AI代理（如Claude和Cursor）的工具。支持通过S3或本地文件系统持久化堆快照，并且准备好与现代AI开发环境集成。

功能

• V8 JavaScript执行：在安全、隔离的V8引擎中运行任意JavaScript代码。
• 堆快照：在运行之间持久化并恢复V8堆状态，支持S3和本地文件存储。
• 无状态模式：可选模式，不保存堆状态的新执行，适合无服务器环境。
• MCP协议：实现模型上下文协议，以便无缝集成到Claude、Cursor和其他MCP客户端。
• 可配置存储：运行时可以选择S3、本地目录或无状态模式。
• 多种传输方式：支持stdio、HTTP和SSE（服务器发送事件）传输协议。

安装

使用提供的安装脚本安装mcp-v8：

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

这将自动下载并安装最新版本到你的平台的/usr/local/bin/mcp-v8（可能需要输入密码）。

---

高级用户：如果你希望从源码构建，请参阅本文档末尾的从源码构建部分。

命令行参数

mcp-v8支持以下命令行参数：

• --s3-bucket <bucket>：使用AWS S3进行堆快照。指定S3桶名。（与--stateless冲突）
• --directory-path <path>：使用本地目录进行堆快照。指定目录路径。（与--stateless冲突）
• --stateless：以无状态模式运行 - 不保存或加载任何堆快照。每次JavaScript执行都从一个新的V8隔离区开始。（与--s3-bucket和--directory-path冲突）
• --http-port <port>：在指定端口启用HTTP传输。如果没有提供，则服务器使用stdio传输（默认）。
• --sse-port <port>：在指定端口启用SSE（服务器发送事件）传输。（与--http-port冲突）

注意：对于堆存储，如果未提供--s3-bucket、--directory-path或--stateless，服务器将默认使用/tmp/mcp-v8-heaps作为本地目录。

快速开始

安装后，你可以直接运行服务器。选择以下选项之一：

Stdio传输（默认）

# 使用S3进行堆存储（推荐用于云/持久使用）
mcp-v8 --s3-bucket my-bucket-name

# 使用本地文件系统目录进行堆存储（推荐用于本地开发）
mcp-v8 --directory-path /tmp/mcp-v8-heaps

# 使用无状态模式 - 不进行堆持久化（推荐用于一次性计算）
mcp-v8 --stateless

HTTP传输

HTTP传输使用HTTP/1.1升级机制从HTTP切换到MCP协议：

# 在端口8080启动HTTP服务器，使用本地文件系统存储
mcp-v8 --directory-path /tmp/mcp-v8-heaps --http-port 8080

# 在端口8080启动HTTP服务器，使用S3存储
mcp-v8 --s3-bucket my-bucket-name --http-port  8080

# 在端口8080启动HTTP服务器，使用无状态模式
mcp-v8 --stateless --http-port 8080

HTTP传输适用于：

• 网络MCP客户端
• 使用MCP Inspector等工具进行测试和调试
• 容器化部署
• 远程MCP服务器访问

SSE传输

服务器发送事件（SSE）传输用于流式响应：

# 在端口8081启动SSE服务器，使用本地文件系统存储
mcp-v8 --directory-path /tmp/mcp-v8-heaps --sse-port 8081

# 在端口8081启动SSE服务器，使用无状态模式
mcp-v8 --stateless --sse-port 8081

无状态模式 vs 有状态模式

无状态模式（--stateless）

无状态模式在每个JavaScript执行中使用新的V8隔离区，没有堆持久化。

优点：

• 更快的执行：没有快照创建/序列化的开销
• 无存储I/O：不读写堆文件
• 新的隔离区：每次JS执行都是干净的开始
• 适用于：一次性计算、无状态函数、无服务器环境

示例用例：简单的计算、数据转换或任何不需要在执行之间持久化状态的场景。

有状态模式（默认）

有状态模式使用S3或本地文件系统存储在执行之间持久化V8堆状态。

优点：

• 状态持久化：变量和对象在运行之间保持不变
• 后续运行更快：预加载的上下文和数据
• 适用于：交互会话、随着时间建立复杂的状态

示例用例：增量构建数据结构、维护会话状态或重用昂贵的计算。

集成

Claude桌面版

1. 按上述方法安装服务器。
2. 打开Claude桌面版 → 设置 → 开发者 → 编辑配置。
3. 将你的服务器添加到claude_desktop_config.json：

有状态模式与S3：

{
  "mcpServers": {
    "js": {
      "command": "/usr/local/bin/mcp-v8 --s3-bucket my-bucket-name"
    }
  }
}

无状态模式：

{
  "mcpServers": {
    "js": {
      "command": "/usr/local/bin/mcp-v8 --stateless"
    }
  }
}

4. 重启Claude桌面版。新工具将在锤子图标下出现。

Cursor

1. 按上述方法安装服务器。
2. 在项目根目录创建或编辑.cursor/mcp.json：

有状态模式与本地文件系统：

{
  "mcpServers": {
    "js": {
      "command": "/usr/local/bin/mcp-v8 --directory-path /tmp/mcp-v8-heaps"
    }
  }
}

无状态模式：

{
  "mcpServers": {
    "js": {
      "command": "/usr/local/bin/mcp-v8 --stateless"
    }
  }
}

3. 重启Cursor。MCP工具将在UI中可用。

通过Railway的Claude（Web/云）

你也可以使用Railway上的托管版本而不需本地安装：

选项1：使用Claude设置

1. 转到Claude的连接器设置页面
2. 添加一个新自定义连接器：
   • 名称："mcp-v8"
   • URL：https://mcp-js-production.up.railway.app/sse

选项2：使用Claude Code CLI

claude mcp add mcp-v8 -t sse https://mcp-js-production.up.railway.app/sse

然后通过运行claude并询问：“运行这个JavaScript：[1,2,3].map(x => x * 2)”来测试。

示例用法

• 向Claude或Cursor询问：“运行这个JavaScript：1 + 2”
• 使用堆快照在运行之间持久化状态。

堆存储选项

你可以使用以下命令行参数配置堆存储：

• S3：--s3-bucket <bucket>
  • 示例：mcp-v8 --s3-bucket my-bucket-name
  • 需要在环境中设置AWS凭证。
  • 适用于云部署和跨实例共享状态。
• 文件系统：--directory-path <path>
  • 示例：mcp-v8 --directory-path /tmp/mcp-v8-heaps
  • 在本地磁盘上存储堆快照。
  • 适用于本地开发和测试。
• 无状态：--stateless
  • 示例：mcp-v8 --stateless
  • 不进行堆持久化 - 每次执行都是全新的开始。
  • 适用于一次性计算和无服务器环境。

注意：一次只能使用一种存储选项。如果提供了多个选项，服务器将返回错误。

限制

尽管mcp-v8提供了一个强大且持久的JavaScript执行环境，但其运行时存在一些限制。

• 不支持async/await或Promises：不支持异步JavaScript。所有代码必须是同步的。
• 不支持fetch或网络访问：没有内置的方式进行HTTP请求或访问网络。
• 不支持console.log或标准输出：console.log或其他类似函数的输出不会显示。要返回结果，请确保你想要的值是代码的最后一行。
• 不支持文件系统访问：运行时不提供对本地文件系统或环境变量的访问。
• 不支持npm install或外部包：不能安装或导入npm包。只有标准JavaScript（ECMAScript）内置功能可用。
• 不支持计时器：如setTimeout和setInterval这样的函数不可用。
• 不支持DOM或浏览器API：这不是一个浏览器环境；没有对window、document或其他特定于浏览器的对象的访问。

---

从源码构建（高级）

如果你希望从源码构建而不是使用安装脚本：

先决条件

• Rust（推荐使用夜间工具链）
• （可选）AWS凭证用于S3存储

构建服务器

cd server
cargo build --release

构建好的二进制文件位于server/target/release/server。如果需要，可以在上面的集成步骤中使用此路径代替/usr/local/bin/mcp-v8。