Instruction file imported from sunra-ai/sunra-clients (.cursor/rules/mcp.mdc). Copyright stays with the author.

MCP Server Development Rules

Overview

This file contains rules and guidelines for developing MCP (Model Context Protocol) servers using fast-mcp and TypeScript, specifically for integrating with Sunra.ai services.

Technology Stack

• Runtime: Node.js with TypeScript
• Framework: FastMCP (fast-mcp library)
• Language: TypeScript with strict type checking
• Package Manager: npm or pnpm
• API Client: @sunra/client for Sunra.ai integration

Project Structure Standards

Directory Layout

mcp-server/
├── src/
│   ├── index.ts           # Main server entry point
│   ├── tools/             # MCP tools implementation
│   │   └── base.ts        # base functions such as submit, status, result, cancel
│   │   └── models
│   │     └── provider1    # group tools by provider name
│   │       └── model1.ts  # add each endpoint as a standalone tool in [model name].ts
│   │       └── model2.ts
│   │     └── provider2
│   ├── resources/         # MCP resources (if needed)
│   ├── prompts/           # MCP prompts (if needed)
│   ├── types/             # TypeScript type definitions
│   └── utils/             # Utility functions
├── dist/                  # Compiled JavaScript
├── package.json
├── tsconfig.json
├── README.md
└── .env.example

File Naming Conventions

• Use kebab-case for file names: text-to-image.ts
• Use PascalCase for class names: TextToImageTool
• Use camelCase for function and variable names: generateImage
• Use UPPER_SNAKE_CASE for constants: DEFAULT_TIMEOUT

Code Standards

TypeScript Configuration

• Enable strict mode: "strict": true
• Use ES2020 or later target
• Enable experimental decorators if needed
• Include proper type definitions for all dependencies
• Use 2 space indent size

Error Handling

• Always wrap async operations in try-catch blocks
• Use specific error types for different failure modes
• Provide meaningful error messages to users
• Log errors appropriately for debugging

Documentation

• Use JSDoc comments for all public functions and classes
• Document parameter types and return values
• Include usage examples in documentation
• Explain complex business logic with inline comments

MCP Server Implementation Guidelines

Server Setup

• Use FastMCP's FastMCPServer class for server creation
• Configure both stdio and HTTP transport options
• Set up proper error handling middleware
• Include health check endpoints for HTTP mode

Tool Implementation

• Each tool should have a single, well-defined responsibility
• Use Zod schemas for input validation
• Implement proper error handling and user feedback
• Support both synchronous and asynchronous operations where appropriate

Tool Categories for Sunra.ai Integration

1. Base Tools

   • submit: Submit a request
   • status: Query the status of a request
   • result: Get the result of a request
   • cancel: Cancel a request
   • subscribe: Submit and wait for status to be determined(COMPLETED, FAILED or CANCELED).

2. Model Endpoint Tools

   • [provider]/[model]/[endpoint]: A specific model endpoint, such as black-forest-labs/flux-kontext-max/text-to-image

Input Validation

• Use Zod schemas for all tool inputs
• Validate file uploads and URLs
• Implement reasonable limits on input sizes
• Provide clear error messages for invalid inputs

Authentication

• Support API key authentication via environment variables
• Implement secure credential handling
• Allow configuration override through MCP server config

API Integration Best Practices

Sunra.ai Client Usage

• Use the official @sunra/client package
• Implement proper error handling for API failures
• Support both polling and streaming modes for queue operations
• Handle rate limiting and retry logic appropriately

Response Handling

• Always return structured data with proper typing
• Include metadata like request IDs and processing times
• Provide progress updates for long-running operations
• Handle partial failures gracefully

Resource Management

• Implement proper cleanup for temporary files
• Use streaming for large file operations
• Implement timeouts for long-running requests
• Clean up resources on server shutdown

Configuration Management

Environment Variables

• SUNRA_KEY: Required API key for Sunra.ai
• MCP_SERVER_PORT: Port for HTTP mode (default: 3000)
• MCP_LOG_LEVEL: Logging level (debug, info, warn, error)
• MCP_TIMEOUT: Default timeout for operations (default: 300000ms)

Configuration Files

• Support .env files for local development
• Allow configuration through MCP server config
• Implement configuration validation on startup

Testing Standards

Unit Testing

• Write tests for all utility functions
• Mock external API calls appropriately
• Test error conditions and edge cases
• Use Vitest testing framework

Integration Testing

• Test MCP tool implementations end-to-end
• Verify proper error handling with external APIs
• Test configuration and environment setup
• Include performance benchmarks for critical operations

Security Considerations

API Key Handling

• Never log or expose API keys in code
• Use environment variables for sensitive configuration
• Implement proper error messages that don't leak credentials
• Support key rotation without server restart

Input Sanitization

• Validate all user inputs before processing
• Sanitize file paths and URLs
• Implement upload size limits
• Check file types and content validation

Rate Limiting

• Implement client-side rate limiting
• Handle API rate limit responses gracefully
• Provide user feedback on rate limit status
• Queue requests when limits are exceeded

Performance Optimization

Caching Strategy

• Cache frequently accessed resources
• Implement TTL for cached items
• Use appropriate cache keys and invalidation
• Consider memory usage for large cached items

Concurrent Processing

• Use appropriate concurrency limits
• Implement queuing for high-volume operations
• Handle backpressure appropriately
• Monitor resource usage under load

Deployment Guidelines

Package Management

• Use exact versions for critical dependencies
• Include proper build scripts in package.json
• Implement health checks for deployed servers
• Support both development and production modes

Docker Support

• Provide Dockerfile for containerized deployment
• Use multi-stage builds for optimized images
• Include proper environment variable handling
• Support orchestration with docker-compose

Monitoring and Logging

Logging Standards

• Use structured logging with appropriate levels
• Include request IDs for tracing
• Log performance metrics for operations
• Implement log rotation and retention policies

Health Monitoring

• Implement health check endpoints
• Monitor API response times and error rates
• Track resource usage (memory, CPU, storage)
• Set up alerts for critical failures

Development Workflow

Code Organization

• Group related functionality in modules
• Use barrel exports for clean imports
• Implement proper separation of concerns
• Follow single responsibility principle

Version Control

• Use semantic versioning for releases
• Write clear commit messages
• Include migration guides for breaking changes
• Tag releases appropriately

Documentation Updates

• Update README with new features
• Maintain changelog for user-facing changes
• Document configuration options
• Provide troubleshooting guides

Common Patterns

Error Response Format

interface MCPError {
  code: string;
  message: string;
  details?: Record<string, any>;
}

Tool Response Format

interface ToolResponse<T = any> {
  content: Array<{
    type: "text" | "image" | "resource";
    text?: string;
    data?: T;
  }>;
  isError?: boolean;
}

Configuration Schema

interface ServerConfig {
  apiKey: string;
  timeout?: number;
  retryAttempts?: number;
  logLevel?: 'debug' | 'info' | 'warn' | 'error';
}

Performance Targets

Response Times

• Tool execution: < 5 seconds for most operations
• Queue status checks: < 1 second
• Health checks: < 100ms
• Server startup: < 10 seconds

Resource Usage

• Memory usage: < 512MB for basic operations
• CPU usage: < 50% during normal operation
• Disk usage: Minimal, with proper cleanup
• Network: Efficient use of API calls

Troubleshooting Guidelines

Common Issues

1. API Key Problems: Verify environment variables and permissions
2. Timeout Issues: Check network connectivity and increase timeout values
3. Memory Issues: Monitor for memory leaks in long-running operations
4. Rate Limiting: Implement exponential backoff and user feedback

Debug Information

• Include request/response debugging when log level is debug
• Provide clear error messages with actionable steps
• Include relevant context in error reports
• Implement graceful degradation when possible

Future Considerations

Extensibility

• Design for easy addition of new AI models
• Support plugin architecture for custom tools
• Implement configuration-driven tool registration
• Plan for multi-tenant usage patterns

Scalability

• Design for horizontal scaling
• Implement proper connection pooling
• Consider caching strategies for high-volume usage
• Plan for load balancing and failover scenarios