336 lines
7.1 KiB
Markdown
336 lines
7.1 KiB
Markdown
# MCP 代码执行工具
|
||
|
||
一个基于 Rust 的工具，提供命令行界面和 MCP（Model Context Protocol）服务器，用于在隔离环境中执行 JavaScript、TypeScript 和 Python 代码。
|
||
|
||
**项目仓库：** <https://github.com/nuwax-ai/run_code_rmcp>
|
||
|
||
[English](./README.md) | 中文
|
||
|
||
## 功能特点
|
||
|
||
- 在隔离环境中执行 JavaScript、TypeScript 和 Python 代码
|
||
- **JavaScript/TypeScript**：由 Deno 运行时驱动
|
||
- **Python**：由 `uv` 驱动，支持自动依赖管理
|
||
- 使用 blake3 哈希自动缓存代码，加快重复执行速度
|
||
- 支持 JavaScript 的 ESM 和 CommonJS 模块
|
||
- 自动解析和安装 Python 依赖
|
||
- 独立的日志捕获和执行结果处理
|
||
- 提供命令行工具（`run_code_rmcp`）和 MCP 服务器（`script_runner`）两种使用方式
|
||
|
||
## 安装方法
|
||
|
||
### 安装命令行工具
|
||
|
||
```bash
|
||
# 克隆仓库
|
||
git clone https://github.com/nuwax-ai/run_code_rmcp.git
|
||
cd run_code_rmcp
|
||
|
||
# 安装命令行工具 (run_code_rmcp)
|
||
cargo install --path .
|
||
|
||
# 或同时安装命令行工具和 MCP 服务器
|
||
cargo install --path . --features mcp
|
||
cargo install --path . --bin script_runner --features mcp
|
||
```
|
||
|
||
### 系统要求
|
||
|
||
- **Rust**：1.85 或更高版本（用于构建）
|
||
- **Deno**：JavaScript/TypeScript 执行必需
|
||
- **uv**：Python 执行和依赖管理必需
|
||
|
||
安装 Deno：
|
||
```bash
|
||
curl -fsSL https://deno.land/install.sh | sh
|
||
```
|
||
|
||
安装 uv：
|
||
```bash
|
||
curl -LsSf https://astral.sh/uv/install.sh | sh
|
||
```
|
||
|
||
## 使用方法
|
||
|
||
### 命令行工具：run_code_rmcp
|
||
|
||
`run_code_rmcp` 命令允许直接从命令行执行代码。
|
||
|
||
#### 基本语法
|
||
|
||
```bash
|
||
run_code_rmcp [选项] <命令>
|
||
```
|
||
|
||
**选项：**
|
||
- `--show-logs`：显示执行日志
|
||
- `--clear-cache`：执行前清除缓存
|
||
- `--use-mcp`：使用 MCP SDK 集成（需要 mcp feature）
|
||
|
||
**命令：**
|
||
- `js`：执行 JavaScript 代码
|
||
- `ts`：执行 TypeScript 代码
|
||
- `python`：执行 Python 代码
|
||
- `clear-cache`：清除缓存文件
|
||
|
||
#### 执行 JavaScript/TypeScript
|
||
|
||
```bash
|
||
# 执行 JavaScript 文件
|
||
run_code_rmcp --show-logs js -f fixtures/test_js.js
|
||
|
||
# 带参数执行
|
||
run_code_rmcp --show-logs js -f fixtures/test_js_params.js -p '{"name":"User"}'
|
||
|
||
# 执行 TypeScript
|
||
run_code_rmcp --show-logs ts -f fixtures/test_ts.ts
|
||
|
||
# 执行内联代码
|
||
run_code_rmcp js -c "function handler() { return 'Hello!'; }"
|
||
```
|
||
|
||
#### 执行 Python
|
||
|
||
```bash
|
||
# 执行 Python 文件
|
||
run_code_rmcp --show-logs python -f fixtures/test_python.py
|
||
|
||
# 带参数执行
|
||
run_code_rmcp --show-logs python -f fixtures/test_python_params.py -p '{"a":10, "b":20}'
|
||
|
||
# 执行内联代码
|
||
run_code_rmcp python -c "def handler(): return 'Hello from Python!'"
|
||
```
|
||
|
||
#### 缓存管理
|
||
|
||
```bash
|
||
# 清除所有缓存
|
||
run_code_rmcp clear-cache --language all
|
||
|
||
# 清除特定语言的缓存
|
||
run_code_rmcp clear-cache --language python
|
||
run_code_rmcp clear-cache --language js
|
||
run_code_rmcp clear-cache --language ts
|
||
|
||
# 执行前清除缓存
|
||
run_code_rmcp --clear-cache js -f fixtures/test_js.js
|
||
```
|
||
|
||
### 作为 Rust 库使用
|
||
|
||
```toml
|
||
[dependencies]
|
||
run_code_rmcp = { git = "https://github.com/nuwax-ai/run_code_rmcp.git" }
|
||
```
|
||
|
||
```rust
|
||
use run_code_rmcp::{CodeExecutor, LanguageScript};
|
||
|
||
#[tokio::main]
|
||
async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||
// 执行 JavaScript
|
||
let js_result = CodeExecutor::execute_with_params_compat(
|
||
"function handler() { return {success: true}; }",
|
||
LanguageScript::Js,
|
||
None
|
||
).await?;
|
||
|
||
// 执行 Python
|
||
let py_result = CodeExecutor::execute_with_params_compat(
|
||
"def handler(): return {'success': True}",
|
||
LanguageScript::Python,
|
||
None
|
||
).await?;
|
||
|
||
Ok(())
|
||
}
|
||
```
|
||
|
||
### MCP 服务器：script_runner
|
||
|
||
`script_runner` 是一个 MCP 服务器，为 AI 助手提供代码执行工具。
|
||
|
||
#### 启动服务器
|
||
|
||
```bash
|
||
# 启动 MCP 服务器
|
||
script_runner
|
||
|
||
# 启用详细日志
|
||
script_runner --verbose
|
||
```
|
||
|
||
服务器通过 stdio 通信，等待 MCP 协议的 JSON 请求。
|
||
|
||
#### 可用工具
|
||
|
||
MCP 服务器提供以下工具：
|
||
|
||
1. **run_javascript** - 执行 JavaScript 代码
|
||
2. **run_typescript** - 执行 TypeScript 代码
|
||
3. **run_python** - 执行 Python 代码
|
||
|
||
每个工具接受：
|
||
- `code`（字符串）：要执行的代码
|
||
- `params`（对象，可选）：传递给 handler 函数的参数
|
||
|
||
#### 与 AI 助手集成
|
||
|
||
添加到你的 MCP 客户端配置（如 Claude Desktop）：
|
||
|
||
```json
|
||
{
|
||
"name": "script-runner",
|
||
"command": "script_runner",
|
||
"transport": "stdio"
|
||
}
|
||
```
|
||
|
||
## 代码结构
|
||
|
||
### Handler 函数
|
||
|
||
脚本应定义一个返回结果的 handler 函数。
|
||
|
||
#### JavaScript/TypeScript
|
||
|
||
支持 `main` 和 `handler` 函数（main 优先）：
|
||
|
||
```javascript
|
||
// 这个函数优先级更高
|
||
function main(input) {
|
||
console.log("使用 main 处理:", input);
|
||
return { result: "Hello from main!" };
|
||
}
|
||
|
||
// 如果没有定义 main，则使用这个函数
|
||
function handler(input) {
|
||
console.log("使用 handler 处理:", input);
|
||
return { result: "Hello from handler!" };
|
||
}
|
||
```
|
||
|
||
也支持 ESM 模块：
|
||
|
||
```javascript
|
||
import { serve } from "https://deno.land/std/http/server.ts";
|
||
|
||
function handler(input) {
|
||
return { message: "ESM works!" };
|
||
}
|
||
```
|
||
|
||
#### Python
|
||
|
||
支持 `handler` 和 `main` 函数（handler 优先）：
|
||
|
||
```python
|
||
import pandas as pd
|
||
|
||
# 这个函数优先级更高
|
||
def handler(args):
|
||
print(f"处理中: {args}")
|
||
data = pd.DataFrame({"a": [1, 2, 3]})
|
||
return {"result": data.to_dict()}
|
||
|
||
# 如果没有定义 handler，则使用这个函数
|
||
def main(args):
|
||
return {"result": "使用 main 代替"}
|
||
```
|
||
|
||
### 参数传递
|
||
|
||
参数会传递给 handler 函数：
|
||
|
||
```bash
|
||
run_code_rmcp js -f script.js -p '{"name": "User", "count": 42}'
|
||
```
|
||
|
||
在代码中：
|
||
```javascript
|
||
function handler(input) {
|
||
// input = { name: "User", count: 42 }
|
||
return `Hello ${input.name}, count: ${input.count}`;
|
||
}
|
||
```
|
||
|
||
### Python 依赖
|
||
|
||
Python 依赖会被自动检测并安装：
|
||
|
||
```python
|
||
import requests
|
||
import pandas as pd
|
||
|
||
def handler(args):
|
||
# 依赖会通过 uv 自动安装
|
||
response = requests.get("https://api.example.com")
|
||
data = pd.DataFrame(response.json())
|
||
return data.to_dict()
|
||
```
|
||
|
||
### 日志捕获
|
||
|
||
所有控制台输出都会与返回值分开捕获：
|
||
|
||
```javascript
|
||
console.log("这是日志");
|
||
console.log("这也是日志");
|
||
|
||
function handler() {
|
||
return "这是结果";
|
||
}
|
||
```
|
||
|
||
结果：
|
||
```json
|
||
{
|
||
"logs": ["这是日志", "这也是日志"],
|
||
"result": "这是结果",
|
||
"error": null
|
||
}
|
||
```
|
||
|
||
## 开发
|
||
|
||
```bash
|
||
# 构建
|
||
cargo build
|
||
|
||
# 使用 cargo 运行
|
||
cargo run -- --show-logs js -f fixtures/test_js.js
|
||
|
||
# 运行测试
|
||
cargo test
|
||
|
||
# 使用 mcp feature 构建
|
||
cargo build --features mcp
|
||
|
||
# 使用 cargo 运行 MCP 服务器
|
||
cargo run --bin script_runner --features mcp
|
||
```
|
||
|
||
## 环境预热
|
||
|
||
项目包含预热函数来缓存常用依赖：
|
||
|
||
```rust
|
||
use run_code_rmcp::warm_up_all_envs;
|
||
|
||
#[tokio::main]
|
||
async fn main() -> Result<()> {
|
||
// 预安装常用的 Python 和 JS/TS 依赖
|
||
warm_up_all_envs(None, None, None, None).await?;
|
||
Ok(())
|
||
}
|
||
```
|
||
|
||
## 待办事项
|
||
|
||
- [ ] TTS（文本转语音）功能 - 目前存在已知问题
|
||
|
||
## 许可证
|
||
|
||
本项目采用 Apache License 2.0 发布。详见根目录的 `LICENSE` 与 `NOTICE` 文件。
|