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)

• ResContract CLI installed (for smart contract operations)

• Access to ResilientDB GraphQL endpoint

Local Installation

1. Clone the repository:

2. Install dependencies:

3. Configure environment variables:

4. Update .env file with your settings:

Docker Installation

1. Build the Docker image:

2. Run the container:

Configuration

Environment Variables

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:

For Docker Installation:

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:

getTransaction

Get asset transaction details by transaction ID (GraphQL - port 8000).

Parameters:

• transactionId (required): Transaction ID to retrieve

Example:

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:

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:

get

Retrieve a value from ResilientDB by key (HTTP REST API - port 18000).

Parameters:

• key (required): Key to retrieve

Example:

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:

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:

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

Running Tests

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:

   # 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

• ResilientDB Documentation

• ResilientDB GraphQL API

• ResilientDB Quick Start

• MCP Protocol Documentation

License

Apache 2.0 License

Authors

Team 10 - ECS 265 Project