OpenMCP-Chain is a decentralized protocol stack bridging blockchain and large models, enabling trusted AI agents with standardized Web3 interactions.
OpenMCP-Chain
OpenMCP-Chain 是一个将区块链基础设施与大模型智能体深度融合的开源协议栈。项目提供可验证的代理执行环境，让 AI Agent 能够安全地调用 Web3 能力，并保留完整的审计与溯源数据。
目录
核心特性
- Golang + Python 协同：通过内置的 Python Bridge 触发推理脚本，便于在 Go 服务中复用模型能力。
- Web3 快速接入：内置 JSON-RPC 客户端，可查询链 ID、最新区块高度等指标，并支持
eth_getBalance、eth_getTransactionCount等读操作。 - 可追踪任务日志：默认使用本地文件模拟 MySQL 持久化，同时提供真实 MySQL 仓库实现，满足生产环境的数据一致性需求。
- 上下文记忆驱动的推理：Agent 在推理前自动装载最近的任务历史，把经验注入 Prompt，提升回答连续性。
- 知识库增强：通过静态知识卡片在推理时补充领域经验，让回复同时参考链上最佳实践与安全提示。
- 可扩展架构：配置、存储、Agent、API、Web3 等模块均采用接口抽象，支持按需替换实现。
架构与文档
- 系统设计与流程图参见
docs/architecture.md。 - API 契约说明位于
docs/api/。 - 部署建议与演进规划参见
docs/deployment.md与docs/roadmap.md。 - 安全测试与渗透测试流程见
docs/security/SECURITY_TESTING.md。 - 数据指标、仓库建模与报表方案见
docs/analytics/data_warehouse_and_reporting.md。 - 文档校对流程请查阅
docs/documentation-review.md。
快速入门
环境准备
- 安装 Go 1.22+ 与 Python 3.9+。
- （可选）准备可访问的以太坊 JSON-RPC 节点。
构建与运行
# 拉取依赖并编译
go build ./...
# 启动守护进程（默认配置位于 configs/openmcp.json）
OPENMCP_CONFIG=$(pwd)/configs/openmcp.json go run ./cmd/openmcpd
服务启动后将监听 http://127.0.0.1:8080，并在 data/tasks.log 写入执行摘要。
触发一次任务
可直接使用 curl，或运行示例脚本：
# 使用示例脚本提交任务
python examples/task_quickstart.py invoke \
--goal "查询账户余额" \
--chain-action eth_getBalance \
--address 0x0000000000000000000000000000000000000000
# 查看最近的 5 条任务历史
python examples/task_quickstart.py history --limit 5
若未配置真实 RPC 节点，链上数据字段会为空，错误信息会写入 observations。
API 速览
当前版本实现以下 REST 接口，详见 docs/api/tasks.md：
| Method | Path | 描述 |
| --- | --- | --- |
| POST | /api/v1/tasks | 提交一次智能体任务，返回推理输出、链上快照与审计信息。 |
| GET | /api/v1/tasks | 查询最近的任务执行记录，支持分页与过滤，并返回 total/next_offset 元数据。 |
| GET | /api/v1/tasks/{id} | 查询指定任务的详细执行记录。 |
| GET | /api/v1/tasks/stats | 汇总任务数量、状态分布与最近更新时间。 |
示例脚本
examples/task_quickstart.py：命令行客户端，演示如何调用 REST API 并解析响应。examples/README.md：记录示例依赖与运行方式，便于扩展更多脚本或 Notebook。
欢迎补充新的示例，并在 PR 中引用相关文档章节。
前端控制台
项目提供一个基于 React + Vite 的轻量级前端，帮助快速连调 /api/v1/tasks 接口。源码位于 web/，具备以下能力：
- 图形化填写任务目标、链上操作、可选地址与 Metadata；
- 实时轮询任务状态，并展示模型思考、回复与链上观测结果；
- 内置连接诊断与身份认证面板，可检测 API 连通性并缓存访问令牌；
- 支持通过 UI 或
VITE_API_BASE_URL覆盖后端地址，便于连接自定义环境； - 自动检测网络离线/恢复状态，提示用户并暂停轮询，防止误操作；
- 提供任务状态筛选与 JSON 导出，便于排查与归档执行记录。
启动方式：
cd web
npm install
npm run dev
默认会连接本地的 http://127.0.0.1:8080 服务，可结合 OPENMCP_CONFIG=$(pwd)/configs/openmcp.json go run ./cmd/openmcpd 快速体验端到端流程。
常见问题
Q: 需要同时安装 Go 和 Python 吗？
是的。守护进程由 Go 实现，推理逻辑通过 Python Bridge 执行。若缺少 Python，POST /api/v1/tasks 将返回桥接失败错误。
Q: 未连接真实 RPC 节点会怎样？
系统仍会完成推理，但 chain_id、block_number 等字段为空，并在 observations 中提示 RPC 错误。可通过 configs/openmcp.json 修改 RPC 端点。
Q: 如何接入 MySQL？
在配置中将 storage.task_store.driver 设置为 mysql 并提供 dsn，随后以 -tags mysql 运行 openmcpd。示例配置见 configs/openmcp.mysql.json。
Q: 文档如何保持最新？
请参考 docs/documentation-review.md 中的校对流程，在 PR 中勾选受影响的文档并安排同伴审阅。
贡献指南
欢迎提交 Issue 或 Pull Request，共同完善区块链与大模型融合的最佳实践。贡献代码时请确保：
- 通过
go fmt、go test等基础校验； - 为新增模块补充文档或注释；
- 遵循文档校对流程，在 PR 中注明已更新的章节。
许可协议
项目遵循 MIT License，详情请参阅 LICENSE 文件。