From beec47c36cf5b81305e04dcba0cbda873f340fa1 Mon Sep 17 00:00:00 2001 From: Roman Marek~ Date: Tue, 7 Oct 2025 22:30:55 +0200 Subject: [PATCH 1/9] Enhance project structure and tooling support - Updated `.gitignore` to include additional files and directories for better project management. - Refactored `package.json` to move the main server file to `src/`, added Jest for testing, and integrated Husky for pre-commit checks. - Expanded `CHANGELOG.md` with new project features and improvements. - Updated `README.md` to include setup instructions, available tools, and contribution guidelines. - Removed `mcp-sqlite-server.js` as it has been relocated to the `src/` directory. --- .eslintrc.js | 33 + .github/FUNDING.yml | 30 +- .github/ISSUE_TEMPLATE/bug_report.md | 40 + .github/ISSUE_TEMPLATE/feature_request.md | 25 + .github/pull_request_template.md | 48 + .github/workflows/ci.yml | 90 + .github/workflows/release.yml | 44 + .gitignore | 139 +- .husky/pre-commit | 4 + .prettierignore | 5 + .prettierrc | 9 + CHANGELOG.md | 82 +- CONTRIBUTING.md | 246 + README.md | 564 +- eslint.config.js | 69 + jest.config.js | 49 + mcp-sqlite-server.js | 390 -- package-lock.json | 5887 ++++++++++++++++++--- package.json | 121 +- src/mcp-sqlite-server.js | 655 +++ test/README.md | 174 + test/client-simulation-test.js | 574 ++ test/error-analysis.js | 251 + test/error-handling.test.js | 472 ++ test/integration.test.js | 426 ++ test/mcp-tools.test.js | 860 +++ test/performance-test.js | 467 ++ test/quick-benchmark.js | 189 + test/setup.js | 40 + test/sqlite-handler.test.js | 265 + test/test-utils.js | 195 + test/visual-comparison.js | 127 + 32 files changed, 11044 insertions(+), 1526 deletions(-) create mode 100644 .eslintrc.js create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/pull_request_template.md create mode 100644 .github/workflows/ci.yml create mode 100644 .github/workflows/release.yml create mode 100755 .husky/pre-commit create mode 100644 .prettierignore create mode 100644 .prettierrc create mode 100644 CONTRIBUTING.md create mode 100644 eslint.config.js create mode 100644 jest.config.js delete mode 100644 mcp-sqlite-server.js create mode 100755 src/mcp-sqlite-server.js create mode 100644 test/README.md create mode 100644 test/client-simulation-test.js create mode 100644 test/error-analysis.js create mode 100644 test/error-handling.test.js create mode 100644 test/integration.test.js create mode 100644 test/mcp-tools.test.js create mode 100644 test/performance-test.js create mode 100644 test/quick-benchmark.js create mode 100644 test/setup.js create mode 100644 test/sqlite-handler.test.js create mode 100644 test/test-utils.js create mode 100644 test/visual-comparison.js diff --git a/.eslintrc.js b/.eslintrc.js new file mode 100644 index 0000000..cc1c617 --- /dev/null +++ b/.eslintrc.js @@ -0,0 +1,33 @@ +module.exports = { + env: { + node: true, + es6: true, + }, + extends: 'eslint:recommended', + parserOptions: { + ecmaVersion: 2020, + sourceType: 'commonjs', + }, + rules: { + 'no-console': 'off', // Allow console statements for server logging + 'no-unused-vars': 'warn', + 'no-undef': 'error', + semi: ['error', 'always'], + quotes: 'off', // Handled by Prettier + indent: 'off', // Handled by Prettier + }, + overrides: [ + { + files: ['test/**/*.js'], + env: { + node: true, + es6: true, + jest: true, + }, + rules: { + 'no-console': 'off', + 'no-unused-vars': 'warn', + }, + }, + ], +}; diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml index 3f6edb9..e7a845d 100644 --- a/.github/FUNDING.yml +++ b/.github/FUNDING.yml @@ -1,15 +1,15 @@ -# These are supported funding model platforms - -github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2] -patreon: # Replace with a single Patreon username -open_collective: # Replace with a single Open Collective username -ko_fi: jparkerweb -tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel -community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry -liberapay: # Replace with a single Liberapay username -issuehunt: # Replace with a single IssueHunt username -lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry -polar: # Replace with a single Polar username -buy_me_a_coffee: # Replace with a single Buy Me a Coffee username -thanks_dev: # Replace with a single thanks.dev username -custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2'] +# These are supported funding model platforms + +github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2] +patreon: # Replace with a single Patreon username +open_collective: # Replace with a single Open Collective username +ko_fi: jparkerweb +tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel +community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry +liberapay: # Replace with a single Liberapay username +issuehunt: # Replace with a single IssueHunt username +lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry +polar: # Replace with a single Polar username +buy_me_a_coffee: # Replace with a single Buy Me a Coffee username +thanks_dev: # Replace with a single thanks.dev username +custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2'] diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..27340c7 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,40 @@ +--- +name: Bug report +about: Create a report to help us improve +title: '[BUG] ' +labels: bug +assignees: '' +--- + +**Describe the bug** +A clear and concise description of what the bug is. + +**To Reproduce** +Steps to reproduce the behavior: + +1. Go to '...' +2. Click on '....' +3. Scroll down to '....' +4. See error + +**Expected behavior** +A clear and concise description of what you expected to happen. + +**Actual behavior** +A clear and concise description of what actually happened. + +**Environment (please complete the following information):** + +- Node Version: [e.g. 18.17.0] +- OS: [e.g. Windows 11, macOS 13.5, Ubuntu 22.04] +- MCP SQLite Version: [e.g. 1.0.7] +- Database Type: [e.g. SQLite 3.x] + +**Additional context** +Add any other context about the problem here. + +**Error logs** + +``` +Paste any error logs here +``` diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..1427eee --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,25 @@ +--- +name: Feature request +about: Suggest an idea for this project +title: '[FEATURE] ' +labels: enhancement +assignees: '' +--- + +**Is your feature request related to a problem? Please describe.** +A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] + +**Describe the solution you'd like** +A clear and concise description of what you want to happen. + +**Describe alternatives you've considered** +A clear and concise description of any alternative solutions or features you've considered. + +**Use case** +Describe a specific use case for this feature. How would you use it? + +**Additional context** +Add any other context or screenshots about the feature request here. + +**Implementation considerations** +If you have ideas about how this could be implemented, please share them here. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..ddf6fd0 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,48 @@ +## Description + +Brief description of what this PR does. + +## Type of Change + +- [ ] Bug fix (non-breaking change which fixes an issue) +- [ ] New feature (non-breaking change which adds functionality) +- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) +- [ ] Documentation update +- [ ] Performance improvement +- [ ] Code refactoring + +## Related Issues + +Fixes #(issue number) + +## Changes Made + +- Change 1 +- Change 2 +- Change 3 + +## Testing + +- [ ] I have added tests that prove my fix is effective or that my feature works +- [ ] New and existing unit tests pass locally with my changes +- [ ] I have tested this change manually +- [ ] I have tested with MCP Inspector (`npm run test:mcp`) + +## Checklist + +- [ ] My code follows the style guidelines of this project +- [ ] I have performed a self-review of my own code +- [ ] I have commented my code, particularly in hard-to-understand areas +- [ ] I have made corresponding changes to the documentation +- [ ] I have updated the CHANGELOG.md +- [ ] My changes generate no new warnings +- [ ] I have added tests that prove my fix is effective or that my feature works +- [ ] New and existing unit tests pass locally with my changes + +## Screenshots (if applicable) + +Add screenshots to help explain your changes. + +## Additional Notes + +Any additional information that reviewers should know. diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..61316d7 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,90 @@ +name: CI + +on: + push: + branches: [main, develop] + pull_request: + branches: [main, develop] + +jobs: + test: + runs-on: ubuntu-latest + + strategy: + matrix: + node-version: [14.x, 16.x, 18.x, 20.x] + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Setup Node.js ${{ matrix.node-version }} + uses: actions/setup-node@v4 + with: + node-version: ${{ matrix.node-version }} + cache: 'npm' + + - name: Install dependencies + run: npm ci + + - name: Run linting + run: npx eslint mcp-sqlite-server.js + + - name: Run tests + run: npm test + + - name: Run tests with coverage + run: npm run test:coverage + + - name: Upload coverage to Codecov + uses: codecov/codecov-action@v3 + with: + file: ./coverage/lcov.info + flags: unittests + name: codecov-umbrella + fail_ci_if_error: false + + security: + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '18.x' + cache: 'npm' + + - name: Install dependencies + run: npm ci + + - name: Run security audit + run: npm audit --audit-level=high + + - name: Check for outdated dependencies + run: npm outdated || true + + build: + runs-on: ubuntu-latest + needs: [test, security] + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '18.x' + cache: 'npm' + + - name: Install dependencies + run: npm ci + + - name: Verify build + run: node -c mcp-sqlite-server.js + + - name: Test MCP server startup + run: 'timeout 10s node mcp-sqlite-server.js :memory: || true' diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..c68eddc --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,44 @@ +name: Release + +on: + push: + tags: + - 'v*' + +jobs: + release: + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '18.x' + registry-url: 'https://registry.npmjs.org' + cache: 'npm' + + - name: Install dependencies + run: npm ci + + - name: Run tests + run: npm test + + - name: Create Release + uses: actions/create-release@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + tag_name: ${{ github.ref }} + release_name: Release ${{ github.ref }} + draft: false + prerelease: false + + - name: Publish to npm + run: npm publish + env: + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} diff --git a/.gitignore b/.gitignore index 25e0ad5..37752b9 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,135 @@ -.git -node_modules/ -.cursor/ -test.db \ No newline at end of file +# Dependencies +node_modules/ +npm-debug.log* +yarn-debug.log* +yarn-error.log* + +# Runtime data +pids +*.pid +*.seed +*.pid.lock + +# Coverage directory used by tools like istanbul +coverage/ +*.lcov + +# nyc test coverage +.nyc_output + +# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files) +.grunt + +# Bower dependency directory (https://bower.io/) +bower_components + +# node-waf configuration +.lock-wscript + +# Compiled binary addons (https://nodejs.org/api/addons.html) +build/Release + +# Dependency directories +jspm_packages/ + +# TypeScript v1 declaration files +typings/ + +# TypeScript cache +*.tsbuildinfo + +# Optional npm cache directory +.npm + +# Optional eslint cache +.eslintcache + +# Microbundle cache +.rpt2_cache/ +.rts2_cache_cjs/ +.rts2_cache_es/ +.rts2_cache_umd/ + +# Optional REPL history +.node_repl_history + +# Output of 'npm pack' +*.tgz + +# Yarn Integrity file +.yarn-integrity + +# dotenv environment variables file +.env +.env.test + +# parcel-bundler cache (https://parceljs.org/) +.cache +.parcel-cache + +# Next.js build output +.next + +# Nuxt.js build / generate output +.nuxt +dist + +# Gatsby files +.cache/ +public + +# Storybook build outputs +.out +.storybook-out + +# Temporary folders +tmp/ +temp/ + +# Logs +logs +*.log + +# Runtime data +pids +*.pid +*.seed +*.pid.lock + +# Directory for instrumented libs generated by jscoverage/JSCover +lib-cov + +# Coverage directory used by tools like istanbul +coverage + +# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files) +.grunt + +# Compiled binary addons (http://nodejs.org/api/addons.html) +build/Release + +# Users Environment Variables +.lock-wscript + +# IDEs and editors +.vscode/ +.idea/ +*.swp +*.swo +*~ + +# OS generated files +.DS_Store +.DS_Store? +._* +.Spotlight-V100 +.Trashes +ehthumbs.db +Thumbs.db + +# Test databases +*.test.db +*.test.sqlite +test.db +test.sqlite +*.db diff --git a/.husky/pre-commit b/.husky/pre-commit new file mode 100755 index 0000000..d24fdfc --- /dev/null +++ b/.husky/pre-commit @@ -0,0 +1,4 @@ +#!/usr/bin/env sh +. "$(dirname -- "$0")/_/husky.sh" + +npx lint-staged diff --git a/.prettierignore b/.prettierignore new file mode 100644 index 0000000..83239b2 --- /dev/null +++ b/.prettierignore @@ -0,0 +1,5 @@ +node_modules/ +coverage/ +.git/ +*.min.js +package-lock.json diff --git a/.prettierrc b/.prettierrc new file mode 100644 index 0000000..4d1c1dd --- /dev/null +++ b/.prettierrc @@ -0,0 +1,9 @@ +{ + "semi": true, + "singleQuote": true, + "tabWidth": 4, + "trailingComma": "es5", + "printWidth": 100, + "bracketSpacing": true, + "arrowParens": "avoid" +} diff --git a/CHANGELOG.md b/CHANGELOG.md index 6f9287f..bf9594d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,28 +1,54 @@ -# Changelog - -All notable changes to the MCP SQLite Server will be documented in this file. - -## [1.0.7] - 2025-06-02 -### šŸ“¦ Updated -- Added a "description" parameter to each tool definitions for better Agent selection - -### šŸ› Fixed -- Resolved a know validation issue with VS Code that requires stricter JSON schema validation - -## [1.0.0] - 2025-04-05 -### āœØ Added -- Initial release of MCP SQLite Server -- Complete set of CRUD operations: - - `create_record` - Insert data into tables - - `read_records` - Query records with filtering, limit and offset - - `update_records` - Modify existing records with conditions - - `delete_records` - Remove records matching conditions -- Database exploration tools: - - `list_tables` - List all tables in the database - - `get_table_schema` - Get column information for tables - - `db_info` - Get database file metadata -- Custom SQL query execution with the `query` tool -- Support for relative and absolute database paths -- Detailed error reporting for all operations -- Comprehensive JSON response formatting -- Full documentation in README.md \ No newline at end of file +# Changelog + +All notable changes to the MCP SQLite Server will be documented in this file. + +## [Unreleased] + +### āœØ Added + +- Project scaffolding and DX improvements + - Moved server entry to `src/mcp-sqlite-server.js` + - Added Jest test suite with coverage reports + - Added ESLint and Prettier configurations + - Added Husky and lint-staged pre-commit checks + - Added GitHub Issue/PR templates and workflows + +### šŸ“ Docs + +- Expanded `README.md` with setup, usage examples, and contribution guidelines +- Added `CONTRIBUTING.md` + +### šŸ“¦ Updated + +- Package scripts for linting, formatting, cleaning, and prepare hooks +- `package.json` entries (e.g., `files`, `bin`) to reflect new layout + +## [1.0.7] - 2025-06-02 + +### šŸ“¦ Updated + +- Added a "description" parameter to each tool definitions for better Agent selection + +### šŸ› Fixed + +- Resolved a know validation issue with VS Code that requires stricter JSON schema validation + +## [1.0.0] - 2025-04-05 + +### āœØ Added + +- Initial release of MCP SQLite Server +- Complete set of CRUD operations: + - `create_record` - Insert data into tables + - `read_records` - Query records with filtering, limit and offset + - `update_records` - Modify existing records with conditions + - `delete_records` - Remove records matching conditions +- Database exploration tools: + - `list_tables` - List all tables in the database + - `get_table_schema` - Get column information for tables + - `db_info` - Get database file metadata +- Custom SQL query execution with the `query` tool +- Support for relative and absolute database paths +- Detailed error reporting for all operations +- Comprehensive JSON response formatting +- Full documentation in README.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..aa9e2cc --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,246 @@ +# Contributing to MCP SQLite Server + +First off, thank you for considering contributing to MCP SQLite Server! It's people like you that make this project better for everyone. + +## šŸ¤ Code of Conduct + +By participating in this project, you are expected to uphold our Code of Conduct (see CODE_OF_CONDUCT.md). + +## šŸš€ How Can I Contribute? + +### Reporting Bugs + +Before creating bug reports, please check the existing issues to avoid duplicates. When you create a bug report, include as many details as possible: + +- **Use a clear and descriptive title** +- **Describe the exact steps to reproduce the problem** +- **Provide specific examples** (code snippets, commands, etc.) +- **Describe the behavior you observed** and what you expected +- **Include your environment details** (Node version, OS, etc.) + +**Bug Report Template:** + +```markdown +**Description:** +A clear description of the bug. + +**Steps to Reproduce:** + +1. Step one +2. Step two +3. See error + +**Expected Behavior:** +What you expected to happen. + +**Actual Behavior:** +What actually happened. + +**Environment:** + +- Node Version: +- OS: +- MCP SQLite Version: +``` + +### Suggesting Enhancements + +Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion: + +- **Use a clear and descriptive title** +- **Provide a detailed description** of the suggested enhancement +- **Explain why this enhancement would be useful** +- **List any similar features** in other projects if applicable + +### Pull Requests + +1. **Fork the repository** and create your branch from `main` +2. **Make your changes** following the coding standards +3. **Add tests** for any new functionality +4. **Ensure all tests pass** by running `npm test` +5. **Update documentation** if needed +6. **Write a clear commit message** following our commit conventions + +#### Pull Request Process + +1. Update the README.md with details of changes if applicable +2. Update the CHANGELOG.md following the existing format +3. The PR will be merged once you have the sign-off of a maintainer + +## šŸ’» Development Setup + +### Prerequisites + +- Node.js >= 14.0.0 +- npm or yarn + +### Setup Instructions + +```bash +# Clone your fork +git clone https://github.com/YOUR_USERNAME/mcp-sqlite.git +cd mcp-sqlite + +# Install dependencies +npm install + +# Run tests +npm test + +# Run tests with coverage +npm run test:coverage + +# Test with MCP Inspector +npm run test:mcp +``` + +## šŸ“ Coding Standards + +### Code Style + +This project uses ESLint for code quality. Please ensure your code follows the existing style: + +```bash +# Check for linting errors +npx eslint src/ + +# Auto-fix linting errors +npx eslint src/ --fix +``` + +**Key Style Guidelines:** + +- Use single quotes for strings +- Use 4 spaces for indentation +- Use semicolons +- Use meaningful variable and function names +- Add comments for complex logic + +### Commit Messages + +Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification: + +``` +(): + + + +