mcp

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