# Cursor AI Rules

This file provides guidance to Cursor AI when working with code in this repository.

## Development Commands

```bash
# Build the project
npm run build

# Development with hot reloading (builds and starts server with watch mode)
npm run dev

# Start the production server
npm start

# Testing
npm test               # Run tests with vitest in watch mode
npm run test:ci        # Run tests once with JSON output for CI

# Code quality
npm run lint           # Check for linting issues
npm run lint:fix       # Fix auto-fixable linting issues
npm run format         # Format code with Prettier
npm run format:check   # Check code formatting
```

## Architecture Overview

This is a TypeScript template for building Model Context Protocol (MCP) servers. The architecture follows a simple two-layer pattern:

### Core Components

- **`src/index.ts`** - Main MCP server entry point that:
  - Sets up the stdio server transport for inter-process communication
  - Defines all available MCP tools with their JSON schemas
  - Connects to the transport via stdin/stdout
  - Handles error responses in MCP format
- **`src/config.ts`** - Environment configuration with validation using Zod
- **`src/logger.ts`** - Structured logging with Pino (OpenTelemetry compatible)
- **`src/lib/utils.ts`** - Utility functions for MCP response formatting

### Template MCP Tools Available

The template includes one example tool to demonstrate MCP tool implementation:
- `listClassesByDataGroup` - List classes for an Elephant data group with names and descriptions

### Build System

- Uses Vite for building with ES modules output format
- TypeScript compilation targeting Node.js 22.18+ (native type stripping enabled by default)
- External dependency: `@modelcontextprotocol/sdk` (not bundled)
- Source alias `@` points to `src/` directory
- Output goes to `dist/` directory

### Testing

- Uses Vitest as the test runner and framework
- Test files should be placed alongside source files with `.test.ts` extension
- Vitest provides built-in TypeScript support and ES modules compatibility
- Run `npm test` for watch mode development testing
- Run `npm run test:ci` for CI/automated testing with JSON output

### Code Style

- ESLint with TypeScript recommended rules
- Prettier formatting (empty config uses defaults)
- Private class methods use `#` syntax
- Unused parameter pattern: prefix with `_`
- `@typescript-eslint/no-explicit-any` set to warn (used for MCP argument flexibility)

## Key Implementation Details

- All tool responses are wrapped in MCP `content` format with `type: 'text'` and JSON stringified data
- Server runs as stdio transport for local inter-process communication
- No HTTP server or port configuration required
- Server communicates via stdin/stdout with parent process
- Error handling returns MCP-formatted error messages rather than throwing
- **Structured Logging**: Uses Pino for production-ready logging with OpenTelemetry trace correlation
- **Configuration Management**: Environment variables validated with Zod schemas
- **Graceful Shutdown**: Proper SIGTERM/SIGINT handling for process termination

## Template Usage

This is a template project for creating new MCP servers. To customize:

1. Update `package.json` with your project name and description
2. Update environment variables in `src/config.ts` (SERVER_NAME, SERVER_VERSION, etc.)
3. Replace the echo tool in `src/index.ts` with your custom tools
4. Add additional TypeScript files for business logic as needed
5. Update README.md to document your specific MCP server functionality
6. Modify this .cursorrules file to reflect your project's architecture

## Environment Variables

The following environment variables are supported (see `src/config.ts`):

- `NODE_ENV` - Environment (development/production/test)
- `SERVER_NAME` - MCP server name (default: mcp-typescript-template)
- `SERVER_VERSION` - Server version (default: 1.0.0)
- `LOG_LEVEL` - Logging level (error/warn/info/debug, default: info)

## Coding Guidelines

- Follow existing patterns in the codebase
- Use TypeScript strict mode
- Prefer functional programming patterns where appropriate
- Keep methods focused and single-responsibility
- Use meaningful variable and function names
- Add JSDoc comments for public APIs
- **Use structured logging**: Always use the `logger` from `src/logger.ts` instead of `console.log`
- **Environment variables**: Add new config to `src/config.ts` with Zod validation
- **Error handling**: Use try-catch blocks and log errors with context using structured logging

## Logging Best Practices

- Use appropriate log levels: `error`, `warn`, `info`, `debug`
- Include relevant context in log messages (user IDs, session IDs, etc.)
- Log structured data as the second parameter: `logger.info("message", { key: value })`
- Error logs should include error details: `logger.error("Error message", { error: error.message })`
- The logger automatically includes trace correlation when OpenTelemetry is configured