npm package: @mseep/cw-social-mcp
Description: Cosmos Social Graph MCP Server
Latest version: 1.0.0

# Cyberlink MCP Server

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](https://cursor.sh/) installed
- [Claude Desktop](https://claude.ai/desktop) installed

## Installation and Setup

1. Clone the repository:
```bash
git clone https://github.com/your-org/cw-social-mcp.git
cd cw-social-mcp
```

2. Install dependencies:
```bash
npm install
```

3. Build the project:
```bash
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:

```json
{
    "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:
   - create_cyberlink
   - create_named_cyberlink
   - create_cyberlinks
   - update_cyberlink
   - delete_cyberlink
   - query_cyberlinks
   - query_named_cyberlinks
   - query_cyberlinks_by_owner
   - query_config
   - query_wallet_balance
   - send_tokens

## Development

1. Build the project:
```bash
npm run build
```

2. Start the server in development mode:
```bash
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.