relay-protocol-mcp-server

# 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
```typescript
{
  error: string,       // Simple message for LLM
  details: {          // Full details for debugging
    message: string,
    statusCode?: number,
    response?: any,
    request?: any
  }
}
```

### Pagination Pattern
- Default pagination with page/limit
- Optional `fetchAll` flag for auto-pagination
- Return pagination metadata with results
- Safety limit of 10,000 items for fetchAll

### Import Style
- Use ES modules with .js extensions
- Use type imports where applicable
- Group imports: external, internal, types

### Testing Guidelines
- Test error scenarios
- Mock HTTP requests
- Validate schema parsing
- Test pagination logic

## Key Decisions

1. **No Authentication**: Relay API is free, no API keys needed
2. **Hard-coded Configuration**: Fixed API URL and settings in config.ts
3. **No Caching**: Adds complexity without clear benefit
4. **Hybrid Pagination**: Manual control with auto-fetch option
5. **Direct Returns**: MCP SDK handles success/error states

## Common Patterns

### Tool Handler Template
```typescript
async function handleToolName(args: unknown) {
  const validated = toolSchema.parse(args);
  return await client.apiMethod(validated);
}
```

### Error Handling in Tools
```typescript
try {
  const result = await operation();
  return result;
} catch (error) {
  if (error instanceof SpecificError) {
    // Handle specific error type
  }
  throw error; // Let MCP SDK handle
}
```

## Development Workflow

1. Run `pnpm dev` for development
2. Use `pnpm typecheck` before committing
3. Run `pnpm test` for test suite
4. Use `pnpm build` for production build

## Debugging Tips

- Check console output for API request logs
- Error details include full request/response data
- Use fetchAll sparingly to avoid large responses
- Test with small datasets first

## Implemented Tools

The project implements 9 MCP tools covering all major Relay Protocol operations:

1. **`relay_get_chains`** - List supported blockchain networks
2. **`relay_get_token_price`** - Get real-time token prices
3. **`relay_get_currencies`** - Discover tokens with advanced filtering
4. **`relay_get_quote`** - Generate bridging/swap quotes
5. **`relay_swap_multi_input`** - Execute multi-chain swaps
6. **`relay_get_execution_status`** - Track request progress
7. **`relay_get_requests`** - Monitor request history
8. **`relay_transactions_index`** - Index transactions for tracking
9. **`relay_transactions_single`** - Index specific transfers/wraps

## Project Status

- ✅ All 9 tools implemented and documented
- ✅ Comprehensive TypeScript types for all API responses
- ✅ Full error handling with detailed debugging information
- ✅ Zod validation schemas integrated into tool handlers
- ✅ Complete documentation with JSDoc comments
- ✅ Node.js v20+ requirement for modern features
- ✅ Production-ready with proper build pipeline

Remember: The goal is to provide a clean, type-safe interface to Relay Protocol through MCP tools while maintaining excellent developer experience.