ResilientDB MCP Server

# ResilientDB MCP Server A Model Context Protocol (MCP) server for interacting with ResilientDB, a high-performance blockchain platform. This server allows Large Language Models (LLMs) like Claude to interact with ResilientDB through GraphQL queries and HTTP REST API. ## Overview This MCP server bridges the gap between AI agents (like Claude Desktop) and ResilientDB by providing a standardized interface for: - **GraphQL Operations**: Asset transactions on the blockchain (port 8000) - **HTTP REST API Operations**: Key-value storage operations (port 18000 - Crow server) **Note:** For midterm, this implementation focuses on GraphQL and HTTP REST API integration. Smart contract operations (ResContract CLI) are temporarily disabled. ## Features ### GraphQL Operations (Port 8000) - `createAccount`: Create new accounts in ResilientDB (if supported) - `getTransaction`: Retrieve asset transaction details by ID (blockchain transactions) - `postTransaction`: Post new asset transactions to the blockchain (requires PrepareAsset with crypto keys) - `updateTransaction`: Update existing transactions (note: blockchain transactions are typically immutable) ### Key-Value Operations (Port 18000 - HTTP REST API) - `get`: Retrieve values by key using HTTP REST API (Crow server) - `set`: Store key-value pairs using HTTP REST API (Crow server) **Note:** For midterm, smart contract operations (compile, deploy, execute) are temporarily removed. Focus is on GraphQL and HTTP REST API integration. **Important Architecture Notes:** - **GraphQL (port 8000)**: Used for blockchain asset transactions - **HTTP/Crow (port 18000)**: Used for key-value operations ## Installation ### Prerequisites - Python 3.11 or higher - ResilientDB instance running (see [ResilientDB Installation](https://github.com/apache/incubator-resilientdb)) - ResContract CLI installed (for smart contract operations) - Access to ResilientDB GraphQL endpoint ### Local Installation 1. Clone the repository: ```bash git clone https://github.com/rahulkanagaraj786/ResilientDB-MCP.git cd ResilientDB-MCP ``` 2. Install dependencies: ```bash pip install -r requirements.txt ``` 3. Configure environment variables: ```bash cp .env.example .env # Edit .env with your ResilientDB configuration ``` 4. Update `.env` file with your settings: ```env RESILIENTDB_GRAPHQL_URL=http://localhost:8000/graphql RESILIENTDB_HTTP_URL=http://localhost:18000 ``` ### Docker Installation 1. Build the Docker image: ```bash docker build -t mcp/resilientdb -f Dockerfile . ``` 2. Run the container: ```bash docker run -i --rm mcp/resilientdb ``` ## Configuration ### Environment Variables | Variable | Description | Default | |----------|-------------|---------| | `RESILIENTDB_GRAPHQL_URL` | GraphQL endpoint URL (port 8000 for asset transactions) | `http://localhost:8000/graphql` | | `RESILIENTDB_HTTP_URL` | HTTP/Crow server URL (port 18000 for KV operations) | `http://localhost:18000` | | `RESILIENTDB_API_KEY` | Optional API key for authentication | None | | `RESILIENTDB_AUTH_TOKEN` | Optional auth token | None | | `REQUEST_TIMEOUT` | Request timeout in seconds | `30` | | `TRANSACTION_POLL_INTERVAL` | Polling interval for transactions | `1.0` | | `MAX_POLL_ATTEMPTS` | Maximum polling attempts | `30` | **Important Notes:** - GraphQL (port 8000) is used for **asset transactions** (blockchain) - HTTP/Crow (port 18000) is used for **key-value operations** (simple storage) ## Usage with Claude Desktop Add the MCP server to your Claude Desktop configuration: 1. Open Claude Desktop settings 2. Edit the MCP servers configuration file (usually `claude_desktop.json`) 3. Add the following configuration: ### For Local Installation: ```json { "mcpServers": { "resilientdb": { "command": "python", "args": ["/path/to/ResilientDB-MCP/server.py"], "env": { "RESILIENTDB_GRAPHQL_URL": "http://localhost:8000/graphql", "RESILIENTDB_HTTP_URL": "http://localhost:18000" } } } } ``` ### For Docker Installation: ```json { "mcpServers": { "resilientdb": { "command": "docker", "args": ["run", "-i", "--rm", "mcp/resilientdb"] } } } ``` 4. Restart Claude Desktop ## Available Tools ### createAccount Create a new account in ResilientDB. **Parameters:** - `accountId` (optional): Account ID. If not provided, server will generate one. **Example:** ```json { "accountId": "my-account-123" } ``` ### getTransaction Get asset transaction details by transaction ID (GraphQL - port 8000). **Parameters:** - `transactionId` (required): Transaction ID to retrieve **Example:** ```json { "transactionId": "tx-123456" } ``` **Note:** This is for blockchain asset transactions, not KV transactions. ### postTransaction Post a new asset transaction to ResilientDB (GraphQL - port 8000). **Parameters:** - `data` (required): Transaction data in PrepareAsset format with crypto keys and signatures **Example:** ```json { "data": { "operation": "CREATE", "asset": { "data": {...} }, "outputs": [...], "inputs": [...] } } ``` **Note:** This requires PrepareAsset format with cryptographic keys. For simple KV operations, use the `set` tool instead. ### updateTransaction Update an existing transaction. **Parameters:** - `transactionId` (required): Transaction ID to update - `data` (required): Updated transaction data **Example:** ```json { "transactionId": "tx-123456", "data": { "status": "completed" } } ``` ### get Retrieve a value from ResilientDB by key (HTTP REST API - port 18000). **Parameters:** - `key` (required): Key to retrieve **Example:** ```json { "key": "my-key" } ``` **Note:** This uses HTTP REST API (Crow server on port 18000). ### set Store a key-value pair in ResilientDB (HTTP REST API - port 18000). **Parameters:** - `key` (required): Key to store - `value` (required): Value to store (can be any JSON-serializable value) **Example:** ```json { "key": "my-key", "value": "my-value" } ``` **Note:** This uses HTTP REST API (Crow server on port 18000). ## Architecture The MCP server acts as a mediator between the MCP host (Claude Desktop) and ResilientDB backend services: ``` ┌─────────────┐ ┌──────────────┐ ┌─────────────┐ │ Claude │────────▶│ MCP Server │────────▶│ ResilientDB │ │ Desktop │ │ (Python) │ │ Backend │ └─────────────┘ └──────────────┘ └─────────────┘ │ ├──▶ GraphQL Client (port 8000) │ (Asset Transactions only) │ └──▶ HTTP REST Client (port 18000) (Key-Value Operations) ``` ### Routing Logic The server automatically routes requests to the appropriate service: - **Asset Transactions** → GraphQL API (port 8000) - `getTransaction`: Retrieve asset transactions - `postTransaction`: Post asset transactions (requires PrepareAsset) - `createAccount`: Create accounts (if supported) - `updateTransaction`: Update transactions (if supported) - **Key-Value Operations** → HTTP REST API (port 18000 - Crow server) - `get`: Retrieve key-value pairs - `set`: Store key-value pairs **Important:** KV operations use HTTP REST API (port 18000). ## Development ### Project Structure ``` ResilientDB-MCP/ ├── server.py # Main MCP server implementation ├── graphql_client.py # GraphQL client for ResilientDB ├── rescontract_client.py # ResContract CLI client ├── config.py # Configuration management ├── requirements.txt # Python dependencies ├── Dockerfile # Docker configuration └── README.md # This file ``` ### Running Tests ```bash # Install test dependencies pip install pytest pytest-asyncio # Run tests pytest ``` ### Contributing 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Submit a pull request ## Troubleshooting ### ResContract CLI Not Found If you get an error about ResContract CLI not being found: 1. Ensure ResContract CLI is installed 2. Add it to your PATH, or 3. Set `RESCONTRACT_CLI_PATH` environment variable to the full path ### GraphQL Connection Errors If you encounter GraphQL connection errors: 1. Verify ResilientDB is running 2. Check the `RESILIENTDB_GRAPHQL_URL` is correct (should be port 8000, not 9000) 3. Ensure network connectivity to the GraphQL endpoint 4. Check firewall settings 5. Verify GraphQL server is accessible: `curl http://localhost:8000/graphql` ### HTTP Connection Errors If you encounter HTTP connection errors for KV operations: 1. Verify Crow HTTP server is running on port 18000 2. Check the `RESILIENTDB_HTTP_URL` is correct 3. Test HTTP endpoint: `curl http://localhost:18000/v1/transactions/test` 4. Ensure the HTTP server is accessible ### Key-Value Operations Not Working If KV operations (get/set) fail: 1. Verify you're using HTTP REST API (port 18000), not GraphQL 2. Check that Crow HTTP server is running 3. Test with curl: ```bash # Set a value curl -X POST -d '{"id":"test","value":"hello"}' http://localhost:18000/v1/transactions/commit # Get a value curl http://localhost:18000/v1/transactions/test ``` 4. Verify HTTP REST API (port 18000) is accessible for KV operations ### Transaction Timeouts If transactions timeout: 1. Increase `REQUEST_TIMEOUT` in `.env` 2. Check ResilientDB blockchain status 3. Verify network latency ## Key Architecture Insights ### Service Separation ResilientDB uses different services for different operations: 1. **GraphQL Server (Port 8000)** - Purpose: Blockchain asset transactions - Operations: `getTransaction`, `postTransaction` (with PrepareAsset) 2. **HTTP/Crow Server (Port 18000)** - Purpose: Simple key-value storage - Operations: `get`, `set` (via REST API) - Endpoints: - `POST /v1/transactions/commit` (for set) - `GET /v1/transactions/{key}` (for get) ### Why This Matters - **KV operations use HTTP REST API** (port 18000) for `set`/`get` operations - **Asset transactions use GraphQL** (port 8000) and require PrepareAsset format - **Wrong port numbers** (e.g., 9000 instead of 8000) will cause connection errors ## References - [ResilientDB GitHub](https://github.com/apache/incubator-resilientdb) - [ResilientDB Documentation](https://resilientdb.incubator.apache.org/) - [ResilientDB GraphQL API](https://beacon.resilientdb.com/docs/resilientdb_graphql) - [ResilientDB Quick Start](https://quickstart.resilientdb.com/) - [MCP Protocol Documentation](https://modelcontextprotocol.io/) ## License Apache 2.0 License ## Authors Team 10 - ECS 265 Project