mcpchainx

mcpchainx 是一个将区块链基础设施与大模型智能体深度融合的开源协议栈。项目提供可验证的代理执行环境，让 AI Agent 能够安全地调用 Web3 能力，并保留完整的审计与溯源数据。

目录

• 核心特性
• 架构与文档
• 快速入门
• 前端控制台
• API 速览
• 示例脚本
• 常见问题
• 贡献指南
• 许可协议

核心特性

• 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。

快速入门

环境准备

1. 安装 Go 1.22+ 与 Python 3.9+。
2. （可选）准备可访问的以太坊 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 文件。