Faial MCP

Faial MCP服务器

此包将Faial CUDA静态分析二进制文件封装在模型上下文协议（MCP）服务器中。它允许代理和其他MCP客户端调用 faial-drf 通过 analyze_kernel 工具。

Docker快速入门（推荐）

使用Faial MCP最简单的方法是通过Docker，它捆绑了Faial二进制文件和MCP服务器：

# Test your Docker setup (optional but recommended)
# Linux/macOS:
./test-docker.sh
# Windows PowerShell:
.\test-docker.ps1

# Build the Docker image
docker build -t faial-mcp .

# Run as a network-based MCP server (SSE transport)
docker run -p 8000:8000 faial-mcp

# Or run with stdio transport (for local development)
docker run -i faial-mcp faial-mcp-server --transport stdio

请参阅 有关详细说明，请参阅以下部分，或阅读 GETTING_STARTED.md 以获得完整的演练。

先决条件（本地安装）

• Python 3.10或更新版本
• Faial双星(faial-drf, cu-to-json，支持库）在主机系统上可用

本地安装

这些说明建议用于所有平台，包括WSL（Linux的Windows子系统）。

1. 创建虚拟环境：

   python3 -m venv .venv

1. 激活虚拟环境：

- Windows（命令提示符/PowerShell）：

     .venv\Scripts\activate

- Linux/MOSC/WSL：

     source .venv/bin/activate

1. 安装软件包：

   pip install -e .

您可以通过以下方式安装可选的开发依赖项 pip install -e .[dev].

跑步

激活虚拟环境后，运行服务器：

faial-mcp-server --transport stdio

服务器默认使用stdio传输，这适用于本地代理集成。SSE和流式HTTP传输也可通过 --transport sse 或 --transport streamable-http.

配置

环境变量配置默认路径：

• FAIAL_MCP_EXECUTABLE：路径 faial-drf （默认为查找 faial-drf 上 PATH).
• FAIAL_MCP_CU_TO_JSON：路径 cu-to-json 当默认查找不足时，使用助手。
• FAIAL_MCP_TIMEOUT_MS：当请求未指定超时时，应用默认超时（毫秒）。
• FAIAL_MCP_TRANSPORT：默认传输(stdio, sse，或 streamable-http).
• FAIAL_MCP_HOST / FAIAL_MCP_PORT：使用SSE或HTTP传输时主机/端口的默认值。

每次工具调用都可以覆盖可执行文件、帮助程序路径、工作目录和环境。

可用工具

analyze_kernel

运行Faial的数据种族自由分析(faial-drf)与CUDA或WGSL内核相比。 所有请求都必须通过 source 现场。 不支持基于文件路径的提交，因为服务器在调用之前会将每个请求写入一个隔离的临时文件 faial-drf.

关键论点：

• source （必需）：作为字符串的自包含内核代码段。包括任何辅助函数、结构、常量和宏，这样内核就可以在没有额外文件的情况下编译。
• virtual_filename：逻辑文件名（例如。， my_kernel.cu)以控制日志中记录的扩展。
• include_dirs：要转发的目录列表 -I。当内核合法地依赖于

您可以将标头装载到服务器的工作区中。路径相对于 working_directory （默认：服务器的当前工作目录），因此请提供绝对路径或设置 working_directory 在引用装载的文件时。

• macros：宏定义词典({"DEBUG": "1", "USE_FAST": null})那就变成了 -D 旗帜。值是可选的；使用 null 用于标志样式宏。CLI样式的字符串，例如 "DEBUG 1" 或 "USE_FAST=value" 也会被自动接受和规范化。
• working_directory：运行目录 faial-drf这也控制了相对包含的方式

路径和辅助二进制文件已解析。默认为服务器的启动目录。

• include_raw_output：设置为 true 当您需要Faial提供完整的stdout/stderr/JSON有效负载时。

默认情况下，MCP响应仅包括简明摘要和简短摘录，以保留有效载荷 小。

• params, block_dim, grid_dim, only_kernel, only_array, logic, timeout_ms,

find_true_data_races, grid_level, all_levels, all_dims, unreachable, ignore_parsing_errors, 和 extra_args：Faial CLI标志的一对一镜像。

• environment：调用时要设置的额外环境变量 faial-drf （仅限字符串值）。
• 其他CLI镜像交换机： params, block_dim, grid_dim, only_kernel, only_array, logic, timeout_ms, find_true_data_races, grid_level, all_levels, all_dims, unreachable, ignore_parsing_errors，以及 extra_args.

请求负载示例：

{
  "name": "analyze_kernel",
  "arguments": {
    "source": "__global__ void saxpy(int n, float a, float *x, float *y) { int i = blockIdx.x * blockDim.x + threadIdx.x; if (i ;status=;errors=;unknowns=;notes=`，或 `stderr_summary=...` 当Faial无法解析任何内核时。

### 内核提取助手

使用内置的帮助程序提取内核代码段并准备一个准备发送的有效负载：

faial-mcp-server extract active_benchmarking/reverseArray_datarace.cu --kernel reverseArray --json

此命令定位所请求的 `__global__` 函数，打印内核源代码（或发出JSON
`--json`)，并重放评论中嵌入的任何启动提示，如 `//--blockDim=256 --gridDim=1`.Set
`--virtual-filename` 如果您需要在输出负载中使用自定义逻辑文件名。

______________________________________________________________________

## Docker使用

### 塑造形象

Dockerfile会自动下载Faial二进制文件并设置MCP服务器：

docker build -t faial-mcp .

这将创建一个自包含的映像（~500MB），其中包含：

- Ubuntu 24.04基础版
- 来自官方发行版的Faial二进制文件
- Python 3和MCP服务器包

### 运行容器

#### 基于网络的MCP（SSE传输）-建议用于远程访问

Run on default port 8000

docker run -p 8000:8000 faial-mcp

Or customize host/port

docker run -p 9000:9000 faial-mcp faial-mcp-server --transport sse --host 0.0.0.0 --port 9000

将您的MCP客户端连接到 `http://localhost:8000` （或您的自定义港口）。

#### 地方发展（stdio交通）

docker run -i faial-mcp faial-mcp-server --transport stdio

**注：** 使用Docker进行stdio传输需要交互模式(`-i` 旗）。

#### 从主机分析文件

要分析主机上的文件，请将一个目录装载到容器中：

Mount current directory to /workspace in container

docker run -p 8000:8000 -v "$(pwd):/workspace" faial-mcp

Now the MCP client can reference files like: /workspace/my_kernel.cu

在Windows PowerShell上：

docker run -p 8000:8000 -v "${PWD}:/workspace" faial-mcp

### 测试服务器

运行后，使用简单的curl请求测试MCP服务器：

curl -X POST http://localhost:8000/analyze \ -H "Content-Type: application/json" \ -d '{ "source": "__global__ void add(int *a, int *b) { *a = *b + 1; }", "virtual_filename": "test.cu" }'

### 配置MCP客户端

#### 克劳德桌面

添加到您的 `claude_desktop_config.json`:

{ "mcpServers": { "faial": { "url": "http://localhost:8000", "transport": "sse" } } }

#### 光标/其他客户端

配置MCP客户端以连接到 `http://localhost:8000` 使用SSE传输。

### 环境变量

通过传递环境变量来覆盖默认值 `docker run`:

docker run -p 8000:8000 \ -e FAIAL_MCP_TIMEOUT_MS=60000 \ -e FAIAL_MCP_EXECUTABLE=/opt/faial/faial-drf \ faial-mcp

可用变量：

- `FAIAL_MCP_EXECUTABLE`：路径 `faial-drf` （默认值： `/opt/faial/faial-drf`)
- `FAIAL_MCP_CU_TO_JSON`：路径 `cu-to-json` 助手
- `FAIAL_MCP_TIMEOUT_MS`：默认分析超时（毫秒）
- `FAIAL_MCP_HOST`：网络传输的默认主机（默认： `0.0.0.0`)
- `FAIAL_MCP_PORT`：网络传输的默认端口（默认： `8000`)

### Docker编写（可选）

对于持久部署，创建 `docker-compose.yml`:

version: '3.8' services: faial-mcp: build: . ports: - "8000:8000" volumes: - ./workspace:/workspace environment: - FAIAL_MCP_TIMEOUT_MS=60000 restart: unless-stopped

运行方式：

docker-compose up -d

### 部署到云端

Docker镜像可以部署到任何容器托管平台：

#### Docker中心/注册表

Tag and push

docker tag faial-mcp your-registry/faial-mcp:latest docker push your-registry/faial-mcp:latest

#### 云运行/ECS/Kubernetes

将映像部署到您首选的云平台，确保：

- 端口8000暴露
- 容器有足够的内存（建议2GB以上）
- 集 `FAIAL_MCP_TIMEOUT_MS` 适合您的工作量

### 故障排除

#### 集装箱立即出口

检查日志： `docker logs `

#### 无法连接到MCP服务器

- 确保端口暴露： `docker run -p 8000:8000 ...`
- 检查防火墙设置
- 验证服务器是否正在侦听： `docker exec  netstat -tlnp`

#### 分析失败，显示“未找到可执行文件”

验证Faial是否在路径中：

docker exec which faial-drf docker exec faial-drf --version

#### 已装载卷的权限错误

在Linux上，您可能需要调整所有权：

docker run -p 8000:8000 -v "$(pwd):/workspace" --user $(id -u):$(id -g) faial-mcp