Content
# mcpchainx
mcpchainx is an open-source protocol stack that deeply integrates blockchain infrastructure with large model intelligent agents. The project provides a verifiable proxy execution environment, allowing AI Agents to securely call Web3 capabilities while retaining complete audit and traceability data.
## Table of Contents
- [Core Features](#核心特性)
- [Architecture and Documentation](#架构与文档)
- [Quick Start](#快速入门)
- [Frontend Console](#前端控制台)
- [API Overview](#api-速览)
- [Example Scripts](#示例脚本)
- [Frequently Asked Questions](#常见问题)
- [Contribution Guide](#贡献指南)
- [License Agreement](#许可协议)
## Core Features
- **Golang + Python Collaboration**: Trigger inference scripts through the built-in Python Bridge, making it easy to reuse model capabilities in Go services.
- **Fast Web3 Access**: Built-in JSON-RPC client, query chain ID, latest block height and other indicators, and support read operations such as `eth_getBalance` and `eth_getTransactionCount`.
- **Trackable Task Logs**: Default use of local file simulation MySQL persistence, while providing a real MySQL warehouse implementation, meeting the data consistency requirements of the production environment.
- **Context Memory-Driven Reasoning**: Agent automatically loads recent task history before reasoning, injecting experience into Prompt to improve response continuity.
- **Knowledge Base Enhancement**: Supplement domain experience through static knowledge cards during reasoning, allowing replies to refer to both on-chain best practices and security tips.
- **Scalable Architecture**: Configuration, storage, Agent, API, Web3 and other modules adopt interface abstraction, supporting on-demand replacement implementation.
## Architecture and Documentation
- System design and process diagrams can be found in [`docs/architecture.md`](docs/architecture.md).
- API contract descriptions are located in [`docs/api/`](docs/api/).
- Deployment suggestions and evolution plans can be found in [`docs/deployment.md`](docs/deployment.md) and [`docs/roadmap.md`](docs/roadmap.md).
- Security testing and penetration testing processes can be found in [`docs/security/SECURITY_TESTING.md`](docs/security/SECURITY_TESTING.md).
- Data indicators, warehouse modeling, and reporting solutions can be found in [`docs/analytics/data_warehouse_and_reporting.md`](docs/analytics/data_warehouse_and_reporting.md).
- Document review processes can be found in [`docs/documentation-review.md`](docs/documentation-review.md).
## Quick Start
### Environment Preparation
1. Install **Go 1.22+** and **Python 3.9+**.
2. (Optional) Prepare an accessible Ethereum JSON-RPC node.
### Build and Run
```bash
# Pull dependencies and compile
go build ./...
# Start the daemon process (default configuration located in configs/openmcp.json)
OPENMCP_CONFIG=$(pwd)/configs/openmcp.json go run ./cmd/openmcpd
```
After the service starts, it will listen on `http://127.0.0.1:8080` and write execution summaries to `data/tasks.log`.
### Trigger a Task
You can directly use `curl` or run example scripts:
```bash
# Use example scripts to submit tasks
python examples/task_quickstart.py invoke \
--goal "Query account balance" \
--chain-action eth_getBalance \
--address 0x0000000000000000000000000000000000000000
# View the last 5 task histories
python examples/task_quickstart.py history --limit 5
```
If no real RPC node is configured, on-chain data fields will be empty, and error information will be written to `observations`.
## API Overview
The current version implements the following REST interfaces, see [`docs/api/tasks.md`](docs/api/tasks.md) for details:
| Method | Path | Description |
| --- | --- | --- |
| `POST` | `/api/v1/tasks` | Submit a smart agent task, return inference output, on-chain snapshot, and audit information. |
| `GET` | `/api/v1/tasks` | Query recent task execution records, support pagination and filtering, and return `total`/`next_offset` metadata. |
| `GET` | `/api/v1/tasks/{id}` | Query the detailed execution record of a specified task. |
| `GET` | `/api/v1/tasks/stats` | Summarize task quantity, status distribution, and recent update time. |
## Example Scripts
- `examples/task_quickstart.py`: Command-line client, demonstrating how to call REST API and parse responses.
- `examples/README.md`: Record example dependencies and operation methods, convenient for expanding more scripts or Notebooks.
Welcome to supplement new examples and reference relevant document sections in PR.
## Frontend Console
The project provides a lightweight frontend based on React + Vite, helping to quickly connect to the `/api/v1/tasks` interface. The source code is located in [`web/`](web/README.md), with the following capabilities:
- Graphical filling of task goals, on-chain operations, optional addresses, and metadata;
- Real-time polling task status, and displaying model thinking, replies, and on-chain observation results;
- Built-in connection diagnosis and identity authentication panel, detecting API connectivity and caching access tokens;
- Support covering backend addresses through UI or `VITE_API_BASE_URL`, convenient for connecting custom environments;
- Automatic detection of network offline/recovery status, prompting users and pausing polling to prevent misoperation;
- Providing task status filtering and JSON export, convenient for troubleshooting and archiving execution records.
Startup method:
```bash
cd web
npm install
npm run dev
```
It will connect to the local `http://127.0.0.1:8080` service by default, and can quickly experience the end-to-end process with `OPENMCP_CONFIG=$(pwd)/configs/openmcp.json go run ./cmd/openmcpd`.
## Frequently Asked Questions
**Q: Do I need to install both Go and Python?**<br>
Yes. The daemon process is implemented by Go, and the inference logic is executed through the Python Bridge. If Python is missing, `POST /api/v1/tasks` will return a bridge failure error.
**Q: What happens if I don't connect to a real RPC node?**<br>
The system will still complete the inference, but fields such as `chain_id` and `block_number` will be empty, and RPC errors will be prompted in `observations`. You can modify the RPC endpoint by `configs/openmcp.json`.
**Q: How to access MySQL?**<br>
Set `storage.task_store.driver` to `mysql` and provide `dsn` in the configuration, then run `openmcpd` with `-tags mysql`. See `configs/openmcp.mysql.json` for example configuration.
**Q: How to keep the documentation up-to-date?**<br>
Refer to the review process in [`docs/documentation-review.md`](docs/documentation-review.md), mark affected documents in PR, and arrange peer review.
## Contribution Guide
Welcome to submit issues or pull requests to improve the best practices of blockchain and large model fusion. When contributing code, please ensure:
- Passing basic verification such as `go fmt` and `go test`;
- Supplementing documentation or comments for new modules;
- Following the [document review process](docs/documentation-review.md), marking updated sections in PR.
## License Agreement
The project follows the MIT License, see [`LICENSE`](LICENSE) file for details.
Connection Info
You Might Also Like
No recommendations available