mcp cw graph

A Model Context Protocol (MCP) server for interacting with the CW-Social smart contract on Cosmos-based blockchains. This server provides a standardized interface for creating, updating, and querying cyberlinks - semantic relationships between entities on the blockchain.

Features

• Full CRUD operations for cyberlinks
• Named cyberlink support
• Batch operations
• Rich query capabilities
• Transaction status tracking
• Input validation
• Error handling
• Integration with Cursor IDE and Claude Desktop

Prerequisites

• Node.js 16+
• npm or yarn
• Access to a Cosmos blockchain node
• Wallet with funds for transactions
• Cursor IDE installed
• Claude Desktop installed

Installation and Setup

1. Clone the repository:

   git clone https://github.com/your-org/cw-social-mcp.git
   cd cw-social-mcp

2. Install dependencies:

   npm install

3. Build the project:

   npm run build

Integration Configuration

Both Cursor IDE and Claude Desktop use the same MCP configuration format. Create or edit the configuration file:

• For Cursor: ~/.cursor/mcp.json

Add the following configuration:

{
    "mcpServers": {
        "cw-graph": {
        "command": "node",
        "args": ["PATH_TO_YOUR_PROJECT/dist/index.js"],
        "env": {
            "NODE_URL": "http://localhost:26657",
            "WALLET_MNEMONIC": "your wallet mnemonic phrase",
            "CONTRACT_ADDRESS": "your contract address",
            "DENOM": "stake"
            }
        }
    }
}

Replace the following values: - PATH_TO_YOUR_PROJECT: Absolute path to your cw-social-mcp project - NODE_URL: Your Cosmos node URL - WALLET_MNEMONIC: Your wallet's mnemonic phrase - CONTRACT_ADDRESS: Your deployed contract address - DENOM: (Optional) Token denomination, defaults to 'stake'

The configuration uses stdio format for communication between the MCP server and the clients (Cursor/Claude Desktop).

Verification

1. Restart Cursor IDE or Claude Desktop after configuration
2. The following tools should be available:
3. create_cyberlink
4. create_named_cyberlink
5. create_cyberlinks
6. update_cyberlink
7. delete_cyberlink
8. query_cyberlinks
9. query_named_cyberlinks
10. query_cyberlinks_by_owner
11. query_config
12. query_wallet_balance
13. send_tokens

Development

1. Build the project:

   npm run build

2. Start the server in development mode:

   npm run dev

Project Structure

src/
├── index.ts             # Main entry point
├── cyberlink-service.ts # Cyberlink and blockchain operations
└── types.ts             # TypeScript types and schemas

cursor_rules/
└── chat_history.mdc    # Rules for chat history storage

Cursor Rules

The project includes cursor rules that define behavior for specific features:

• Chat History Storage: Rules defining how chat history is stored and managed within the system. These rules ensure consistent handling of conversation data across the MCP server.

Copy rules into ./cursor/rules directory

MCP Tools

Creation and Modification

• mcp_cw_graph_create_cyberlink - Create a new cyberlink
• mcp_cw_graph_create_named_cyberlink - Create a named cyberlink with identifier
• mcp_cw_graph_create_cyberlinks - Create multiple cyberlinks in batch
• mcp_cw_graph_update_cyberlink - Update an existing cyberlink by ID
• mcp_cw_graph_delete_cyberlink - Delete a cyberlink by ID

Basic Queries

• mcp_cw_graph_query_by_id - Query a single cyberlink by numeric ID
• mcp_cw_graph_query_by_formatted_id - Query a cyberlink by its formatted ID
• mcp_cw_graph_query_cyberlinks - Query all cyberlinks with pagination
• mcp_cw_graph_query_named_cyberlinks - Query all named cyberlinks
• mcp_cw_graph_query_by_ids - Query multiple cyberlinks by their IDs

Advanced Queries

• mcp_cw_graph_query_by_owner - Query cyberlinks by owner address
• mcp_cw_graph_query_by_time_range - Query cyberlinks by creation time range
• mcp_cw_graph_query_by_time_range_any - Query cyberlinks by creation or update time range

System Queries

• mcp_cw_graph_query_last_id - Get the last assigned cyberlink ID
• mcp_cw_graph_query_config - Query contract configuration
• mcp_cw_graph_query_debug_state - Query contract debug state (admin only)
• mcp_cw_graph_get_tx_status - Check transaction status and get cyberlink IDs

Wallet Operations

• mcp_cw_graph_query_wallet_balance - Get wallet address and token balances
• mcp_cw_graph_send_tokens - Send tokens to another wallet address

Query Parameters

Time Range Queries

• owner - Owner address to filter by
• start_time - Start time in nanoseconds (Uint64, can be passed as string or number)
• end_time - Optional end time in nanoseconds (Uint64, can be passed as string or number)
• start_after - Optional pagination cursor (Uint64, can be passed as string or number)
• limit - Optional result limit (default: 50)

Pagination

Most query endpoints support pagination with: - start_after - Cursor for the next page (Uint64, can be passed as string or number) - limit - Maximum number of results to return

Data Types

• Timestamps: All timestamp fields use Uint64 format (nanoseconds since Unix epoch)
• Can be passed as string to preserve precision for large values
• Also accepts number format for backward compatibility
• Example: "1683900000000000000" (string) or 1683900000000000000 (number)

Error Handling

The server uses standardized error codes from the MCP protocol: - InvalidParams - Invalid input parameters - MethodNotFound - Unknown tool name - InternalError - Blockchain or server errors

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.