MCP Sigmund

# Development Guide This document provides comprehensive information for developers working on MCP Sigmund. ## Development Setup ### Available Scripts - `npm run dev` - Start development server with hot reload - `npm run build` - Build the project for production - `npm start` - Run the built project - `npm run clean` - Clean build directory - `npm run rebuild` - Clean and rebuild - `npm test` - Run all tests - `npm run test:watch` - Run tests in watch mode - `npm run test:coverage` - Run tests with coverage report - `npm run test:unit` - Run unit tests only - `npm run test:integration` - Run integration tests only ### Project Structure ``` src/ ├── index.ts # Main MCP server implementation with tools and text visualizations ├── database.ts # PostgreSQL database client and query functions ├── smart-formatting.ts # Intelligent formatting and display hints ├── error-handler.ts # Error handling and validation utilities ├── logger.ts # Structured logging utilities ├── types.ts # TypeScript type definitions and interfaces ├── validation.ts # Input validation and sanitization utilities ├── auth.example.ts # Database configuration template └── auth.ts # Your actual configuration (not in git) tests/ ├── setup.ts # Test setup and teardown ├── fixtures.ts # Test data fixtures and utilities ├── database.test.ts # Database client unit tests ├── error-handler.test.ts # Error handling tests └── integration.test.ts # End-to-end integration tests ``` ## Customization ### Adding New Tools 1. Define your tool in `src/index.ts` using the `server.tool()` method 2. Implement the corresponding database functions in `src/database.ts` 3. Add validation in `src/error-handler.ts` 4. Create tests in `tests/` directory ### Database Integration The `src/database.ts` file provides: - PostgreSQL connection pooling - Generic query functions for financial data - Provider-agnostic data access - Comprehensive filtering and aggregation - Error handling and connection management ### Smart Formatting The `src/smart-formatting.ts` file provides: - Context detection algorithms - Display hint configurations - Transaction description simplification - Currency and date formatting utilities - Progressive disclosure logic ### Error Handling The `src/error-handler.ts` file provides: - Custom error classes for different error types - Input validation functions - Centralized error handling - Detailed error responses ## Testing ### Running Tests ```bash # Run all tests npm test # Run tests in watch mode npm run test:watch # Run tests with coverage npm run test:coverage # Run specific test types npm run test:unit npm run test:integration ``` ### Test Structure - **Unit Tests**: Test individual functions and modules in isolation - **Integration Tests**: Test the full MCP server functionality - **Database Tests**: Test database queries and data handling ### Writing Tests 1. Create test files in the `tests/` directory 2. Use Jest testing framework 3. Follow the existing test patterns 4. Ensure good test coverage for new features ## Building and Deployment ### Development Build ```bash npm run dev ``` ### Production Build ```bash npm run build npm start ``` ### Clean Build ```bash npm run clean npm run rebuild ``` ## Code Quality ### TypeScript - Use strict TypeScript configuration - Define proper interfaces for all data structures - Avoid `any` types - use specific types instead - Follow TypeScript best practices ### Code Style - Use consistent formatting (Prettier recommended) - Follow existing code patterns - Add JSDoc comments for public functions - Keep functions focused and single-purpose ### Error Handling - Use custom error classes from `error-handler.ts` - Validate all inputs - Provide meaningful error messages - Handle database connection errors gracefully ## Performance Considerations ### Database Queries - Use parameterized queries to prevent SQL injection - Implement proper indexing (see Database Documentation) - Use connection pooling for better performance - Monitor query performance with built-in metrics ### Memory Management - Monitor memory usage with built-in tools - Clean up resources properly - Use streaming for large data sets - Implement proper error handling to prevent memory leaks ## Security ### Input Validation - Sanitize all user inputs - Validate data types and ranges - Use parameterized queries - Implement rate limiting for production ### Configuration - Never commit sensitive configuration files - Use environment variables for secrets - Implement proper access controls - Follow security best practices ## Contributing 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Add tests if applicable 5. Ensure all tests pass 6. Submit a pull request ### Pull Request Guidelines - Include tests for new functionality - Update documentation as needed - Follow existing code style - Provide clear commit messages - Reference any related issues