MCP Server - Clusters Interface Specification v1

This repository hosts the reference implementation for the Model Context Protocol (MCP) server component dedicated to managing sovereign clusters and related assets via API version 1. This interface facilitates secure user verification, cluster entity manipulation, unique identifier (name) assignment, and controlled community association enrollment.

Prerequisites & Dependencies

Project dependencies required for operation:

{
  "@modelcontextprotocol/sdk": "^1.7.0",
  "dotenv": "^16.4.7",
  "zod": "^3.24.2"
}

Deployment Sequence

1. Dependency acquisition:

npm install

1. Configuration setup: Populate a .env configuration file with CLUSTERS_API_KEY={CLUSTERS_API_KEY} (this variable is optional for certain operations).

2. Execution command:

npm run dev

Endpoint Interaction Testing (Stdio Transport)

As this implementation utilizes the StdioServerTransport, interaction must occur via sending structured JSON-RPC 2.0 payloads through standard input. The following examples illustrate method invocation:

User Verification & Session Establishment

Requesting a Challenge Message

echo '{"jsonrpc":"2.0","id":1,"method":"get_signing_message"}' | node dist/index.js

Exchanging Credentials for an Authorization Token

echo '{"jsonrpc":"2.0","id":1,"method":"get_auth_key","params":{"signature":"0x123","signingDate":"2024-05-07","type":"evm","wallet":"0x123"}}' | node dist/index.js

Verifying Token Validity

echo '{"jsonrpc":"2.0","id":1,"method":"validate_auth_token","params":{"authKey":"your-auth-key"}}' | node dist/index.js

Cluster Resource Management

Provisioning a New Cluster Entity

echo '{"jsonrpc":"2.0","id":1,"method":"create_a_cluster","params":{"authKey":"your-auth-key","testnet":false}}' | node dist/index.js

Retrieving Cluster Metadata by Identifier

echo '{"jsonrpc":"2.0","id":1,"method":"get_cluster_by_id","params":{"id":"cluster-id","testnet":false}}' | node dist/index.js

Retrieving Cluster Metadata by Registered Name

echo '{"jsonrpc":"2.0","id":1,"method":"get_cluster_by_name","params":{"name":"cluster-name","testnet":false}}' | node dist/index.js

Locating Cluster Identifier via Wallet Address

echo '{"jsonrpc":"2.0","id":1,"method":"get_cluster_id_by_address","params":{"address":"0x123","testnet":false}}' | node dist/index.js

Integrating Wallet Addresses into a Cluster

echo '{"jsonrpc":"2.0","id":1,"method":"add_wallets","params":{"wallets":[{"address":"0x123","name":"new-wallet","isPrivate":false}],"authKey":"your-auth-key","testnet":false}}' | node dist/index.js

On-Demand Wallet Generation

echo '{"jsonrpc":"2.0","id":1,"method":"generate_wallet","params":{"type":"evm","name":"new-wallet","isPrivate":false,"authKey":"your-auth-key","testnet":false}}' | node dist/index.js

Modifying Associated Wallet Details

echo '{"jsonrpc":"2.0","id":1,"method":"update_wallets","params":{"wallets":[{"address":"0x123","name":"updated-name"}],"authKey":"your-auth-key","testnet":false}}' | node dist/index.js

Decommissioning Wallet Associations

echo '{"jsonrpc":"2.0","id":1,"method":"remove_wallets","params":{"addresses":["0x123"],"authKey":"your-auth-key","testnet":false}}' | node dist/index.js

Confirming Wallet Association Status

echo '{"jsonrpc":"2.0","id":1,"method":"verify_wallet","params":{"clusterId":"cluster-id","authKey":"your-auth-key","testnet":false}}' | node dist/index.js

Identity Resolution (Address/Name Mapping)

Resolving Display Name from Address

echo '{"jsonrpc":"2.0","id":1,"method":"get_name_by_address","params":{"address":"0x123","testnet":false}}' | node dist/index.js

Retrieving All Associated Names for an Address

echo '{"jsonrpc":"2.0","id":1,"method":"get_all_names_by_address","params":{"address":"0x123","testnet":false}}' | node dist/index.js

Fetching Batch Data based on Wallet Identifiers

echo '{"jsonrpc":"2.0","id":1,"method":"get_bulk_data_by_addresses","params":{"addresses":["0x123","0x456"],"testnet":false}}' | node dist/index.js

Fetching Batch Data based on Registered Names

echo '{"jsonrpc":"2.0","id":1,"method":"get_bulk_data_by_names","params":{"names":[{"name":"name-1"},{"name":"name-2"}],"testnet":false}}' | node dist/index.js

Registration Transaction Management

Checking Name Uniqueness Status

echo '{"jsonrpc":"2.0","id":1,"method":"check_name_availability","params":{"names":["name-1","name-2"],"testnet":false}}' | node dist/index.js

Generating Pre-Transaction Data for Name Acquisition

• Note: This method is currently non-functional/placeholder data generation only.

echo '{"jsonrpc":"2.0","id":1,"method":"get_registration_sign_data","params":{"network":"1","sender":"0x123","names":[{"name":"name1","amountWei":"1000000000000000000"}],"referralClusterId":"optional-id","testnet":false}}' | node dist/index.js

Querying On-Chain Transaction State

echo '{"jsonrpc":"2.0","id":1,"method":"get_transaction_status","params":{"txHash":"0x123","testnet":false}}' | node dist/index.js

Community Affiliation Endpoints

Verifying Community Name Uniqueness

echo '{"jsonrpc":"2.0","id":1,"method":"check_community_name_availability","params":{"communityName":"community-name","name":"some-name","testnet":false}}' | node dist/index.js

Enrolling a Name into a Community

echo '{"jsonrpc":"2.0","id":1,"method":"register_community_name","params":{"authKey":"your-auth-key","communityName":"some_community","name":"some_name","walletAddress":"your-wallet-address","testnet":false}}' | node dist/index.js

Operational Guidelines

1. All dynamic inputs (e.g., 0x123, your-auth-key) must be substituted with live credentials or identifiers.
2. The testnet flag is optional across all functions, defaulting appropriately based on server configuration.
3. Standard output conforms strictly to the JSON-RPC 2.0 specification.
4. For secure operations, a valid authorization credential (authKey) must be presented.
5. Server operational parameters are primarily driven by environment variables; ensure the .env file configuration aligns with deployment requirements.