内容
# FFDec MCP 服务器
[](https://github.com/Xeleron/ffdec-mcp/releases)
[](https://github.com/Xeleron/ffdec-mcp/actions)
[](https://opensource.org/licenses/Apache-2.0)
一款用于分析和操作 Shockwave Flash (SWF) 文件的 [模型上下文协议（MCP）](https://modelcontextprotocol.io/) 服务器，使用 [JPEXS 免费 Flash 反编译器（FFDec）](https://github.com/jindrapetrik/jpexs-decompiler)。
> **快速了解**：让 AI 助手（Claude、GitHub Copilot 等）通过自然语言命令读取、修改和修补 SWF 文件。
---
## 快速开始
### 使用 Podman/Docker（推荐）
```bash
# 1. 构建镜像
podman build -t ffdec-mcp-server:latest .
# 2. 添加到您的 MCP 客户端配置（详见安装部分）
```
### 使用 Smithery（仅限 Claude Desktop）
```bash
npx -y @smithery/cli install @Xeleron/ffdec-mcp --client claude
```
---
## 功能
| 类别 | 功能 |
| :--- | :--- |
| **分析** | 读取 SWF 头部，列出标签/类/符号，检查字节码 |
| **反编译** | 从类和脚本中提取 ActionScript 3 源代码 |
| **修改** | 修补类/方法，编辑常量，重命名标识符 |
| **注入** | 添加新类、方法、字段或从文件导入 ABC |
| **导出** | 保存修改后的 SWF，导出特定组件 |
---
## 先决条件
| 要求 | 版本 | 备注 |
| :--- | :--- | :--- |
| **Java** | 21+ | 本地构建所需（JDK，非 JRE） |
| **Maven** | 3.6+ | 从源代码构建所需 |
| **Podman/Docker** | 任意 | 推荐的本地 Java 设置替代方案 |
---
## 安装
### 选项 1：Podman/Docker（最佳稳定性）
Dockerfile 自动处理所有 FFDec 库依赖项。
```bash
podman build -t ffdec-mcp-server:latest .
```
将以下内容添加到您的 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"ffdec": {
"command": "podman",
"args": [
"run",
"-i",
"--rm",
"-v",
"/绝对路径/到/您的/swfs:/swfs:rw",
"ffdec-mcp-server:latest"
]
}
}
}
```
> **注意**：将 `/绝对路径/到/您的/swfs` 替换为您的实际本地目录。
### 选项 2：本地构建（高级）
1. **克隆仓库：**
```bash
git clone https://github.com/Xeleron/ffdec-mcp.git
cd ffdec-mcp
```
2. **安装 FFDec 库：**
```bash
mvn install:install-file \
-Dfile=/路径/到/ffdec_lib.jar \
-DgroupId=com.jpexs \
-DartifactId=ffdec_lib \
-Dversion=1.0.0 \
-Dpackaging=jar
```
3. **构建和配置：**
```bash
mvn clean package
```
将您的 MCP 客户端指向生成的 `run.sh`（确保通过 `chmod +x run.sh` 可执行）。
---
## 可用工具
服务器暴露了 40+ 个工具。运行时使用 `tools/list` 获取完整的技术定义。
<details>
<summary><strong>会话管理</strong></summary>
| 工具 | 描述 |
| :--- | :--- |
| `open_swf` | 打开 SWF 文件并创建会话 |
| `close_swf` | 关闭会话并释放资源 |
| `reload_swf` | 从磁盘重新加载，丢弃未保存的更改 |
| `list_sessions` | 列出所有打开的 SWF 会话 |
| `save_swf` | 将修改保存到磁盘 |
</details>
<details>
<summary><strong>分析和检查</strong></summary>
| 工具 | 描述 |
| :--- | :--- |
| `get_swf_info` | SWF 头部和元数据（版本、大小、尺寸） |
| `list_classes` | 枚举 AS3 类和脚本 |
| `list_tags` | 列出所有标签及其类型 |
| `list_symbols` | 符号类关联（ID ↔ 类名） |
| `list_scripts` | AS3 脚本包和索引 |
| `list_methods` | 类的实例和方法 |
| `get_traits` | 类的所有特性（方法、字段、访问器） |
| `get_class_hierarchy` | 超类和接口 |
| `get_dependencies` | 给定类引用的类 |
| `get_constant_pool` | 常量池片段（字符串、整数） |
| `get_tag_details` | 按索引获取标签的详细元数据 |
</details>
<details>
<summary><strong>反编译和搜索</strong></summary>
| 工具 | 描述 |
| :--- | :--- |
| `decompile_class` | 反编译 AS3 类到源代码 |
| `decompile_script` | 按索引反编译脚本 |
| `get_bytecode` | 方法/类的 AVM2 字节码（P-code） |
| `search_source` | 搜索反编译的 AS3 源代码 |
| `search_pcode` | 搜索字节码模式 |
| `find_class` | 查找匹配查询的类 |
| `find_methods` | 跨脚本/类查找方法 |
| `resolve_identifier` | 将名称解析为内部索引 |
</details>
<details>
<summary><strong>修改</strong></summary>
| 工具 | 描述 |
| :--- | :--- |
| `patch_class` | 替换整个类源代码并重新编译 |
| `patch_method` | 替换单个方法的源代码 |
| `patch_bytecode` | 直接替换方法的 P-code |
| `edit_constants` | 在 ABC 池中查找和替换常量 |
| `rename_identifier` | 一致地重命名类/方法/字段 |
| `modify_symbol` | 添加/删除/更改符号类关联 |
| `modify_swf_header` | 更改版本、帧率、尺寸 |
| `modify_class_flags` | 切换密封/最终/接口标志 |
| `replace_superclass` | 更改类的超类 |
</details>
<details>
<summary><strong>注入和删除</strong></summary>
| 工具 | 描述 |
| :--- | :--- |
| `inject_class` | 添加新 AS3 类（创建 DoABC 标签） |
| `inject_abc_from_file` | 从 SWF/.abc 文件导入 ABC 标签 |
| `add_method` | 在现有类中追加方法 |
| `add_field` | 在现有类中添加字段 |
| `add_interface` | 添加接口实现 |
| `remove_trait` | 删除方法/属性特性 |
| `remove_tag` | 按索引删除标签 |
| `delete_class` | 从 ABC 数据中删除类 |
</details>
---
## 示例工作流程
### 分析 SWF
> **用户**： "打开 game.swf 并显示它包含哪些类"
> **AI**： 使用 `open_swf`，然后 `list_classes`。
### 修改 SWF
> **用户**： "将 Player 类中的玩家最大生命值从 100 更改为 200"
> **AI**： 搜索常量，使用 `edit_constants` 或 `patch_method`，然后 `save_swf`。
---
## 故障排除
<details>
<summary><strong>构建失败，提示 "ffdec_lib not found"</strong></summary>
FFDec 库不在 Maven Central 上。使用 **Docker 构建** 自动处理此问题，或使用 `mvn install:install-file` 手动安装 JAR。
</details>
<details>
<summary><strong>服务器无法启动： "Java version X required"</strong></summary>
运行 `java -version`。本项目需要 **Java 21+**。
</details>
---
## 许可证
在 **Apache License 2.0** 下许可。
### 第三方许可证
| 组件 | 许可证 | 备注 |
| :--- | :--- | :--- |
| `ffdec_lib` | [LGPLv3](https://www.gnu.org/licenses/lgpl-3.0.html) | 核心 SWF 分析库 |
