Package Exports

@egarcia74/warp-sql-server-mcp
@egarcia74/warp-sql-server-mcp/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@egarcia74/warp-sql-server-mcp) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

SQL Server MCP - AI-Powered Database Integration

Connect AI assistants to your SQL Server databases with enterprise-grade security and performance.

🤖 AI-First Database Access: Enable GitHub Copilot, Warp AI, and other assistants to interact with your SQL Server databases through natural language queries, with comprehensive security controls and production-ready reliability.

🚀 Quick Start - Choose Your AI Assistant

New to this project? Get up and running in under 5 minutes!

🤖 GitHub Copilot in VS Code (⭐ Most Popular)

Perfect for developers who want AI-powered SQL assistance directly in their IDE.

→ 5-Minute VS Code Setup Guide

✅ GitHub Copilot can query your databases directly
✅ Context-aware suggestions based on your actual schema
✅ Natural language to SQL query generation
✅ Real-time insights while coding

💬 Warp Terminal

Ideal for terminal-based workflows and command-line database interactions.

→ 5-Minute Warp Setup Guide

✅ AI-powered terminal with SQL Server integration
✅ Natural language database queries
✅ Fast iteration for analysis and debugging
✅ Cross-platform terminal experience

🔧 Advanced Integration

Complete VS Code Integration Guide → - Advanced workflows and configuration

Using another AI assistant? This MCP server works with any MCP-compatible system.

✨ What You Get

🤖 Natural language to SQL - Ask questions, get queries
🔒 Enterprise security - Three-tier safety system with secure defaults
📊 Performance insights - Query optimization and bottleneck detection
☁️ Cloud-ready - AWS/Azure secret management
🚀 Streaming support - Memory-efficient handling of large datasets
📈 16 Database Tools - Complete database operations through AI

🔒 Security Levels (Quick Reference)

Security Level	Environment Variable	Default	Impact
🔒 Read-Only Mode	`SQL_SERVER_READ_ONLY`	`true`	Only SELECT queries allowed
⚠️ Destructive Operations	`SQL_SERVER_ALLOW_DESTRUCTIVE_OPERATIONS`	`false`	Controls INSERT/UPDATE/DELETE
🚨 Schema Changes	`SQL_SERVER_ALLOW_SCHEMA_CHANGES`	`false`	Controls CREATE/DROP/ALTER

🔒 Maximum Security (Default - Production Recommended):

SQL_SERVER_READ_ONLY=true                      # Only SELECT allowed
SQL_SERVER_ALLOW_DESTRUCTIVE_OPERATIONS=false  # No data modifications
SQL_SERVER_ALLOW_SCHEMA_CHANGES=false         # No schema changes

📋 Essential Environment Variables

📖 Complete Reference: See docs/ENV-VARS.md for comprehensive documentation of all environment variables, defaults, and context-aware behavior.

Variable	Required	Default	Description
`SQL_SERVER_HOST`	Yes	`localhost`	SQL Server hostname
`SQL_SERVER_PORT`	Yes	`1433`	SQL Server port
`SQL_SERVER_DATABASE`	Yes	`master`	Initial database
`SQL_SERVER_USER`	For SQL Auth	-	Database username
`SQL_SERVER_PASSWORD`	For SQL Auth	-	Database password
`SQL_SERVER_ENCRYPT`	No	`true`	Enable SSL/TLS
`SQL_SERVER_TRUST_CERT`	No	context-aware	Trust server certificate

💡 Authentication: For Windows Authentication, leave SQL_SERVER_USER and SQL_SERVER_PASSWORD empty. 💡 SSL Certificates: SQL_SERVER_TRUST_CERT automatically adapts to your environment (trusts in development, requires valid certificates in production).

🛠️ Installation & Configuration

Note: As of v1.7.11 the package is published under the scoped name @egarcia74/warp-sql-server-mcp. The previous unscoped package remains temporarily and will be deprecated.

⭐ Recommended: Global npm Installation

# Install globally via npm (easiest method)
npm install -g @egarcia74/warp-sql-server-mcp

# Initialize configuration
warp-sql-server-mcp init

# Edit config file with your SQL Server details
# Config file location: ~/.warp-sql-server-mcp.json

Benefits:

✅ No manual path configuration
✅ Secure credential storage with file permissions (600)
✅ Easy configuration updates without touching AI assistant settings
✅ Password masking and validation

Alternative: Manual Installation

# Clone and install manually
git clone https://github.com/egarcia74/warp-sql-server-mcp.git
cd warp-sql-server-mcp
npm install

🎯 Use Cases

🔍 Database Analysis & Exploration

Schema Discovery: Reverse engineer legacy databases without documentation
Data Quality Assessment: Spot-check data integrity across tables
New Team Onboarding: Rapidly explore unfamiliar database schemas

📊 Business Intelligence & Reporting

Ad-hoc Analysis: Quick business questions through natural language
Data Export: Export filtered datasets to CSV for analysis
Revenue Analysis: AI-powered business insights

🛠️ Development & DevOps

Query Performance Tuning: Execution plan analysis and optimization
API Development: Quickly test database queries during development
Database Troubleshooting: Debug slow queries and identify bottlenecks

🚀 AI-Powered Operations

Natural Language to SQL: Ask questions like "Show me customers who haven't placed orders"
Query Optimization: "Why is this query running slowly?"
Automated Insights: Generate business reports through conversational queries

📚 Complete Documentation

📋 Complete Documentation Index - Navigate all documentation in one place

User Guides

Environment Variables Reference - Complete environment variables documentation
Security Guide - Comprehensive security configuration and threat model
Security Threat Analysis Process - Workflows for reviewing and responding to security alerts
Architecture Guide - Technical deep-dive and system design
All MCP Tools - Complete API reference (16 tools)

Setup Guides

VS Code Integration Guide - Advanced workflows and configuration
Azure Key Vault Guide - Cloud secret management setup
AWS Secrets Manager Guide - Enterprise credential management

Developer Resources

Software Engineering Manifesto - Philosophy and engineering practices
Quality No-Compromise Case Study - Real-world analysis of zero-tolerance quality standards
Testing Guide - Comprehensive test documentation (535+ tests)
Contributing Guide - Development workflow and standards
Git Commit Checklist - Pre-commit quality gates and guidelines
Git Push Checklist - Pre-push validation and deployment guidelines
Git Release Checklist - Step-by-step release guide (automation + npm)

🧪 Production Validation

✅ PRODUCTION-VALIDATED: This MCP server has been fully tested through:

618+ Comprehensive Tests: All MCP tools, security boundaries, error scenarios (392 unit + 40 manual integration + 20 protocol tests)
40 Manual Integration Tests: Live database validation across all security phases
20 Protocol Tests: End-to-end MCP communication validation
100% Success Rate: All security phases validated in production scenarios

🐳 Quick Testing with Docker (Recommended for Development)

# One-command testing with automated SQL Server container
npm run test:integration

# This will:
# 1. 🐳 Start SQL Server 2022 container
# 2. ⏱️ Wait for database initialization (2-3 minutes)
# 3. 🧪 Run all integration tests
# 4. 🔄 Clean up and stop container

Benefits: ✨ Zero configuration, 🛡️ Complete isolation, ⚡ Fast setup, 📋 Consistent environment

Complete Docker Testing Guide →

🔧 Manual Setup Testing (Production Validation)

Security Phases Tested:

Phase 1 (Read-Only): Maximum security - 20/20 tests ✅
Phase 2 (DML Operations): Selective permissions - 10/10 tests ✅
Phase 3 (DDL Operations): Full development mode - 10/10 tests ✅

# Quick Start - Get comprehensive help
npm run help               # Show all commands with detailed descriptions

# Run tests locally
npm test                   # All automated unit + integration tests
npm run test:coverage      # Coverage report with detailed metrics
npm run test:integration   # 🚀 Complete integration test suite with Docker
npm run test:integration:ci  # For CI environments with external database
npm run test:integration:performance  # ⭐ Fast performance validation (~2s)

# View logs and monitor activity
npm run logs               # Show recent server logs
npm run logs:tail          # Follow logs in real-time
npm run logs:audit         # Show security audit logs

🔧 Usage Examples

Once configured, you can use natural language with your AI assistant:

VS Code + GitHub Copilot

@sql-server List all databases
@sql-server Show me tables in the AdventureWorks database
@sql-server Generate a query to find the top 10 customers by sales
@sql-server Analyze the performance of this query: SELECT * FROM Orders WHERE OrderDate > '2023-01-01'

Warp Terminal

Please list all databases on the SQL Server
Execute this SQL query: SELECT TOP 10 * FROM Users ORDER BY CreatedDate DESC
Can you describe the structure of the Orders table?
Show me 50 rows from the Products table where Price > 100

🚨 Troubleshooting

Common Issues

Connection Problems:

Verify SQL Server is running on the specified port: telnet localhost 1433
Check firewall settings on both client and server
Enable TCP/IP protocol in SQL Server Configuration Manager

Authentication Issues:

For SQL Server Auth: Verify SQL_SERVER_USER and SQL_SERVER_PASSWORD
For Windows Auth: Leave user/password empty, optionally set SQL_SERVER_DOMAIN
Ensure the connecting user has appropriate database permissions

Configuration Issues:

Set SQL_SERVER_ENCRYPT=false for local development
MCP servers require explicit environment variables (.env files are not loaded automatically)
Check MCP server logs: npm run logs or npm run logs:tail for real-time monitoring
View audit logs for security-related issues: npm run logs:audit

Platform-Specific

Windows:

Enable TCP/IP in SQL Server Configuration Manager
Start SQL Server Browser service for named instances
Windows Authentication works seamlessly with domain accounts

macOS/Linux:

Remote SQL Server connections often require SQL Server Authentication
May need SQL_SERVER_ENCRYPT=true for remote connections
Test connectivity: nc -zv localhost 1433 or nmap -p 1433 localhost

🤝 Contributing

This project demonstrates enterprise-grade software engineering practices. We welcome contributions that maintain our high standards:

Fork the repository and create a feature branch
Follow TDD practices - write tests first!
Maintain code quality - all commits trigger automated quality checks
Add comprehensive tests for new functionality
Update documentation as needed
Submit a pull request with detailed description

Development Commands:

# Get comprehensive help for all available commands
npm run help               # Show organized command reference with descriptions

# Core development
npm run dev                # Development mode with auto-restart
npm test                   # Run all tests
npm run lint:fix          # Fix linting issues
npm run format            # Format code
npm run ci                 # Full CI pipeline locally

# Log viewing and monitoring
npm run logs               # Show recent server logs
npm run logs:tail          # Follow server logs in real-time
npm run logs:audit         # Show security audit logs
npm run logs:tail:audit    # Follow audit logs in real-time

# System maintenance and cleanup
npm run cleanup            # Clean up leftover test processes
npm run cleanup:processes  # Same as cleanup (alias)

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🌟 About This Project

While this appears to be an MCP server for SQL Server integration, it's fundamentally a comprehensive framework demonstrating enterprise-grade software development practices. Every component, pattern, and principle here showcases rigorous engineering standards that can be applied to any production system.

Key Engineering Highlights:

🔬 618+ Comprehensive Tests covering all functionality and edge cases
🛡️ Multi-layered Security with defense-in-depth architecture
📊 Production Observability with structured logging and performance monitoring
⚡ Enterprise Reliability featuring connection pooling and graceful error handling
🏛️ Clean Architecture with dependency inversion and modular design
📚 Living Documentation that auto-syncs with code changes

→ Read the Complete Engineering Philosophy

@egarcia74/warp-sql-server-mcp