Imhex MCP

ImHex MCP集成

🔧 基于人工智能的ImHex二进制分析

  ](https://github.com/jmpnop/imhexMCP) 

   

*模型上下文协议服务器使Claude等AI助手能够以编程方式分析二进制文件*

⚡ 快速开始 • 特性 • 文档 • 测试 • 演出

______________________________________________________________________

💡 概述

ImHex MCP提供 生产就绪的Python MCP服务器 将AI助手连接到 ImHex，强大的十六进制编辑器。这实现了自主二进制分析、恶意软件检查、固件分析和逆向工程工作流程。

包含内容

• 🔌 MCP服务器 -40+二进制分析工具（Python）
• 📦 ImHex补丁 -10个补丁添加网络接口和基于队列的文件打开
• ⚡ 性能优化 -通过缓存、压缩和异步操作，速度提高了18%
• 🧪 综合测试 -255/255次测试通过（成功率100%）
• 📊 生产特点 -普罗米修斯指标、断路器、速率限制
• 📖 完整的文件 -API文档、架构图、指南

______________________________________________________________________

🌟 特性

核心能力

文件操作

• 基于队列的异步文件打开（无需手动GUI交互！）
• 多文件管理（列表、切换、关闭）
• 具有多种编码的二进制数据读/写

分析工具

• 带分页的模式搜索（十六进制、文本、正则表达式）
• 多架构拆卸（x86、ARM、MIPS等）
• 哈希计算（MD5、SHA-1、SHA-256、SHA-384、SHA-512）
• 字符串提取（ASCII、UTF-16）
• 文件类型检测（30+幻数签名）
• 加密检测的熵分析
• Myers算法的二进制差分

批量操作

• 多文件模式搜索
• 批处理哈希
• 跨文件的比较分析

高级功能

• 大文件分块读取（100MB+）
• 数据导出（二进制、十六进制、base64）
• 书签管理
• 模式语言集成

Python库功能

演出 （17项改进，100%完成）

• 整体速度提高18% （0.217秒→ 0.178s)
• 带宽减少98.9% 使用zstd压缩
• 缓存操作速度提高28% 使用orjson+LRU缓存
• 锁减少25% 具有优化的关键部分
• JSON速度提高97% 序列化

生产就绪

• 异步/等待支持连接池
• 带有LRU驱逐的响应缓存
• 使用指数回退重试逻辑
• 断路器型式
• Prometheus指标导出
• 速率限制和输入验证
• 100%符合mypy的类型提示

______________________________________________________________________

🚀 快速开始

先决条件

• macOS或Linux
• Python 3.10+（在3.10、3.11、3.12、3.14上测试）
• CMake 3.25+
• Git
• C++编译器（GCC 11+或Clang 14+）

一个命令设置

git clone --recurse-submodules https://github.com/jmpnop/imhexMCP.git
cd imhexMCP
./setup-imhex-mcp.sh

此脚本：

1. 克隆ImHex存储库
2. 自动应用所有10个补丁
3. 显示构建说明

构建ImHex

cd ImHex
mkdir -p build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build . -j$(sysctl -n hw.ncpu)  # macOS
# cmake --build . -j$(nproc)            # Linux

设置MCP服务器

cd ../../mcp-server
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

启动ImHex并启用网络接口

1. 运行ImHex： ./ImHex/build/imhex
2. 首选 设置 → 将军
3. 启用 网络接口
4. 重新启动ImHex

网络接口正在监听 localhost:31337

配置Claude桌面

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "imhex": {
      "command": "/ABSOLUTE/PATH/TO/imhexMCP/mcp-server/venv/bin/python",
      "args": ["/ABSOLUTE/PATH/TO/imhexMCP/mcp-server/server.py"]
    }
  }
}

重要：使用绝对路径，而不是相对路径！

验证设置

cd imhexMCP
./verify-setup.sh  # Should show 15/15 passed

与克劳德一起测试

在克劳德，问：

Can you check if ImHex is working? Use the imhex_get_capabilities tool.

______________________________________________________________________

📖 关键终点

ImHex MCP插件提供28个网络端点。以下是最重要的：

全参考：参见 ENDPOINTS.md 对于所有28个具有详细参数的端点。

______________________________________________________________________

🧪 测试

测试套件

255次测试，100%通过 ✅

# Run all tests
pytest

# Run with coverage
pytest --cov=lib --cov=mcp-server --cov-report=term-missing

# Run specific test types
pytest -m unit          # Unit tests only
pytest -m integration   # Integration tests (requires ImHex)
pytest -m compression   # Compression tests

测试组织

使用pytest标记组织测试：

• @pytest.mark.unit -快速单元测试（无依赖关系）
• @pytest.mark.integration -需要运行ImHex
• @pytest.mark.slow -测试时间>1秒
• @pytest.mark.compression -压缩模块测试

覆盖

按模块划分的当前覆盖范围：

• error_handling.py: 94%
• advanced_features.py: 96%
• advanced_cache.py: 92%
• batching.py: 90%
• security.py: 82%

目标：所有模块的覆盖率超过80%

______________________________________________________________________

⚡ 演出

总体改进

17/17优化完成（100%）

关键优化

第一回合：orjson+LRU缓存+快速大小估计

• orjson，JSON速度提高2-3倍（实际每次调用24倍）
• LRU缓存密钥生成 @lru_cache(maxsize=1000)
• 尺寸估算的直接长度计算

第2轮：压缩+异步锁优化

• 压缩缓冲区重用 zlib.compressobj()
• 自适应压缩级别（基于数据大小）
• CacheEntry创建已移至关键部分之外
• 锁定时time.time（）调用减少25%

压缩性能

• 带宽减少98.9% 与zstd
• 净收益：每100个请求节省227毫秒（@100 Mbps）
• 开销：大多数有效载荷的压缩时间\<1ms
• 缓存加速：元数据速度提高21670倍

详情：参见 lib/PERFORMANCE_RESULTS.md 和 lib/OPTIMIZATION_RESULTS_ROUND2.md

______________________________________________________________________

📂 项目结构

imhexMCP/
├── lib/                          # Core Python library (production-ready)
│   ├── async_client.py          # Main async client
│   ├── cache.py                 # Response caching (LRU + orjson)
│   ├── data_compression.py      # Adaptive compression
│   ├── connection_pool.py       # Connection pooling
│   ├── request_batching.py      # Batch operations
│   ├── error_handling.py        # Retry logic & circuit breaker
│   ├── security.py              # Input validation & sanitization
│   ├── metrics.py               # Prometheus metrics
│   └── test_*.py                # Test suite (255 tests)
│
├── mcp-server/                  # MCP server implementation
│   ├── server.py                # Main MCP server (2381 lines)
│   ├── enhanced_client.py       # Enhanced client wrapper
│   ├── imhex_cli.py            # CLI interface
│   └── benchmark_*.py          # Performance benchmarks
│
├── patches/                     # Git patches for ImHex
│   ├── PATCH_MANIFEST.md        # Patch documentation
│   ├── 0001-feat-*.patch        # Queue-based file opening
│   └── 0007-0014-*.patch        # Complete MCP plugin
│
├── ImHex/                       # ImHex submodule (1.38.0.WIP)
│   └── build/imhex             # ImHex binary
│
├── docs/                        # Comprehensive documentation
│   ├── LIBRARY-ARCHITECTURE.md # 15+ Mermaid diagrams
│   ├── API.md                  # API reference
│   └── ...
│
├── CLAUDE.md                    # AI assistant context
├── README.md                    # This file
└── setup-imhex-mcp.sh          # Automated setup script

______________________________________________________________________

🏗️ 建筑

┌─────────────────────┐
│   User / AI         │  Analyze binaries via Claude
└──────────┬──────────┘
           │ MCP Protocol (stdio)
┌──────────▼──────────┐
│   MCP Server        │  Python server (40+ tools)
│   - Request handling│  • Async operations
│   - Caching         │  • Connection pooling
│   - Compression     │  • Performance optimization
└──────────┬──────────┘
           │ JSON-RPC over TCP
┌──────────▼──────────┐
│   ImHex             │  Hex editor with network interface
│   Network Interface │  • Listens on localhost:31337
└──────────┬──────────┘
           │ Plugin API
┌──────────▼──────────┐
│   MCP Plugin        │  C++ plugin (patched)
│   - File operations │  • Queue-based file opening
│   - Data analysis   │  • 28 network endpoints
│   - Batch ops       │  • Enhanced error handling
└──────────┬──────────┘
           │ ImHex APIs
┌──────────▼──────────┐
│   ImHex Core        │
│   - FileProvider    │
│   - Pattern Engine  │
│   - Crypto Library  │
└─────────────────────┘

______________________________________________________________________

📊 改进总结

状态：17/17完成（100%）🎉

关键改进

1. ✅ Pytest框架 -专业测试套件（255项测试，100%通过）
2. ✅ CI/CD管道 -GitHub操作（测试、安全、lint、基准测试）
3. ✅ 类型提示 -100%mypy合规性
4. ✅ Python 3.14兼容性 -所有测试均已通过
5. ✅ 测试套件修复 -通过率从86%提高到100%

性能与优化

1. ✅ 性能分析 -cProfile分析、瓶颈识别
2. ✅ 优化第一轮 -或json、LRU缓存（速度提高18%）
3. ✅ 优化第二轮 -压缩、异步锁（锁减少25%）

安全与质量

1. ✅ 安全加固 -速率限制、输入验证、SQL注入预防
2. ✅ 代码质量工具 -黑色，片状，mypy
3. ✅ 集中配置 -基于Pydantic的验证

文档

1. ✅ 斯芬克斯API文件 -100%模块覆盖率（21个模块）
2. ✅ 架构图 -15+美人鱼图
3. ✅ 基于属性的测试 -假设整合
4. ✅ 普罗米修斯指标 -生产监控

详情：参见 改进-总结.md

______________________________________________________________________

💻 平台支持

测试平台

• ✅ macOS ARM64 （苹果硅）-本地构建
• ✅ macOS x86_64 （英特尔）-完全支持

应该工作（未经测试）

• ⚠️ Linux x86_64 -标准ImHex构建过程
• ⚠️ 视窗 -通过MSYS2/MinGW64

______________________________________________________________________

🤝 贡献

我们欢迎捐款！

帮助区域

• 🐛 Bug修复和问题报告
• 📝 文档改进
• 🧪 在不同平台上进行测试
• ✨ 新功能和端点

贡献工作流程

1. 分叉此存储库
2. 克隆ImHex并应用补丁
3. 进行更改
4. 运行测试： pytest
5. 生成新补丁： git format-patch origin/master..HEAD
6. 提交带有更新补丁的PR

______________________________________________________________________

📄 文档

______________________________________________________________________

🔗 相关项目

• ImHex -WerWolv的功能丰富的十六进制编辑器
• MCP规范 -基于Anthropic的模型上下文协议
• 克劳德 -支持MCP的AI助手

______________________________________________________________________

📞 支持

获取帮助

• 📖 文档：从以下内容开始 CLAUDE.md
• 🐛 问题:
• 💬 讨论:

报告问题

请包括：

• ImHex提交哈希
• 操作系统和架构
• Python版本
• 错误消息
• 重现步骤

______________________________________________________________________

📄 许可证

GPL-2.0 -与ImHex相同

此项目根据其许可条款为ImHex提供了一个模型上下文协议服务器和补丁。看 许可证 全文。

______________________________________________________________________

🙏 学分

• 模型上下文协议 通过 Anthropic -协议规范
• 用于反馈和测试的逆向工程社区

______________________________________________________________________

⭐ 如果你觉得这个存储库有用，请为其加星！

由...制作❤️ 面向逆向工程社区

______________________________________________________________________

版本2.0.0 | 最后更新日期：2025-11-15 | 状态：✅ 生产就绪