@jessejoris/mcp-mysql-via-api 1.0.0

package/PRD.md

@@ -0,0 +1,364 @@
+# Product Requirement Document (PRD)
+# MySQL Model Context Protocol (MCP) Server via API (`mcp_mysql_via_api`)
+
+**Document Version:** 1.1.0  
+**Status:** Approved & Verified  
+**Author:** Antigravity Engineering  
+**Target Systems:** Hermes AI, OpenClaw, Claude Desktop, Cursor, Windsurf, Cline, Codex, CLI & Local IDEs  
+
+---
+
+## 1. Executive Summary & Problem Statement
+
+### 1.1 Context & Background
+The legacy `mcp_mysql` solution establishes direct TCP socket connections (via the `mysql2` driver on port 3306) to MySQL database instances. While effective for local or flat networks, this architectural pattern encounters severe limitations in real-world enterprise, cloud, and distributed environments:
+- **Firewall & Security Boundaries:** Production databases rarely expose port 3306 directly to external networks or AI developer workstations.
+- **Microservices & Multi-Cloud Architecture:** Databases are shielded inside private VPCs / subnets behind API Gateways, ingress controllers, or dedicated internal REST services.
+- **Audit & Governance:** Direct SQL socket connections bypass application-level telemetry, token-based rate limiting, role-based access control (RBAC), and centralized API auditing.
+
+### 1.2 The Solution: `mcp_mysql_via_api`
+`mcp_mysql_via_api` decouples the AI Agent interface from the physical database wire protocol. Instead of direct database socket connections:
+1. The **AI Agent** communicates via standard **Model Context Protocol (MCP)** (`stdio` / stream transport) with the `mcp_mysql_via_api` client.
+2. The MCP client translates tool invocations into authenticated HTTP/REST requests against a remote **MySQL API Server Endpoint** hosted in the database's secure environment.
+3. The server exposes structured endpoints for every table, schema discovery, point lookups, execution of guarded queries, and metadata extraction.
+4. Strict access controls (including presets like `only-read`, `read-write`, `admin` and granular permissions) protect against unauthorized mutations.
+5. All tool outputs are **strictly valid JSON**—guaranteed 100% parseable with zero plaintext, HTML, or unstructured error strings.
+6. Multi-record operations feature **default pagination** with an explicit **bypass option** for AI agents requiring complete data extracts.
+
+---
+
+## 2. Core Personas & Target Agents
+
+| Persona / Agent | Typical Environment | Primary Needs & Constraints |
+|-----------------|---------------------|-----------------------------|
+| **Hermes AI** | Autonomous Agent / Sandbox | High-reliability JSON schema, determinism, zero non-JSON output, RAG context window optimization, self-describing metadata |
+| **OpenClaw** | Multi-agent Orchestrator | Strict token management via default pagination, schema RAG context, cross-table text search, permission guards |
+| **Cursor / Windsurf / Cline** | IDE Integration | Instant response times, tabular and record browsing, connection health checks, direct single-record access |
+| **Claude Desktop / Codex** | Desktop / CLI Agent | Stdio transport compliance, transparent error codes, ERD and relationship mapping |
+
+---
+
+## 3. Key Design Principles & Requirements
+
+### 3.1 Strict JSON Output Guarantee
+- **Mandate:** All outputs returned through the MCP tool interface MUST be strictly valid, well-formed JSON strings (`application/json`).
+- **Forbidden:** No raw markdown backticks, no emoji error prefixes (e.g., `❌ Error`), no unstructured text, and no HTML error pages (even on HTTP 404/500).
+- **Envelope Standard:**
+  ```json
+  // Success Response Envelope
+  {
+    "success": true,
+    "data": { ... },
+    "meta": {
+      "pagination": {
+        "page": 1,
+        "limit": 50,
+        "total": 120,
+        "totalPages": 3,
+        "hasMore": true
+      },
+      "timestamp": "2026-09-03T15:25:00.000Z"
+    }
+  }
+
+  // Error Response Envelope
+  {
+    "success": false,
+    "error": {
+      "code": "PERMISSION_DENIED",
+      "message": "Operation 'create_record' is blocked by active permission policy 'only-read'.",
+      "details": {
+        "requiredPermission": "create",
+        "activePermissions": ["list", "read", "utility"]
+      },
+      "timestamp": "2026-09-03T15:25:00.000Z"
+    }
+  }
+  ```
+
+### 3.2 Dual-Layer Permission System & Defense-in-Depth
+To satisfy safety requirements and prevent unauthorized schema alteration or data destruction:
+1. **Permission Presets:**
+   - `only-read` (aliases `readonly`, `read-only`, `only_read`, `read_only`, `view-only`): Allows `list`, `read`, `utility`. Strictly forbids `create`, `update`, `delete`, `execute`, `ddl`.
+   - `read-write` (alias `read_write`): Allows `list`, `read`, `create`, `update`, `utility`. Blocks `delete`, `execute`, `ddl`.
+   - `admin` (aliases `all`, `*`): Allows all operations (`list`, `read`, `create`, `update`, `delete`, `execute`, `ddl`, `utility`, `transaction`).
+   - `custom`: Explicit comma-separated permissions (e.g. `list,read,create`).
+2. **Granular Categories:**
+   - `list`: Database discovery, table listing, schema inspection, ERD generation, RAG context generation.
+   - `read`: Querying records, search data across tables, column statistics, point record lookups, running select queries.
+   - `create`: Single record insertion, bulk insert.
+   - `update`: Single record update, bulk update.
+   - `delete`: Single record deletion, bulk delete.
+   - `execute`: Custom SQL query execution via API.
+   - `ddl`: Schema alterations (`create_table`, `alter_table`, `drop_table`, `execute_ddl`).
+   - `utility`: Connection testing, metadata health checks, CSV exports.
+3. **Dual-Layer Defense Architecture:**
+   - **MCP Client Layer:** Pre-execution permission check; blocks requests locally before network calls if unauthorized.
+   - **API Server Layer:** HTTP endpoint authorization check via `API_PERMISSIONS` / `MCP_PERMISSIONS`; rejects unauthorized mutation verbs with HTTP 403 Forbidden envelopes.
+   - **SQL Keyword Inspection:** Dangerous keywords (`INTO OUTFILE`, `LOAD DATA`, `GRANT`, `REVOKE`) and covert DDL inside `execute_write_query` are intercepted and blocked before execution.
+
+### 3.3 Default Pagination & Explicit Bypass System
+To balance LLM context window safety with full data access:
+- **Default Behavior:**
+  - Multi-record operations (`read_records`, `run_select_query`, `search_data_across_tables`) paginate results by default.
+  - Default: `page = 1`, `limit = 50` (configurable via `DEFAULT_PAGE_SIZE`, default max page size 500).
+  - Metadata provides `total`, `page`, `limit`, `totalPages`, `hasMore`.
+- **Bypass Mode:**
+  - Agents can specify `bypass_pagination: true` (or `all: true` / `limit: 0`).
+  - When active, the server fetches the complete dataset without slicing.
+  - Safety guard: A safety ceiling (`MAX_BYPASS_LIMIT`, default 10,000 rows) prevents memory exhaustion (OOM), returning an explicit warning if the table exceeds the ceiling.
+
+---
+
+## 4. System Architecture & Components
+
+```
+┌────────────────────────────────────────────────────────┐
+│                   AI Agent (Host)                      │
+│       Hermes / OpenClaw / Cursor / Claude Code         │
+└──────────────────────────┬─────────────────────────────┘
+                           │ MCP Protocol (stdio / JSON-RPC 2.0)
+┌──────────────────────────▼─────────────────────────────┐
+│             mcp_mysql_via_api (MCP Client)             │
+│  ┌────────────────────┐      ┌──────────────────────┐  │
+│  │ Permission Engine  │      │ Strict JSON Engine   │  │
+│  │ (only-read, etc.)  │      │ (Guaranteed Parse)   │  │
+│  └────────────────────┘      └──────────────────────┘  │
+│  ┌────────────────────┐      ┌──────────────────────┐  │
+│  │ Pagination Handler │      │ Resilient API Client │  │
+│  │ (Default + Bypass) │      │ (Retries & Auth)     │  │
+│  └────────────────────┘      └──────────────────────┘  │
+└──────────────────────────┬─────────────────────────────┘
+                           │ Authenticated HTTP/REST (JSON)
+                           │ Bearer Token / API Key
+┌──────────────────────────▼─────────────────────────────┐
+│          Remote MySQL API Server (Target Host)         │
+│  ┌──────────────────────────────────────────────────┐  │
+│  │ REST Router (/api/tables, /api/schema, etc.)     │  │
+│  ├──────────────────────────────────────────────────┤  │
+│  │ Dual-Layer Auth & RBAC Middleware (HTTP 403)     │  │
+│  ├──────────────────────────────────────────────────┤  │
+│  │ MySQL Connection Pool & Query Sanitizer          │  │
+│  └──────────────────────────┬───────────────────────┘  │
+└─────────────────────────────┼──────────────────────────┘
+                              │ TCP (Internal Network)
+┌─────────────────────────────▼──────────────────────────┐
+│                   MySQL Database                       │
+└────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 5. Tool Catalog (31 Tools Specification)
+
+### 5.1 Database & Schema Discovery
+1. `list_databases`
+   - **Permission:** `list`
+   - **Description:** Lists all accessible databases on the remote MySQL server.
+   - **Input:** `{}`
+2. `list_tables`
+   - **Permission:** `list`
+   - **Description:** Lists all tables in the specified or default database.
+   - **Input:** `{ database?: string }`
+3. `read_table_schema`
+   - **Permission:** `list`
+   - **Description:** Inspects column definitions, data types, primary keys, foreign keys, and indexes for a specific table.
+   - **Input:** `{ table_name: string, database?: string }`
+4. `get_database_summary`
+   - **Permission:** `list`
+   - **Description:** High-level summary of database structure, table count, column details, and approximate row counts.
+   - **Input:** `{ database?: string, max_tables?: number, include_relationships?: boolean }`
+5. `get_schema_erd`
+   - **Permission:** `list`
+   - **Description:** Generates a visual Mermaid.js Entity-Relationship diagram representing the database foreign keys.
+   - **Input:** `{ database?: string }`
+6. `get_schema_rag_context` *(New AI-Optimized)*
+   - **Permission:** `list`
+   - **Description:** 🎯 AI-OPTIMIZED: Returns ultra-compact schema information designed specifically for LLM context windows (Hermes AI, OpenClaw, IDEs). Use keyword_filter for concept-focused schema discovery.
+   - **Input:** `{ database?: string, max_tables?: number, max_columns?: number, keyword_filter?: string }`
+7. `get_all_tables_relationships`
+   - **Permission:** `list`
+   - **Description:** Analyzes foreign key relationships across all tables.
+   - **Input:** `{ database?: string }`
+8. `search_schema`
+   - **Permission:** `list`
+   - **Description:** Searches for keywords across table names, column names, and comments.
+   - **Input:** `{ query: string, database?: string }`
+9. `find_tables_by_keyword`
+   - **Permission:** `list`
+   - **Description:** Fast ranked keyword search for tables matching specific entities (e.g. "users", "orders").
+   - **Input:** `{ keyword: string, database?: string, limit?: number }`
+10. `search_data_across_tables` *(New AI-Optimized)*
+    - **Permission:** `read`
+    - **Description:** 🔍 Guarded read-only keyword scan across text-like column values across tables. Discovers which table contains specific values or IDs when table structure is unknown.
+    - **Input:** `{ keyword: string, tables?: string[], database?: string, max_tables?: number, limit_per_table?: number }`
+
+### 5.2 CRUD & Data Operations
+11. `read_records`
+    - **Permission:** `read`
+    - **Description:** Retrieves records from any table with filtering, sorting, column selection, and pagination. Supports legacy operator aliases (`eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `like`, `in`, `is null`, `between`) and `conditions` alias.
+    - **Input:** `{ table_name: string, columns?: string[], filters?: any[], conditions?: any[], sorting?: object, pagination?: object, bypass_pagination?: boolean, all?: boolean, database?: string }`
+12. `read_record` *(New Direct Point Lookup)*
+    - **Permission:** `read`
+    - **Description:** Fetches a single record by primary key or ID from a table via API. Fast direct point lookup.
+    - **Input:** `{ table_name: string, id: string | number, key_column?: string, database?: string }`
+13. `count_records`
+    - **Permission:** `read`
+    - **Description:** Returns total count of records matching optional filters/conditions.
+    - **Input:** `{ table_name: string, filters?: any[], conditions?: any[], database?: string }`
+14. `create_record`
+    - **Permission:** `create`
+    - **Description:** Inserts a single record into a table.
+    - **Input:** `{ table_name: string, data: Record<string, any>, database?: string }`
+15. `bulk_insert`
+    - **Permission:** `create`
+    - **Description:** Batch inserts multiple records into a table.
+    - **Input:** `{ table_name: string, records: Array<Record<string, any>>, database?: string }`
+16. `update_record`
+    - **Permission:** `update`
+    - **Description:** Updates records matching specified filter conditions. Accepts `filters` or `conditions`.
+    - **Input:** `{ table_name: string, data: Record<string, any>, filters?: any[], conditions?: any[], database?: string }`
+17. `bulk_update`
+    - **Permission:** `update`
+    - **Description:** Batch updates records by primary key.
+    - **Input:** `{ table_name: string, records: Array<Record<string, any>>, key_column: string, database?: string }`
+18. `delete_record`
+    - **Permission:** `delete`
+    - **Description:** Deletes records matching specified filter conditions. Accepts `filters` or `conditions`.
+    - **Input:** `{ table_name: string, filters?: any[], conditions?: any[], database?: string }`
+19. `bulk_delete`
+    - **Permission:** `delete`
+    - **Description:** Batch deletes records by matching primary key array.
+    - **Input:** `{ table_name: string, key_column: string, keys: Array<string | number>, database?: string }`
+
+### 5.3 Data Profiling & Analysis
+20. `get_column_statistics` *(New AI-Optimized)*
+    - **Permission:** `read`
+    - **Description:** Returns detailed statistical analysis for a specific column: total rows, non-null count, null percentage, distinct count, min/max values, and top frequent values.
+    - **Input:** `{ table_name: string, column_name: string, database?: string }`
+
+### 5.4 Query Management
+21. `run_select_query`
+    - **Permission:** `read`
+    - **Description:** Executes read-only SQL queries via API with optional pagination or bypass. Semicolon-safe and supports `all: true`.
+    - **Input:** `{ query: string, params?: any[], page?: number, limit?: number, bypass_pagination?: boolean, all?: boolean, database?: string }`
+22. `execute_write_query`
+    - **Permission:** `execute` (requires `delete` for DELETE statements, `ddl` for DDL statements; blocks dangerous keywords)
+    - **Description:** Executes INSERT, UPDATE, or guarded mutation queries via API.
+    - **Input:** `{ query: string, params?: any[], database?: string }`
+
+### 5.5 Schema Management (DDL)
+23. `create_table`
+    - **Permission:** `ddl`
+    - **Description:** Creates a new table via API.
+    - **Input:** `{ table_name: string, columns: any[], primary_key?: string | string[], database?: string }`
+24. `alter_table`
+    - **Permission:** `ddl`
+    - **Description:** Adds, modifies, or drops columns via API.
+    - **Input:** `{ table_name: string, action: string, column_definition: any, database?: string }`
+25. `drop_table`
+    - **Permission:** `ddl`
+    - **Description:** Drops a table via API.
+    - **Input:** `{ table_name: string, if_exists?: boolean, database?: string }`
+26. `execute_ddl`
+    - **Permission:** `ddl`
+    - **Description:** Executes raw DDL statements via API with dangerous keyword checks.
+    - **Input:** `{ query: string, database?: string }`
+
+### 5.6 Utilities & Diagnostics
+27. `test_connection`
+    - **Permission:** `utility`
+    - **Description:** Pings remote API endpoint, verifies credentials, database connectivity, and latency in milliseconds.
+    - **Input:** `{}`
+28. `describe_connection`
+    - **Permission:** `utility`
+    - **Description:** Reports active API endpoint, server status, permissions profile, and pagination configuration.
+    - **Input:** `{}`
+29. `list_all_tools`
+    - **Permission:** `utility`
+    - **Description:** Returns a dynamic catalog of all 31 MCP tools with active permission status and agent recommendations.
+    - **Input:** `{}`
+30. `export_table_to_csv`
+    - **Permission:** `utility`
+    - **Description:** Exports table data as CSV string via API.
+    - **Input:** `{ table_name: string, limit?: number, database?: string }`
+31. `export_query_to_csv`
+    - **Permission:** `utility`
+    - **Description:** Exports SELECT query results as CSV string via API (guarded to read-only queries).
+    - **Input:** `{ query: string, limit?: number, database?: string }`
+
+---
+
+## 6. API Server Endpoint Specifications (Companion Server)
+
+The standalone companion Express API server (`src/server/apiServer.ts`) provides full REST access for all tables:
+
+| Method | Endpoint | Description | Auth Required | Permission Checked |
+|--------|----------|-------------|---------------|--------------------|
+| `GET` | `/health` | Server & DB health check + latency measurement | No | Public |
+| `GET` | `/api/info` | Server metadata, version & permission policy | Yes | Utility |
+| `GET` | `/api/databases` | List all databases | Yes | `list` |
+| `GET` | `/api/tables` | List tables in database | Yes | `list` |
+| `GET` | `/api/tables/find` | Find tables by keyword | Yes | `list` |
+| `GET` | `/api/tables/search-data` | Search text data across tables | Yes | `read` |
+| `GET` | `/api/tables/:table/schema` | Get column metadata & indexes | Yes | `list` |
+| `GET` | `/api/tables/:table/records` | Read records with query params (`page`, `limit`, `bypass`, `sort`, `filters`) | Yes | `read` |
+| `GET` | `/api/tables/:table/records/:id` | Point lookup single record by ID | Yes | `read` |
+| `POST` | `/api/tables/:table/records` | Insert single record | Yes | `create` |
+| `POST` | `/api/tables/:table/records/bulk` | Bulk insert records | Yes | `create` |
+| `PUT` | `/api/tables/:table/records/:id` | Update single record by ID | Yes | `update` |
+| `PUT` | `/api/tables/:table/records` | Update records matching condition | Yes | `update` |
+| `PUT` | `/api/tables/:table/records/bulk` | Bulk update records | Yes | `update` |
+| `DELETE` | `/api/tables/:table/records/:id` | Delete single record by ID | Yes | `delete` |
+| `DELETE` | `/api/tables/:table/records` | Delete records matching condition | Yes | `delete` |
+| `POST` | `/api/tables/:table/records/bulk-delete` | Bulk delete records by IDs | Yes | `delete` |
+| `GET` | `/api/tables/:table/count` | Count records matching filter | Yes | `read` |
+| `GET` | `/api/tables/:table/columns/:column/stats` | Statistical profile of column | Yes | `read` |
+| `POST` | `/api/query/select` | Execute SELECT query | Yes | `read` |
+| `POST` | `/api/query/write` | Execute INSERT/UPDATE query | Yes | `execute` |
+| `POST` | `/api/tables` | Create new table | Yes | `ddl` |
+| `PUT` | `/api/tables/:table` | Alter existing table | Yes | `ddl` |
+| `DELETE` | `/api/tables/:table` | Drop existing table | Yes | `ddl` |
+| `POST` | `/api/ddl` | Execute DDL statements | Yes | `ddl` |
+| `GET` | `/api/schema/summary` | Get database summary | Yes | `list` |
+| `GET` | `/api/schema/rag-context` | Generate ultra-compact RAG schema | Yes | `list` |
+| `GET` | `/api/schema/erd` | Generate ER diagram data | Yes | `list` |
+| `GET` | `/api/schema/relationships` | Get foreign key relationships | Yes | `list` |
+| `GET` | `/api/schema/search` | Search schema metadata | Yes | `list` |
+| `GET` | `/api/tables/:table/export` | Export table to CSV | Yes | `utility` |
+| `POST` | `/api/query/export` | Export SELECT query to CSV | Yes | `utility` |
+| `ALL` | `*` (Catch-all) | 404 Handler guaranteeing strict JSON error | Yes | None |
+
+---
+
+## 7. Configuration & Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MYSQL_API_ENDPOINT` | `http://localhost:3300` | Remote MySQL API server URL |
+| `MYSQL_API_KEY` | `""` | API Key or Bearer token for authentication |
+| `MCP_PERMISSIONS` | `all` | Permission preset (`only-read`, `read-write`, `admin`, or comma-separated list) |
+| `API_PERMISSIONS` | `all` | Server-level permission preset enforced on HTTP endpoints |
+| `DEFAULT_PAGE_SIZE` | `50` | Default records per page |
+| `MAX_PAGE_SIZE` | `500` | Maximum allowed records per page |
+| `MAX_BYPASS_LIMIT` | `10000` | Maximum allowed records during pagination bypass |
+| `API_TIMEOUT_MS` | `30000` | Network timeout for API requests in milliseconds |
+| `PORT` | `3300` | HTTP port for the companion API server |
+
+---
+
+## 8. Verification & Testing Strategy
+
+1. **Unit Testing:**
+   - Permissions engine: verify `only-read` blocks all mutating tools; verify custom lists; verify queryContext inspection.
+   - Strict JSON formatter: guarantee that every response envelope parses via `JSON.parse()`.
+   - Pagination engine: verify default limit applied; verify bypass mode logic.
+2. **Integration Testing:**
+   - In-memory mock API server simulating remote endpoints.
+   - Full MCP tool invocation cycles over simulated stdio transport.
+   - Security tests: operator normalization, SQL injection rejection, dangerous SQL keyword blocking.
+   - Dual-layer tests: API server blocking mutations with HTTP 403 under `only-read`.
+   - Strict JSON 404/500 tests: verify zero HTML output.
+3. **Build & Type Safety:**
+   - Zero TypeScript compile errors (`tsc`).
+   - Clean Jest test execution (100% passing across 6 test suites and 61 tests).

package/README.md

@@ -0,0 +1,202 @@
+# MySQL MCP via API (`mcp-mysql-via-api`)
+
+A production-grade **Model Context Protocol (MCP)** server for interacting with MySQL databases **via HTTP/REST API endpoints** on a remote server. Specially optimized for autonomous AI agents like **Hermes AI** and **OpenClaw**, as well as IDEs (Cursor, Windsurf, Cline) and desktop/CLI environments.
+
+---
+
+## 🌟 Key Features
+
+- **Decoupled Architecture:** Access MySQL securely without exposing port 3306 or direct database socket connections across corporate firewalls or VPCs. Connects via an authenticated HTTP/REST API endpoint.
+- **Strict Valid JSON Output Guarantee:** 100% of all tool responses (both success results and error envelopes) are strictly formatted as valid JSON (`application/json`). Never plain text, no raw markdown backticks, no emoji error prefixes, and never HTML error pages (even on HTTP 404/500).
+- **Default Pagination + Instant Bypass:**
+  - Multi-row operations (`read_records`, `run_select_query`, `search_data_across_tables`) paginate by default (`page=1`, `limit=50`).
+  - Supports instant bypass (`bypass_pagination: true` or `all: true`) for full dataset extraction with memory safety guards (`MAX_BYPASS_LIMIT`).
+- **Dual-Layer Defense Permission System:**
+  - **MCP Client Level:** Pre-execution verification preventing unauthorized tool dispatch.
+  - **API Server Level:** HTTP endpoint authorization via `API_PERMISSIONS` returning HTTP 403 Forbidden envelopes.
+  - Presets: `only-read` (read-only), `read-write`, `admin` (all operations).
+  - Granular permissions: `list`, `read`, `create`, `update`, `delete`, `execute`, `ddl`, `utility`.
+- **AI Agent Context Window Optimization (Hermes & OpenClaw):**
+  - `get_schema_rag_context`: Ultra-compact schema representation designed to preserve LLM token context windows.
+  - `search_data_across_tables`: Cross-table text search when schema storage location is unknown.
+  - `get_column_statistics`: Statistical data profiling (null percentage, distinct values, min/max, distribution).
+  - `read_record`: Direct point lookup by primary key or ID.
+- **Direct Table REST Endpoints:** Every table exposes standard REST endpoints (`/api/tables/:table/records`, `/api/tables/:table/records/:id`, `/api/tables/:table/count`, etc.).
+- **Companion MySQL REST API Server Included:** Comes with a standalone Express/Node.js API server (`npm run start:server`) that can be deployed directly to the remote database machine.
+
+---
+
+## 🚀 Quick Start
+
+### 1. Installation
+
+```bash
+cd C:\DEKSTOP\MCP\mcp_mysql_via_api
+npm install
+npm run build
+```
+
+### 2. Configure Environment
+
+Copy `.env.example` to `.env`:
+
+```env
+MYSQL_API_ENDPOINT=http://remote-mysql-server:3300
+MYSQL_API_KEY=your-secure-api-token
+MCP_PERMISSIONS=only-read
+API_PERMISSIONS=only-read
+DEFAULT_PAGE_SIZE=50
+```
+
+### 3. Start the MCP Server
+
+```bash
+npm start
+```
+
+Or run directly via Node/CLI:
+
+```bash
+node dist/mcp-server.js http://remote-server:3300 only-read your-api-key
+```
+
+---
+
+## 🤖 AI Agent Integration
+
+### Hermes AI / OpenClaw Configuration
+
+Add to your agent's MCP servers config (`mcp_config.json` or agent YAML):
+
+```json
+{
+  "mcpServers": {
+    "mysql_via_api": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@jessejoris/mcp-mysql-via-api",
+        "http://your-remote-api-server:3300",
+        "only-read",
+        "your-api-key"
+      ],
+      "env": {
+        "MYSQL_API_ENDPOINT": "http://your-remote-api-server:3300",
+        "MYSQL_API_KEY": "your-api-key",
+        "MCP_PERMISSIONS": "only-read",
+        "DEFAULT_PAGE_SIZE": "50"
+      }
+    }
+  }
+}
+```
+
+### Cursor / Windsurf / Claude Desktop (`claude_desktop_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "mysql_api": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@jessejoris/mcp-mysql-via-api"
+      ],
+      "env": {
+        "MYSQL_API_ENDPOINT": "https://api.internal.example.com",
+        "MYSQL_API_KEY": "secret-bearer-token",
+        "MCP_PERMISSIONS": "only-read"
+      }
+    }
+  }
+}
+```
+
+---
+
+## 🔒 Permission Profiles
+
+Set via `MCP_PERMISSIONS` and `API_PERMISSIONS` environment variables or CLI arguments:
+
+| Preset | Allowed Categories | Mutating Actions Blocked? |
+|--------|-------------------|--------------------------|
+| `only-read` / `readonly` | `list`, `read`, `utility` | ✅ Blocks `create`, `update`, `delete`, `execute`, `ddl` |
+| `read-write` | `list`, `read`, `create`, `update`, `utility` | ✅ Blocks `delete`, `execute`, `ddl` |
+| `admin` / `all` | All permissions | None blocked |
+| Custom (e.g. `list,read`) | Explicit list | Blocks anything omitted |
+
+---
+
+## 🧰 Available Tools (31 Tools Catalog)
+
+### Discovery & Schema
+1. `list_databases`: Lists all accessible databases.
+2. `list_tables`: Lists tables in database.
+3. `read_table_schema`: Full column and index definitions.
+4. `get_database_summary`: Structural overview of tables and rows.
+5. `get_schema_erd`: Generates Mermaid.js ER diagram.
+6. `get_schema_rag_context`: Ultra-compact schema for LLM context windows.
+7. `get_all_tables_relationships`: Analyzes foreign key relationships.
+8. `search_schema`: Searches table and column metadata.
+9. `find_tables_by_keyword`: Ranked keyword search for candidate tables.
+10. `search_data_across_tables`: Scans text data across tables for keywords.
+
+### CRUD & Data
+11. `read_records`: Reads rows with pagination, sorting, and filter conditions.
+12. `read_record`: Direct point lookup by primary key or ID.
+13. `count_records`: Counts matching rows.
+14. `create_record`: Inserts single record.
+15. `bulk_insert`: Batch inserts multiple records.
+16. `update_record`: Updates records matching filter conditions.
+17. `bulk_update`: Batch updates records by primary key.
+18. `delete_record`: Deletes records matching filter conditions.
+19. `bulk_delete`: Batch deletes records by primary keys.
+
+### Data Profiling
+20. `get_column_statistics`: Statistical data profiling of column values.
+
+### Query Execution
+21. `run_select_query`: Runs read-only SELECT queries with pagination/bypass.
+22. `execute_write_query`: Executes guarded mutation queries with DDL/dangerous keyword checks.
+
+### Schema Management (DDL)
+23. `create_table`: Creates table.
+24. `alter_table`: Alters table columns.
+25. `drop_table`: Drops table.
+26. `execute_ddl`: Executes raw DDL statements.
+
+### Diagnostics & Utilities
+27. `test_connection`: Pings remote API, checks DB connection and latency.
+28. `describe_connection`: Returns endpoint, status, and active permission policies.
+29. `list_all_tools`: Live catalog of all 31 tools with active permission status.
+30. `export_table_to_csv`: Exports table data to CSV.
+31. `export_query_to_csv`: Exports SELECT query results to CSV.
+
+---
+
+## 🖥️ Companion MySQL API Server
+
+Deploy `src/server/` on your remote server running MySQL:
+
+```bash
+# On remote server
+export DB_HOST=localhost
+export DB_USER=root
+export DB_PASSWORD=my-password
+export DB_NAME=production_db
+export MYSQL_API_KEY=my-secret-key
+export API_PERMISSIONS=only-read # Optional server-level guard
+export PORT=3300
+
+npm run start:server
+```
+
+---
+
+## 🧪 Testing
+
+```bash
+npm test
+```
+
+Runs all 6 test suites covering 61 unit and integration tests.

package/bin/mcp-mysql-via-api.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+const path = require("path");
+require(path.join(__dirname, "../dist/mcp-server.js"));

package/dist/api-client/mysqlApiClient.d.ts

@@ -0,0 +1,46 @@
+import { ReadRecordsParams, ReadRecordParams, CreateRecordParams, BulkInsertParams, UpdateRecordParams, BulkUpdateParams, DeleteRecordParams, BulkDeleteParams, CountRecordsParams, SelectQueryParams, WriteQueryParams, DdlQueryParams, CreateTableParams, DropTableParams, RagContextParams, SearchDataParams, ColumnStatsParams, ServerConfig } from "../types/index.js";
+export declare class MysqlApiClient {
+    private endpoint;
+    private apiKey;
+    private timeoutMs;
+    private defaultPageSize;
+    private maxPageSize;
+    private maxBypassLimit;
+    constructor(config: ServerConfig);
+    private getHeaders;
+    private request;
+    testConnection(): Promise<any>;
+    getInfo(): Promise<any>;
+    listDatabases(): Promise<any>;
+    listTables(database?: string): Promise<any>;
+    readTableSchema(tableName: string, database?: string): Promise<any>;
+    getDatabaseSummary(options?: {
+        database?: string;
+        maxTables?: number;
+        includeRelationships?: boolean;
+    }): Promise<any>;
+    getSchemaRagContext(options?: RagContextParams): Promise<any>;
+    getSchemaErd(database?: string): Promise<any>;
+    getAllTablesRelationships(database?: string): Promise<any>;
+    searchSchema(query: string, database?: string): Promise<any>;
+    findTablesByKeyword(keyword: string, database?: string, limit?: number): Promise<any>;
+    searchDataAcrossTables(options: SearchDataParams): Promise<any>;
+    readRecords(params: ReadRecordsParams): Promise<any>;
+    readRecord(params: ReadRecordParams): Promise<any>;
+    countRecords(params: CountRecordsParams): Promise<any>;
+    getColumnStatistics(params: ColumnStatsParams): Promise<any>;
+    createRecord(params: CreateRecordParams): Promise<any>;
+    bulkInsert(params: BulkInsertParams): Promise<any>;
+    updateRecord(params: UpdateRecordParams): Promise<any>;
+    bulkUpdate(params: BulkUpdateParams): Promise<any>;
+    deleteRecord(params: DeleteRecordParams): Promise<any>;
+    bulkDelete(params: BulkDeleteParams): Promise<any>;
+    runSelectQuery(params: SelectQueryParams): Promise<any>;
+    executeWriteQuery(params: WriteQueryParams): Promise<any>;
+    createTable(params: CreateTableParams): Promise<any>;
+    alterTable(tableName: string, action: string, columnDefinition: any, database?: string): Promise<any>;
+    dropTable(params: DropTableParams): Promise<any>;
+    executeDdl(params: DdlQueryParams): Promise<any>;
+    exportTableToCsv(tableName: string, limit?: number, database?: string): Promise<any>;
+    exportQueryToCsv(query: string, limit?: number, database?: string): Promise<any>;
+}