Kleros Court MCP

🚀 Kleros MCP Server

A Model Context Protocol (MCP) server that retrieves comprehensive Kleros court dispute data including meta-evidence and evidence submissions from multiple blockchain networks.

✨ Features

• 🔗 Multi-chain Support: Supports both the Ethereum Mainnet and Gnosis Chain.
• 📊 Comprehensive Data: Offers meta-evidence, evidence submissions, and IPFS content.
• 🌐 Remote Hosting Ready: Enables streamable HTTP transport with session management.
• 🔒 Secure: Comes with DNS rebinding protection and proper CORS configuration.
• ⚡ Fast: Retrieves IPFS content in parallel and handles errors effectively.
• 📱 Claude Desktop Compatible: Allows direct URL integration.

📦 Supported Networks

• Ethereum Mainnet (chainId: 1)
• Gnosis Chain (chainId: 100)

📦 Data Sources

• Meta-evidence API: Provides Kleros dispute metadata.
• Ethereum Subgraph: Retrieves evidence submissions on Ethereum.
• Gnosis Subgraph: Retrieves evidence submissions on Gnosis Chain.
• IPFS Gateway: Fetches evidence content via Kleros CDN.

📚 Claude Desktop Integration

Easy Setup (Recommended)

1. Open Claude Desktop Settings
   • Click on "Settings" in the sidebar.
2. Go to Connectors
   • Navigate to "Settings" → "Connectors".
3. Add Custom Connector
   • Click "Add custom connector".
   • Enter a name: Kleros Court.
   • Paste the URL: https://kleros-mcp-server-new.fly.dev/mcp.
   • Click "Add".
4. Start Using
   • The Kleros Court tool will now be available in Claude Desktop.
   • Try: "Get dispute data for dispute ID 481 on Gnosis Chain".

Alternative Configuration File Method

Add the following to your claude_desktop_config.json:

{
    "mcpServers": {
        "kleros": {
            "url": "https://kleros-mcp-server-new.fly.dev/mcp"
        }
    }
}

💻 Usage Examples

get_dispute_data

Retrieves comprehensive dispute data from Kleros, including meta-evidence and evidence submissions.

Parameters:

• disputeId (string): The dispute ID to retrieve data for.
• chainId (number): The chain ID (1 for Ethereum, 100 for Gnosis).

Example Usage:

• "Get dispute data for dispute ID 123 on Ethereum".
• "Show me details for dispute 481 on Gnosis Chain".
• "Retrieve evidence for dispute 50 on chain 100".

Sample Response:

# Kleros Dispute Data

**Dispute ID:** 481
**Chain:** Gnosis Chain (100)

## Meta-Evidence
**Title:** Web3 Security Auditor Registry
**Description:** A curated registry of verified security auditors...

## Evidence Submissions (3)

### Evidence 1
**Title:** Challenge Justification
**Description:** Pokémon is not a web3 auditor, reject the submission.
**Type:** text/plain

🚀 Quick Start

Prerequisites

• Node.js 18.x or higher
• npm or yarn

Local Development

1. Clone and install dependencies:

git clone <your-repo>
cd kleros-mcp-server
npm install

2. Build the project:

npm run build

3. Start the server:

npm start

4. Health check:

curl http://localhost:8080/health

Development Mode

For development with auto-restart:

npm run dev

🚀 Deployment

Fly.io Deployment

1. Install Fly CLI:

curl -L https://fly.io/install.sh | sh

2. Login to Fly:

fly auth login

3. Create app (update app name in fly.toml if needed):

fly apps create kleros-mcp-server-new

4. Build and deploy:

npm run build
fly deploy

5. Check deployment:

fly status
fly logs

Your MCP server will be available at: https://kleros-mcp-server-new.fly.dev/mcp

Environment Variables

Set any required environment variables:

fly secrets set ALLOWED_HOSTS=your-domain.com

📚 Documentation

API Endpoints

Health Check

GET /health

Returns server status and timestamp.

MCP Protocol

POST /mcp
GET /mcp (for SSE notifications)
DELETE /mcp (for session termination)

Main MCP protocol endpoints with session management.

Architecture

kleros-mcp-server/
├── src/
│   ├── index.ts              # Express server with Streamable HTTP transport
│   ├── server.ts             # MCP server setup and tool registration
│   ├── services/
│   │   ├── disputeService.ts # Main dispute data coordination
│   │   ├── metaEvidenceService.ts # Meta-evidence API integration
│   │   ├── subgraphService.ts     # Subgraph queries
│   │   └── ipfsService.ts         # IPFS content retrieval
│   ├── types/
│   │   └── index.ts          # TypeScript type definitions
│   └── utils/
│       └── constants.ts      # API endpoints and configuration
├── Dockerfile                # Container configuration
├── fly.toml                  # Fly.io deployment configuration
└── package.json

Error Handling

The server includes comprehensive error handling:

• Network timeouts: 10 - 15 second timeouts for external APIs.
• IPFS failures: Graceful handling of unreachable content.
• Subgraph errors: Detailed error reporting for query failures.
• Input validation: Proper validation of dispute IDs and chain IDs.

Development

Adding New Chains

1. Add chain ID to SUPPORTED_CHAIN_IDS in src/types/index.ts.
2. Add subgraph URL to API_ENDPOINTS.SUBGRAPHS in src/utils/constants.ts.
3. Add network name to NETWORK_NAMES in src/utils/constants.ts.

Testing

Test the dispute data retrieval:

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get_dispute_data",
      "arguments": {
        "disputeId": "123",
        "chainId": 1
      }
    },
    "id": 1
  }'

MCP Inspector Compliance

This server passes all MCP Inspector checks:

• ✅ Proper protocol implementation
• ✅ Correct message formatting
• ✅ Standard error codes
• ✅ Session management
• ✅ Resource cleanup

Security

• DNS rebinding protection enabled.
• CORS properly configured.
• Non-root container user.
• Input validation and sanitization.
• Graceful error handling without information leakage.

Troubleshooting

Common Issues

1. 404 Subgraph Errors: Check if subgraph URLs are up to date.
2. IPFS Timeout: Evidence content may be temporarily unavailable.
3. Invalid Dispute ID: Ensure the dispute exists on the specified chain.

Getting Help

• Create an issue in the repository.
• Check the logs: fly logs (for deployed version).
• Verify health: curl https://kleros-mcp-server-new.fly.dev/health.

📄 License

MIT

🤝 Contributing

1. Fork the repository.
2. Create your feature branch.
3. Commit your changes.
4. Push to the branch.
5. Create a Pull Request.

🆘 Support

For issues and questions:

• Create an issue in the repository.
• Check the logs: fly logs (for deployed version).
• Verify health: curl https://kleros-mcp-server-new.fly.dev/health.