relay-protocol-mcp-server copilot-instructions.md

Relay Protocol MCP Project Guidelines

You are working on a Model Context Protocol (MCP) server for the Relay Protocol API. This document outlines the project specifications and coding standards.

Project Overview

• Purpose: MCP server providing access to Relay Protocol REST API
• Language: TypeScript with Node.js
• Framework: Official MCP SDK (@modelcontextprotocol/sdk)
• API Client: Axios for HTTP requests
• Validation: Zod for schema validation

Architecture Principles

1. Separation of Concerns

• Keep API client logic separate from MCP tool handlers
• Use comprehensive TypeScript types for validation
• Separate types from implementation

2. Error Handling

• Always wrap tool handlers in try-catch blocks
• Return structured error responses with debugging details
• Distinguish between API errors, connection errors, and validation errors

3. Type Safety

• Use TypeScript strict mode
• Define all API types explicitly
• Use Zod for runtime validation matching TypeScript types

4. Tool Design

• Tools are grouped by resource (chains, prices, quotes, requests, transactions, currencies, swaps)
• All tools prefixed with relay_ to avoid conflicts
• Tool descriptions include examples
• Direct data return (no success/data wrapping)

Code Standards

File Organization

src/
├── client/       # HTTP client and error handling
├── tools/        # MCP tool implementations
├── types/        # TypeScript type definitions
├── config.ts     # Configuration settings
└── index.ts      # MCP server entry point

Naming Conventions

• Files: kebab-case (e.g., relay-client.ts)
• Classes: PascalCase (e.g., RelayClient)
• Functions: camelCase (e.g., swapMultiInput)
• Constants: UPPER_SNAKE_CASE (e.g., MAX_RETRIES)
• MCP tools: snake_case with prefix (e.g., relay_get_chains)

Error Response Format

{
  error: string,       // Simple message for LLM
  details: {          // Full details for debugging
    message: string,
    statusCode?: number,
    response?: any,
    request?: any
  }
}