docs: improve README with clearer MCP configuration guidance

Author: devakone

README.md

@@ -3,7 +3,15 @@
 [![npm version](https://img.shields.io/npm/v/mysql-query-mcp-server.svg)](https://www.npmjs.com/package/mysql-query-mcp-server)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A Model Context Protocol (MCP) server that provides **read-only** MySQL database queries for AI assistants like Claude in Cursor IDE, Windsurf, or Claude Desktop. Execute queries, explore database structures, and investigate your data directly from your AI-powered tools.
+A Model Context Protocol (MCP) server that provides **read-only** MySQL database queries for AI assistants. Execute queries, explore database structures, and investigate your data directly from your AI-powered tools.
+
+## Supported AI Tools
+
+This MCP server works with any tool that supports the Model Context Protocol, including:
+
+- **Cursor IDE**: Set up in `.cursor/mcp.json`
+- **Anthropic Claude**: Use with a compatible MCP client
+- **Other MCP-compatible AI assistants**: Follow the tool's MCP configuration instructions
 
 ## Features & Limitations
 
@@ -37,9 +45,88 @@ npx mysql-query-mcp-server
 
 ## Setup Instructions
 
-### 1. Configure Your Database Connections
+### 1. Configure Your AI Tool to Use the MCP Server
+
+1. Create or edit your MCP configuration file (e.g., `.cursor/mcp.json` for Cursor IDE):
+
+```json
+{
+  "mysql": {
+    "name": "MySQL Query MCP",
+    "description": "MySQL read-only query access through MCP",
+    "type": "bin", 
+    "enabled": true,
+    "bin": "mysql-query-mcp"
+  }
+}
+```
+
+For more advanced configuration with environment variables embedded in the MCP config:
+
+```json
+{
+  "mysql": {
+    "command": "npx",
+    "args": ["mysql-query-mcp-server@latest"],
+    "env": {
+      "LOCAL_DB_HOST": "localhost",
+      "LOCAL_DB_USER": "root",
+      "LOCAL_DB_PASS": "<YOUR_LOCAL_DB_PASSWORD>",
+      "LOCAL_DB_NAME": "your_database",
+      "LOCAL_DB_PORT": "3306",
+      
+      "DEVELOPMENT_DB_HOST": "dev.example.com",
+      "DEVELOPMENT_DB_USER": "<DEV_USER>",
+      "DEVELOPMENT_DB_PASS": "<DEV_PASSWORD>",
+      "DEVELOPMENT_DB_NAME": "your_database",
+      "DEVELOPMENT_DB_PORT": "3306",
+      
+      "STAGING_DB_HOST": "staging.example.com",
+      "STAGING_DB_USER": "<STAGING_USER>",
+      "STAGING_DB_PASS": "<STAGING_PASSWORD>",
+      "STAGING_DB_NAME": "your_database",
+      "STAGING_DB_PORT": "3306",
+      
+      "PRODUCTION_DB_HOST": "prod.example.com",
+      "PRODUCTION_DB_USER": "<PRODUCTION_USER>",
+      "PRODUCTION_DB_PASS": "<PRODUCTION_PASSWORD>",
+      "PRODUCTION_DB_NAME": "your_database",
+      "PRODUCTION_DB_PORT": "3306",
+      
+      "DEBUG": "false",
+      "MCP_MYSQL_SSL": "true",
+      "MCP_MYSQL_REJECT_UNAUTHORIZED": "false"
+    }
+  }
+}
+```
+
+#### Choosing the Right Configuration Approach
+
+There are two ways to configure the MySQL MCP server:
+
+1. **Binary Configuration** (`type: "bin"`, `bin: "mysql-query-mcp"`)
+   - **When to use**: When you've installed the package globally (`npm install -g mysql-query-mcp-server`)
+   - **Pros**: Simpler configuration, cleaner MCP file
+   - **Cons**: Requires global installation, uses a separate `.env` file for database credentials
+
+2. **Command Configuration** (`command: "npx"`, `args: ["mysql-query-mcp-server@latest"]`)
+   - **When to use**: When you want to use the latest version without installing it globally
+   - **Pros**: No global installation required, all configuration in one file
+   - **Cons**: More complex configuration, credentials in MCP file (which may be preferred in some cases)
+
+Choose the approach that best fits your workflow. Both methods will work correctly with any AI assistant that supports MCP.
+
+**Important Configuration Notes:**
+- You must use the full environment names: LOCAL_, DEVELOPMENT_, STAGING_, PRODUCTION_
+- Abbreviations like DEV_ or PROD_ will not work
+- Global settings like DEBUG, MCP_MYSQL_SSL apply to all environments
+- At least one environment (typically "local") must be configured
+- You only need to configure the environments you plan to use
+
+### 2. Alternative: Using a .env File
 
-You can configure the MySQL Query MCP server using environment variables in a `.env` file:
+If you prefer to keep your database credentials in a separate file, you can use a `.env` file:
 
 ```env
 # Local Database
@@ -78,30 +165,12 @@ PRODUCTION_DB_SSL=true
 DEBUG=false
 ```
 
-**Important Notes**:
-- You must configure at least one environment (typically "local")
-- Environment names are fixed (local, development, staging, production)
-- Additional environments can be configured but must use these exact names
-- Only configure the environments you actually need
-
 You can copy the included `.env.example` file to get started:
 ```bash
 cp .env.example .env
 ```
 
-### 2. Configure Cursor to Use the MCP Server
-
-1. Create the `.cursor` directory in your home directory if it doesn't exist:
-```bash
-mkdir -p ~/.cursor
-```
-
-2. If you don't have an MCP configuration file yet, create one:
-```bash
-touch ~/.cursor/mcp.json
-```
-
-3. Add the MySQL Query MCP configuration to your `.cursor/mcp.json` file:
+When using a `.env` file, your MCP configuration can be simplified to:
 
 ```json
 {
@@ -115,8 +184,6 @@ touch ~/.cursor/mcp.json
 }
 ```
 
-This tells Cursor to use the `mysql-query-mcp` binary when accessing the MySQL Query MCP server.
-
 ## Configuration Options
 
 | Environment Variable | Description | Default |
@@ -128,6 +195,8 @@ This tells Cursor to use the `mysql-query-mcp` binary when accessing the MySQL Q
 | [ENV]_DB_NAME | Database name | - |
 | [ENV]_DB_PORT | Database port | 3306 |
 | [ENV]_DB_SSL | Enable SSL connection | false |
+| MCP_MYSQL_SSL | Enable SSL for all connections | false |
+| MCP_MYSQL_REJECT_UNAUTHORIZED | Verify SSL certificates | true |
 
 ## Integration with AI Assistants
 
@@ -175,56 +244,7 @@ Use the info tool to check the status of our production database.
 
 #### 3. environments
 
-List all configured database environments:
-
-```
-Please use the environments tool to show me all available database environments.
-```
-
-### MCP Configuration Example
-
-Here's an example of a proper configuration for your MCP server:
-
-```json
-"mysql": {
-  "command": "npx",
-  "args": ["mysql-query-mcp-server@latest"],
-  "env": {
-    "LOCAL_DB_HOST": "localhost",
-    "LOCAL_DB_USER": "root",
-    "LOCAL_DB_PASS": "<YOUR_LOCAL_DB_PASSWORD>",
-    "LOCAL_DB_NAME": "your_database",
-    "LOCAL_DB_PORT": "3306",
-    
-    "DEVELOPMENT_DB_HOST": "dev.example.com",
-    "DEVELOPMENT_DB_USER": "<DEV_USER>",
-    "DEVELOPMENT_DB_PASS": "<DEV_PASSWORD>",
-    "DEVELOPMENT_DB_NAME": "your_database",
-    "DEVELOPMENT_DB_PORT": "3306",
-    
-    "STAGING_DB_HOST": "staging.example.com",
-    "STAGING_DB_USER": "<STAGING_USER>",
-    "STAGING_DB_PASS": "<STAGING_PASSWORD>",
-    "STAGING_DB_NAME": "your_database",
-    "STAGING_DB_PORT": "3306",
-    
-    "PRODUCTION_DB_HOST": "prod.example.com",
-    "PRODUCTION_DB_USER": "<PRODUCTION_USER>",
-    "PRODUCTION_DB_PASS": "<PRODUCTION_PASSWORD>",
-    "PRODUCTION_DB_NAME": "your_database",
-    "PRODUCTION_DB_PORT": "3306",
-    
-    "DEBUG": "true",
-    "MCP_MYSQL_SSL": "true",
-    "MCP_MYSQL_REJECT_UNAUTHORIZED": "false"
-  }
-}
-```
-
-**Important Notes:**
-- You must use the full environment names: LOCAL_, DEVELOPMENT_, STAGING_, PRODUCTION_
-- Abbreviations like DEV_ or PROD_ will not work
-- Global settings like DEBUG, MCP_MYSQL_SSL apply to all environments
+List all configured environments from your `.env` file.
 
 ## Available Tools
 
@@ -254,10 +274,6 @@ Get detailed information about your database:
 - Process list
 - Available databases
 
-### 3. environments
-
-List all configured environments from your `.env` file.
-
 ## Security Considerations
 
 - ✅ Only read-only queries are allowed (SELECT, SHOW, DESCRIBE)
@@ -266,6 +282,15 @@ List all configured environments from your `.env` file.
 - ✅ Query timeouts prevent runaway operations
 - ⚠️ Keep your `.env` file secure and never commit it to source control
 
+### 3. environments
+
+List all configured environments available in your setup. This tool will show all environments that have been successfully configured, either through:
+- Environment variables in the MCP configuration
+- A `.env` file in the project directory
+- System environment variables
+
+This is helpful for verifying which database environments are properly configured and available for querying.
+
 ## Troubleshooting
 
 ### Connection Issues