onetruth7522/emulation-mcp

# Emulation-MCP 一个基于 SQLite 的 MCP 服务器，将用于仿真逆向工程的衬底管理转化为模式强制的机械写入，并以确定性的 Markdown 视图作为人类可读的表面。 ## 解决的问题 长期的逆向工程和仿真项目会积累一种特定类型的知识：关于目标设备的断言，每个断言都有证据基础、对其他断言的依赖关系，以及随着新证据到来可能改变的状态。跨会话手动维护这种知识会逐渐退化。一个声明被推翻后，其依赖项不会被标记。一笔债务被产生后，它所污染的区域仍然被标记为"忠实"。一个会话结束，新的会话开启，操作者再也无法分辨哪些信念是承重性的。 该 MCP 所管理的衬底将这些依赖纪律的操作转化为模式强制的写入： - 每个断言（称为"声明"）有一个状态——`confirmed`（已确认）、`hypothesized`（假设中）或 `assumed`（假定）——以及一个依赖图。 - 推翻一个声明会通过 SQL 触发器自动将 `pending_reverification`（待重新验证）级联传播到递归依赖项。 - 覆盖区域经历 `honest-halt`（诚实停机）/ `lie`（谎言）/ `faithful`（忠实）/ `scope-boundary`（范围边界）的生命周期，并带有角色门控的状态转换；`faithful` 状态要求所有支撑声明已确认且爆炸半径内无活跃债务。 - 债务通过另一个模式触发器自动毒害其爆炸半径内的忠实覆盖区域。 - 扩展完整性扫描（25 项检查）会暴露漂移、孤立边、方法论调用次数分歧，以及其他过去需要人工捕获的故障模式。 Markdown 视图在每次写入时从数据库确定性重新生成，在相同数据库状态下字节级一致。 ## 项目状态 在为期六个月的时间里，针对一个活跃的多月嵌入式逆向工程项目进行了实地测试。1234 个测试通过，一个有意跳过的测试（针对外部工作流模板的集成测试）。该 MCP 被视为基础设施——不与任何特定目标耦合，旨在被提供自己 `substrate/` 目录的仿真项目所使用。 此前在私有工作区中开发；作为 Anthropic Fellows 申请公共工件集的一部分发布。 ## 架构 七个实体加上一个依赖图： | 实体 | 说明 | |--------|-----------| | `arcs` | 持续调查工作的单元（重建、表征、债务退役、实验、调查） | | `spec_model` | 设备是什么——函数、内存区域、外设、字符串、中断、持久状态 | | `claims` | 关于目标设备的断言，带有状态和依赖关系 | | `coverage` | 处于 `faithful` / `honest-halt` / `lie` / `scope-boundary` 状态的行为区域 | | `debts` | 仿真器中的活跃谎言，带有退役条件和爆炸半径 | | `findings` | 多态观察，可提升为声明或债务，或被驳回 | | `methodology` | 模式及其触发条件，带有单调调用追踪 | SQLite 是事实来源（`substrate/substrate.db`）。七个 Markdown 文件（`substrate/arcs.md`、`substrate/claims.md` 等）在每次写入时原子性重新生成，不应手动编辑——下一次 MCP 写入会覆盖手动编辑的内容。 ## 工具接口 该服务器在写入和读取方面注册了大约 60 个工具。 **写入**是原子性的且以意图命名的——没有通用的 `substrate_update`。每个变更都是独立的工具，带有特定的前置条件：`claim_add`、`claim_promote`、`claim_invalidate`、`claim_revise`、`claim_reconfirm`、`coverage_add`、`coverage_transition`、`scope_boundary_declare`、`debt_add`、`debt_retire`、`finding_log`、`finding_promote`、`finding_dismiss`、`methodology_add`、`methodology_invoke` 等。 **读取**是带有观点的、为定位而组合的：`substrate_brief` 是单次调用的会话开启工具，返回活跃弧、方法论触发匹配、完整性扫描以及自上次会话以来的覆盖增量。`role_enter` 为 surveyor / analyst / IE / conformance / architect 上下文组合角色特定的定位信息。`claim_context`、`arc_status`、`coverage_history` 和 `spec_model_get` 是聚焦检查类读取工具。 完整接口参见 `lib/`（每个工具组一个模块）和 `server.py`（注册部分）。 ## 安装 需要 Python 3.12+。 ``` # 克隆后，从仓库根目录运行： pip install -e . ``` 或使用 `uv`： ``` uv sync ``` ## 在 Claude Desktop 中使用 添加到你的 Claude Desktop MCP 配置中： ``` { "mcpServers": { "emulation-mcp": { "command": "python", "args": ["/path/to/Emulation-MCP/server.py"] } } } ``` `EMULATION_MCP_FRICTION_LOG_BASE` 环境变量控制工作流摩擦日志的存放位置。如果未设置，默认为服务器旁边的 `friction-log/` 目录。 ## 引导新的仿真项目 1. 将 `templates/substrate/` 复制到你的项目工作区中，命名为 `substrate/`。 2. 通过 `substrate_next_session_id` 启动会话。 3. 通过 `arc_open` 打开一个弧，然后开始填充 spec-model、声明和覆盖区域。 任何写入工具在首次使用时都会从 `lib/schema.sql` 自动初始化 `substrate.db`。`substrate_regenerate` 可随时从当前数据库状态重建 Markdown。 ## 测试 ``` pytest ``` 测试与代码的比例约为 2:1（约 23,000 行测试代码对约 11,000 行库代码）。测试范围涵盖 SQL 模式不变量、触发器行为、Markdown 确定性、迁移路径和工具边界清理。 ## 方法论 这个 MCP 是一个系统的一半。另一半是 Emulation Workflow 方法论文档，它定义了角色分离（Home Base、Architect、Surveyor、Analyst、Implementation Engineer、Conformance）、弧生命周期、分歧分类法（模型 / 理解 / 真实差距）以及 MCP 机械执行的三态覆盖模型（faithful / honest-halt / lie）。 没有方法论的 MCP 是没有操作者的衬底。没有 MCP 的方法论是在会话压力下会退化的纪律。它们被设计为配合使用。 ## 许可证 MIT。参见 `LICENSE`。 ## 作者 Travis Maynard（[github.com/onetruth7522](https://github.com/onetruth7522))

标签：Markdown视图, MCP服务器, Python, Schema设计, SQLite, Waymore结果处理, 二进制分析, 二进制发布, 云安全运维, 仿真, 依赖传播, 依赖图, 债务追踪, 假设验证, 反向工程, 固件分析, 安全规则引擎, 完整性检查, 嵌入式逆向, 开源工具, 技术债务, 数据库驱动, 断言状态, 断言管理, 无后门, 模式强制, 状态机, 知识管理, 研究领域, 确定性生成, 级联失效, 网络调试, 自动化, 覆盖率分析, 触发器, 证据链, 调试, 逆向分析, 逆向工程工具, 长周期研究