MySQL Database Server

# Contributing to MCP MySQL Server Thank you for your interest in contributing to the MCP MySQL Server! This document provides guidelines and instructions for contributing. ## Table of Contents - [Code of Conduct](#code-of-conduct) - [Getting Started](#getting-started) - [Development Setup](#development-setup) - [Making Changes](#making-changes) - [Testing](#testing) - [Submitting Changes](#submitting-changes) - [Code Style](#code-style) - [Security](#security) ## Code of Conduct - Be respectful and inclusive - Welcome newcomers and help them learn - Focus on constructive feedback - Prioritize security and safety in database operations ## Getting Started ### Prerequisites - Node.js 18 or higher - TypeScript knowledge - MySQL database for testing - Familiarity with the MCP protocol ### Development Setup 1. **Fork and Clone** ```bash git clone https://github.com/your-username/mcp-mysql-server.git cd mcp-mysql-server ``` 2. **Install Dependencies** ```bash npm install ``` 3. **Configure Environment** ```bash cp .env.example .env # Edit .env with your test database credentials ``` 4. **Build the Project** ```bash npm run build ``` 5. **Test the Server** ```bash npm start ``` ### Project Structure ``` mcp-mysql-server/ ├── src/ │ └── index.ts # Main server implementation ├── dist/ # Compiled output (generated) ├── examples/ # Documentation and guides │ ├── claude-code-setup.md │ ├── codex-cli-setup.md │ └── usage-examples.md ├── .env.example # Environment template ├── package.json ├── tsconfig.json ├── README.md ├── CONTRIBUTING.md └── LICENSE ``` ## Making Changes ### Types of Contributions We welcome: 1. **Bug Fixes**: Fix identified bugs or issues 2. **Features**: Add new tools or capabilities 3. **Documentation**: Improve guides and examples 4. **Tests**: Add test coverage 5. **Performance**: Optimize query execution or connections 6. **Security**: Enhance safety features ### Branch Naming Use descriptive branch names: - `feature/add-transaction-support` - `bugfix/connection-pool-leak` - `docs/improve-setup-guide` - `security/enhance-input-validation` ### Commit Messages Follow conventional commits format: ``` type(scope): brief description Longer description if needed Fixes #123 ``` Types: - `feat`: New feature - `fix`: Bug fix - `docs`: Documentation changes - `refactor`: Code refactoring - `test`: Adding tests - `security`: Security improvements - `perf`: Performance improvements Examples: ``` feat(tools): add transaction support for multi-query operations Add new mysql_transaction tool that allows executing multiple queries within a single transaction with rollback support. Fixes #45 ``` ``` security(validation): enhance table name validation Improve regex pattern to prevent potential SQL injection through table name parameter. ``` ## Testing ### Manual Testing 1. **Test Database Setup** ```bash # Create a test database mysql -u root -p -e "CREATE DATABASE mcp_test" mysql -u root -p mcp_test < test/schema.sql ``` 2. **Test Basic Operations** ```bash # Build and run npm run build npm start ``` 3. **Test with MCP Client** - Configure the server in Claude Code or Codex CLI - Test all four tools (query, list_tables, describe_table, get_database_info) - Test safety features (blocked operations) - Test parameterized queries ### Test Checklist - [ ] All tools respond correctly - [ ] Safety features work (INSERT/UPDATE/DELETE blocking) - [ ] DROP/TRUNCATE/ALTER are always blocked - [ ] Parameterized queries prevent SQL injection - [ ] Error messages are clear and helpful - [ ] Connection pooling works correctly - [ ] Server logs to stderr (not stdout) ## Submitting Changes ### Pull Request Process 1. **Create Pull Request** - Use a clear, descriptive title - Reference any related issues - Provide detailed description of changes - Include testing steps 2. **Pull Request Template** ```markdown ## Description Brief description of the changes ## Type of Change - [ ] Bug fix - [ ] New feature - [ ] Documentation update - [ ] Security enhancement ## Testing - [ ] Manual testing completed - [ ] All existing features still work - [ ] Safety features verified ## Related Issues Fixes #123 ## Checklist - [ ] Code follows project style - [ ] Documentation updated - [ ] No security vulnerabilities introduced ``` 3. **Review Process** - Maintainers will review your PR - Address any feedback or requested changes - Once approved, your PR will be merged ## Code Style ### TypeScript Guidelines 1. **Use TypeScript Features** ```typescript // Good: Use proper types function validateQuery(query: string): { allowed: boolean; reason?: string } // Avoid: Using 'any' function validateQuery(query: any): any ``` 2. **Naming Conventions** - Use `camelCase` for variables and functions - Use `PascalCase` for classes and types - Use `UPPER_CASE` for constants ```typescript const ALLOW_INSERT = process.env.ALLOW_INSERT_OPERATION === "true"; function validateQuery(query: string) { } class DatabaseManager { } ``` 3. **Error Handling** ```typescript // Always include helpful error messages try { const [rows] = await pool.execute(query, params); return { success: true, rows }; } catch (error: any) { return { error: error.message, code: error.code, sqlState: error.sqlState, }; } ``` 4. **Comments and Documentation** ```typescript /** * Validates SQL query against operation restrictions * @param query - The SQL query string to validate * @returns Validation result with allowed status and optional reason */ function validateQuery(query: string): { allowed: boolean; reason?: string } { // Check for blocked operations } ``` ### Code Organization 1. **Keep Functions Focused** - Each function should have a single responsibility - Extract complex logic into separate functions 2. **Use Descriptive Names** ```typescript // Good function validateTableName(name: string): boolean // Avoid function check(n: string): boolean ``` 3. **Consistent Formatting** - Use 2 spaces for indentation - Add spaces around operators - Use semicolons consistently ## Security ### Security First Mindset 1. **Always Use Prepared Statements** ```typescript // Good const [rows] = await pool.execute("SELECT * FROM users WHERE email = ?", [email]); // NEVER do this const [rows] = await pool.execute(`SELECT * FROM users WHERE email = '${email}'`); ``` 2. **Validate All Inputs** ```typescript // Validate table names before use if (!/^[a-zA-Z0-9_]+$/.test(tableName)) { throw new Error("Invalid table name"); } ``` 3. **Default to Safe** - All destructive operations should be disabled by default - Require explicit configuration to enable write operations 4. **Never Expose Sensitive Data** ```typescript // Don't include passwords in logs console.error(`Connected to: ${host}:${port}/${database}`); // Don't log: `Connected as: ${user}:${password}@${host}` ``` ### Reporting Security Issues If you discover a security vulnerability: 1. **Do NOT** open a public issue 2. Email the maintainers directly 3. Provide details: impact, reproduction steps, suggested fix 4. Allow time for patching before public disclosure ## Feature Guidelines ### Adding New Tools When adding a new MCP tool: 1. **Define the Tool** ```typescript { name: "mysql_new_tool", description: "Clear description of what the tool does", inputSchema: { type: "object", properties: { // Define parameters }, required: ["param1"], }, } ``` 2. **Implement Handler** ```typescript case "mysql_new_tool": { // Validate inputs // Perform operation safely // Return structured response } ``` 3. **Update Documentation** - Add to README.md - Add examples to usage-examples.md - Update integration guides if needed 4. **Consider Security** - What could go wrong? - Does it need permission flags? - Is input properly validated? ### Adding Configuration Options 1. **Use Environment Variables** ```typescript const NEW_OPTION = process.env.NEW_OPTION === "true"; ``` 2. **Update .env.example** ```env # Description of the option NEW_OPTION=false ``` 3. **Document in README** - Explain the option - Provide use cases - Show configuration examples ## Documentation ### Writing Good Documentation 1. **Be Clear and Concise** - Use simple language - Provide examples - Explain the "why" not just the "how" 2. **Update All Relevant Files** - README.md for main features - Integration guides for setup - Usage examples for patterns 3. **Include Code Examples** ```markdown ## Feature Name Description of feature. **Example:** \`\`\`typescript // Code example \`\`\` ``` 4. **Keep Examples Up to Date** - Test all code examples - Update when APIs change - Remove outdated information ## Questions? - Open an issue for questions - Check existing issues and discussions - Review [examples](examples/) directory - Read the [README](README.md) ## License By contributing, you agree that your contributions will be licensed under the MIT License. ## Recognition Contributors will be recognized in: - GitHub contributors list - Release notes for significant contributions - Project documentation for major features Thank you for contributing to MCP MySQL Server!