Chess MCP Development

Development guidelines for building and maintaining the Chess MCP Server - a chess engine and game server using the Model Context Protocol.

Code Style & Architecture

1. **Use TypeScript for all source files**

- Maintain proper types and interfaces throughout

- No implicit `any` types

- Use strict TypeScript configuration

2. **Direct TypeScript Execution**

- Use `tsx` for execution (no build step needed)

- Run with: `npx tsx src/index.ts`

- No JavaScript wrapper files required

3. **Design Patterns**

- Follow modular design patterns

- Maintain clean separation of concerns

- Use dependency injection where appropriate

- Keep functions focused and single-purpose

4. **Code Quality Standards**

- Use meaningful variable and function names

- Include JSDoc comments for complex functions

- Follow consistent formatting with Prettier

- Handle errors gracefully with proper logging

AI Implementation

Core Features

1. **Transposition Tables**

- Already implemented with 1M entry limit

- LRU (Least Recently Used) eviction strategy

- Proper memory management and cleanup

2. **Iterative Deepening**

- Progressive depth search with time management

- Gradual increase in search depth

- Time-bounded execution

3. **Search Algorithms**

- Alpha-beta pruning implementation

- Move ordering optimization

- Efficient position evaluation

4. **Memory Management**

- LRU eviction for cache control

- Defined size limits

- Proper cleanup routines

Performance Targets

Testing Requirements

Test Coverage

1. **Unit Tests**

- All core chess engine functionality

- Move generation and validation

- Position evaluation functions

- AI algorithm components

2. **Integration Tests**

- MCP server functionality

- Tool registration and invocation

- Protocol compliance

3. **Performance Tests**

- AI response times

- Memory usage under load

- Search efficiency benchmarks

4. **Edge Cases**

- Checkmate detection

- Stalemate scenarios

- Special moves (castling, en passant, promotion)

- Invalid move handling

Running Tests

```bash

Run all tests

npm test

Run specific test suite

npm test -- --testPathPattern="chess-engine"

Watch mode

npm test -- --watch

```

Test Requirements

MCP Integration

Server Configuration

```json

{

"mcpServers": {

"chess": {

"name": "Chess MCP",

"type": "stdio",

"command": "npx",

"args": ["tsx", "/path/to/Chess-MCP/src/index.ts"]

}

}

}

```

Protocol Implementation

Git Workflow

Commit Standards

Pre-Commit Checklist

Performance Benchmarks

Track and maintain these performance characteristics:

Documentation

Maintenance Requirements

Code Documentation

Quick Reference

```bash

Development mode

npm run dev

Run MCP server

npx tsx src/index.ts

Format code

npm run format

Lint code

npm run lint

Type check

npm run typecheck

```

Architecture Notes

Key Constraints

1. Maximum search depth: 8 plies

2. Time limit: 5 seconds per move

3. Transposition table: 1M entries max

4. Memory: Controlled with LRU eviction

5. TypeScript: Strict mode enabled