{"id":39699923,"url":"https://github.com/guyinwonder168/database-mcp-server","last_synced_at":"2026-04-02T18:08:12.844Z","repository":{"id":311398717,"uuid":"1043417959","full_name":"guyinwonder168/database-mcp-server","owner":"guyinwonder168","description":"Production-ready MCP provider for SQL databases with unified AI agent interface, supporting MySQL, MariaDB, PostgreSQL, and SQLite with secure credential management and comprehensive query tools.","archived":false,"fork":false,"pushed_at":"2026-03-23T12:07:19.000Z","size":18387,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-24T02:56:20.104Z","etag":null,"topics":["ai-agents","ai-tools","artificial-intelligence","claudecode","codex","database","go","mariadb","mcp","mcp-server","model-context-protocol","mysql","opencode","postgresql","sql","sqlite"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/guyinwonder168.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-08-23T20:08:11.000Z","updated_at":"2026-03-23T06:27:32.000Z","dependencies_parsed_at":"2025-08-24T14:04:35.390Z","dependency_job_id":"9f180851-2e61-4eec-af92-2f04f248a08d","html_url":"https://github.com/guyinwonder168/database-mcp-server","commit_stats":null,"previous_names":["guyinwonder168/database-mcp-server"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/guyinwonder168/database-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guyinwonder168%2Fdatabase-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guyinwonder168%2Fdatabase-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guyinwonder168%2Fdatabase-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guyinwonder168%2Fdatabase-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/guyinwonder168","download_url":"https://codeload.github.com/guyinwonder168/database-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guyinwonder168%2Fdatabase-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31312744,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","ai-tools","artificial-intelligence","claudecode","codex","database","go","mariadb","mcp","mcp-server","model-context-protocol","mysql","opencode","postgresql","sql","sqlite"],"created_at":"2026-01-18T10:22:59.100Z","updated_at":"2026-04-02T18:08:12.835Z","avatar_url":"https://github.com/guyinwonder168.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Database MCP Server\n\n[![Go](https://img.shields.io/badge/Go-1.26.0%2B-00ADD8?logo=Go\u0026logoColor=white)](https://go.dev)\n[![License](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)\n[![Version](https://img.shields.io/badge/Version-v1.4.0-blue.svg)](https://github.com/guyinwonder168/database-mcp-server/releases/tag/v1.4.0)\n[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=guyinwonder168_database-mcp-server\u0026metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=guyinwonder168_database-mcp-server)\n[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=guyinwonder168_database-mcp-server\u0026metric=security_rating)](https://sonarcloud.io/summary/new_code?id=guyinwonder168_database-mcp-server)\n[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=guyinwonder168_database-mcp-server\u0026metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=guyinwonder168_database-mcp-server)\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=guyinwonder168_database-mcp-server\u0026metric=alert_status)](https://sonarcloud.io/summary/new_code?id=guyinwonder168_database-mcp-server)\n\nA production-ready Model Context Protocol (MCP) provider for SQL databases, built using various vibe coding tools. Supports MySQL, MariaDB, PostgreSQL, and SQLite. Features robust connection pooling, secure AES-GCM credential storage, structured JSON logging, comprehensive schema introspection, and a full suite of 21 MCP tools. Built and tested with Go 1.26.0.\n\n## 🚀 Quick Start\n\n```bash\n# Clone the repository\ngit clone https://github.com/guyinwonder168/database-mcp-server.git\ncd database-mcp-server\n\n# Build the server\ngo build -o mcp-server ./cmd/server/main.go\n\n# Run the server\n./mcp-server\n```\n\n## 📦 Container Package (GHCR)\n\n```bash\n# Pull the release image\ndocker pull ghcr.io/guyinwonder168/database-mcp-server:v1.4.0\n\n# Run with stdio transport\ndocker run --rm -i ghcr.io/guyinwonder168/database-mcp-server:v1.4.0\n```\n\n```bash\n# Persist config.yaml and logs on host\nmkdir -p ./.mcp-data\ndocker run --rm -i \\\n  -v \"$(pwd)/.mcp-data:/app\" \\\n  ghcr.io/guyinwonder168/database-mcp-server:v1.4.0\n```\n\nPackage registry: `https://github.com/guyinwonder168/database-mcp-server/pkgs/container/database-mcp-server`\n\n## 📋 Features\n\n- 🔧 **Interactive Setup** - Auto-creates `config.yaml` if missing; all configuration is managed via MCP actions\n- 👥 **Profile Management** - Create, update, delete, or clone database profiles via MCP\n- ⚡ **SQL Execution** - Run arbitrary SQL queries (with read-only enforcement)\n- 🔍 **Schema Introspection** - List tables/views with schema info, describe table schemas, list databases, discover joins, and browse schemas\n- 🗂️ **Multi-Schema Support** - Work with tables in any PostgreSQL schema with automatic detection and schema-qualified queries\n- 📊 **Sample Data Fetching** - Fetch sample rows to infer data formats and value ranges\n- 🔗 **Automated Join Discovery** - Suggest JOIN SQL for building complex queries\n- 🚦 **Query Optimization** - EXPLAIN-based analysis with findings and performance estimates\n- 🛡️ **Query Validation** - Syntax, logic, and security checks before execution\n- 🤖 **Smart Query Builder** - Generate SQL queries programmatically (integrated into analyze-schema AIQuerySuggestions)\n- 🔒 **Read-only Profiles** - Prevent write operations on selected profiles\n- 🔐 **Secure Credentials** - Passwords are encrypted at rest using AES-GCM (256-bit)\n- 🏊 **Connection Pooling** - Efficient, configurable pooling with max pool size\n- 📝 **Structured Logging \u0026 Error Handling** - All actions and errors are logged as structured JSON; actionable error responses\n- 🛠️ **Tool Discovery** - `list-tools` MCP action returns a machine-readable list of all available tools/actions\n- 🔌 **Official MCP Protocol** - Communication via stdio (not HTTP server; JSON is exchanged over stdio via official Go MCP SDK)\n- 📈 **Business Intelligence** - Discover KPIs, trends, anomalies, and distribution patterns via `discover-insights`\n- 🧭 **Data Lineage** - Analyze upstream/downstream dependencies via `analyze-data-lineage`\n- 🧱 **Schema Evolution Tracking** - Track schema snapshots, detect drift, and generate migration scripts via `track-schema-changes`\n- 🧬 **Advanced Data Profiling** - Optional statistical/pattern profiling for `analyze-schema` via `profiling: true`\n- 🌐 **Multi-Database Federation** - Execute federated subqueries with cross-profile joins via `federated-query`\n\n## 🛠️ Supported MCP Tools\n\n| Tool | Description |\n|-------|-------------|\n| `configure-profile` | Create, update, delete, or clone database connection profiles |\n| `list-profiles` | List all configured database profiles |\n| `execute-sql` | Execute arbitrary SQL queries with read-only enforcement |\n| `list-tables` | List tables with schema information in selected database |\n| `describe-table` | Describe comprehensive table schema with metadata (supports schema parameter) |\n| `list-databases` | List accessible databases for profile |\n| `list-schemas` | List all accessible database schemas with default schema |\n| `get-search-path` | Get current search_path and effective schema (read-only diagnostic) |\n| `smart-query-builder` | Generate SQL from high-level intent |\n| `optimize-query` | Run EXPLAIN, return plan, findings, and performance estimate |\n| `validate-query` | Validate SQL syntax and flag risky patterns before execution |\n| `analyze-data-lineage` | Trace FK-based upstream/downstream table dependencies |\n| `discover-joins` | Discover foreign key relationships and suggest JOINs |\n| `sample-data` | Fetch sample rows to infer data formats |\n| `discover-insights` | Discover KPIs, trends, anomalies, and distribution patterns in database tables |\n| `track-schema-changes` | Track schema snapshots/history, generate migrations, and detect schema drift |\n| `federated-query` | Execute read-only cross-profile subqueries with optional JOINs, aggregation, and partial-failure metadata |\n| `list-tools` | List all available MCP tools and descriptions |\n| `get-tool-help` | Return on-demand summary, examples, and common errors for a tool |\n| `analyze-schema` | Comprehensive schema analysis with AI query suggestions and optional advanced profiling (`profiling`) |\n| `mcp-info` | Show provider version and author |\n\n## 🤖 Model Compatibility\n\n- Default schema mode is `compact` for tool-first and strict declaration-budget clients.\n- Optional `standard` mode keeps verbose tool descriptions for human-readable metadata.\n- All 21 MCP tools are always registered.\n- **Gemini Compatibility**: Schemas are automatically sanitized to comply with Google Gemini's OpenAPI 3.0 subset requirements (single `type` values, no `additionalProperties: false`, proper `items` schemas).\n- Use `get-tool-help` for per-tool examples and troubleshooting without inflating startup metadata.\n\n`config.yaml`:\n\n```yaml\nschema_mode: compact # compact|standard\n```\n\nRecommended startup configuration for strict tool-loading clients:\n\n```yaml\nschema_mode: compact\n```\n\nHelper tool request example:\n\n```json\n{\n  \"tool_name\": \"execute-sql\",\n  \"topic\": \"all\"\n}\n```\n\n## 📖 Documentation\n\n### Core Documentation\n- 📋 [**API Documentation**](docs/api-documentation.md) - Detailed API specifications and examples\n- 📊 [**Implementation Status**](docs/implementation-status.md) - Current implementation tracking\n- 🏗️ [**Technical Specifications**](docs/technical-specifications.md) - Architecture and design details\n- 📝 [**PRD Analysis**](docs/prd.md) - Product requirements analysis with AI perspective\n- 🔍 [**Schema Introspection Queries**](docs/schema-introspection-queries.md) - Database-specific queries\n- 🧪 [**Test Enhanced Schema**](docs/test-enhanced-schema.md) - Test schema documentation\n- 🗺️ [**Enhancement Roadmap**](docs/roadmap.md) - Strategic development planning\n\n### Memory Bank Documentation\nThe project includes a comprehensive memory bank system for AI assistants, located in `.kilocode/rules/memory-bank/`:\n\n- 🏗️ [**Architecture**](.kilocode/rules/memory-bank/architecture.md) - System architecture and component relationships\n- 📋 [**Brief**](.kilocode/rules/memory-bank/brief.md) - Project overview and requirements\n- 📊 [**Context**](.kilocode/rules/memory-bank/context.md) - Current state and recent changes\n- 🎯 [**Product**](.kilocode/rules/memory-bank/product.md) - Problem statement and solution overview\n- 💻 [**Tech**](.kilocode/rules/memory-bank/tech.md) - Technology stack and development setup\n\n### Project Planning\n- 🗺️ [**Roadmap**](docs/roadmap.md) - Consolidated enhancement plan\n- 📊 [**Vertical Slices (History)**](docs/history/vertical-slices.md) - Phase-by-phase development breakdown\n- 🔍 [**Architecture Validation (History)**](docs/history/architecture-validation.md) - Technical compatibility analysis\n- 🐛 [**MCP Tool Detection Fix (History)**](docs/history/mcp-tool-detection-fix.md) - Critical bug fix documentation\n\n### Version History\n- 📋 [**CHANGELOG**](CHANGELOG.md) - Detailed release notes and version history\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [**Contributing Guidelines**](CONTRIBUTING.md) for development setup and workflow.\n\n## 📄 License\n\nThis project is licensed under the [**MIT License**](LICENSE).\n\n## 🔐 Security\n\nFor security policies and vulnerability reporting, please see our [**Security Policy**](SECURITY.md).\n\n## 📜 Code of Conduct\n\nPlease read our [**Code of Conduct**](CODE_OF_CONDUCT.md) for community guidelines.\n\n## 🧪 Testing\n\n```bash\n# Run all tests\ngo test ./...\n\n# Run tests with coverage\ngo test -cover ./...\n\n# Run specific test suites\ngo test ./internal/mcp -run \"TestDescribe\" -v  # MySQL/PostgreSQL descriptor tests\ngo test ./internal/mcp -run \"TestLoadLineage\" -v  # Lineage edge tests\n```\n\n### Testing Strategy\n\n- **MySQL/PostgreSQL**: Uses [go-sqlmock](https://github.com/DATA-DOG/go-sqlmock) for database-specific query testing without requiring real database connections\n- **SQLite**: Uses real in-memory databases for actual SQLite functionality testing\n- **Live Integration**: Optional live database tests via `DB_MCP_IT_*` environment variables\n\n## 📊 Project Status\n\n- **Version:** v1.4.0\n- **Built with:** Various vibe coding tools\n- **Status:** Production Ready ✅\n- All 21 MCP tools are fully implemented and OpenAPI-aligned.\n- Enhanced schema introspection and sample data features.\n- Optional advanced profiling in `analyze-schema` for column-level statistics, pattern detection, and quality scoring.\n- AES-GCM encryption, connection pooling, and structured error handling are enforced.\n- Comprehensive unit and integration tests included.\n- Ready for production use.\n\n- **Business Intelligence Discovery**: Added `discover-insights` tool for automatic KPI, trend, anomaly, and distribution analysis\n\n---\n\n## Enhancement Planning\n\n**Current Development Status**: The Database MCP Server is production-ready with a comprehensive enhancement roadmap in progress.\n\n**Implementation Phases**:\n- **Phase 1** (Completed): Query optimization, validation, and enhanced NLP\n- **Phase 2** (Completed): Data lineage and business intelligence\n- **Phase 3** (Completed): Schema evolution, advanced profiling, and multi-database federation\n- **Phase 4** (Planned): Cross-database data migration with async jobs, schema translation, and resume capability\n\n**Current Progress**:\n- `track-schema-changes` is implemented with snapshot tracking, history, migration generation, and drift detection.\n- Advanced profiling for `analyze-schema` is implemented with optional `profiling` parameter and backward-compatible response shape.\n- `federated-query` is implemented with parser/planner/join/executor/handler modules and dedicated test coverage.\n- `configure-profile` enhanced with `delete` and `clone` actions (v1.3.0).\n\n**Planning Documents**:\n- [Enhancement Roadmap](docs/roadmap.md) - Strategic overview\n- [Data Migration Design](docs/data-migration-design.md) - Phase 4 implementation plan\n- [Project Plan (History)](docs/history/project-plan-roadmap.md) - Comprehensive implementation strategy\n- [Vertical Slices (History)](docs/history/vertical-slices.md) - Detailed phase breakdowns\n\n## 🔍 Multi-Schema Support (PostgreSQL)\n\nThis server provides comprehensive multi-schema support for PostgreSQL databases:\n\n### Schema-Aware Tools\n\n| Tool | Schema Support |\n|------|---------------|\n| `list-tables` | Returns schema information for all tables |\n| `describe-table` | Optional `schema` parameter with auto-detection |\n| `sample-data` | Optional `schema` parameter |\n| `analyze-schema` | Optional `schema` parameter |\n| `list-schemas` | Discover all accessible schemas |\n| `get-search-path` | Diagnostic tool for current schema context |\n\n### Connection Pooling Note\n\nThis server uses connection pooling per database profile. Due to this architecture:\n\n- **`set-search-path` is intentionally NOT implemented** - Session-level `search_path` changes would contaminate other clients using the same pooled connection\n- **Use explicit schema qualification** via the `schema` parameter on relevant tools\n- **Auto-detection** falls back gracefully: `current_schema()` → first accessible schema → `'public'`\n\n### Example Usage\n\n```json\n// Describe table in specific schema\n{\n  \"profile_name\": \"mydb\",\n  \"database_name\": \"mydb\",\n  \"table_name\": \"users\",\n  \"schema\": \"bitnami_redmine\"\n}\n\n// List all schemas\n{\n  \"profile_name\": \"mydb\",\n  \"database_name\": \"mydb\"\n}\n```\n\n**Ready for immediate enhancement development while maintaining production stability.**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguyinwonder168%2Fdatabase-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fguyinwonder168%2Fdatabase-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguyinwonder168%2Fdatabase-mcp-server/lists"}