@williamp29/project-mcp-server 1.1.0 → 2.0.0

package/README.md

@@ -1,153 +1,120 @@
-# Your project's MCP Server
+# Project MCP Server
 
-A powerful Model Context Protocol (MCP) server that dynamically serves context about your project. It can explore and interact with any API defined by an OpenAPI specification.
+A powerful **Model Context Protocol (MCP)** server that dynamically serves context about your project. It acts as a bridge, allowing LLM agents to explore and interact with your project's APIs (via OpenAPI) and databases.
 
-## For LLM Agents: How to use this MCP
+## Quick Start (Zero Config)
 
-This server provides a set of "meta-tools" that allow you to discover and interact with an API without needing individual tools for every endpoint.
+The easiest way to use this server is to run it directly with `npx`. This requires no code changes to your project.
 
-### Recommended Workflow:
-1.  **Discovery**: Start by calling `get_tags` to understand the broad areas of the API.
-2.  **Listing**: Use `get_tag_endpoints` or `get_all_endpoints` to see available actions for a specific topic.
-3.  **Details**: Call `get_endpoint` for a specific path and method to see exactly what parameters and request body are required.
-4.  **Execution**: Use `call_endpoint` to perform the actual API request.
+### Run with npx
 
-### Identity & Impersonation:
-If the server is configured with an `identity` strategy, you can use `set_identity` to act on behalf of a specific user (e.g., passing a UID).
+**For Cursor / Claude Desktop:**
+Add this to your MCP settings configuration:
 
----
-
-## Installation & Setup
-
-### 1. Build the project
-```bash
-npm install
-npm run build
-```
-
-### 2. Configure Environment Variables
-Create a `.env` file (see `.env.example`):
-- `PROJECT_MCP_API_BASE_URL`: The target API URL.
-- `PROJECT_MCP_AUTH_TYPE`: `bearer`, `identity`, or `none`.
-- `PROJECT_MCP_AUTH_IDENTIFIABLE`: (Optional) e.g., `UID:`.
-- `PROJECT_MCP_AUTH_IDENTIFIER`: Default ID value.
-
-### 3. Usage in Cursor / Claude Desktop
-Add a new MCP server with the following command:
-```bash
-node /path/to/dist/cli.js
+```json
+{
+  "mcpServers": {
+    "my-project": {
+      "command": "npx",
+      "args": ["-y", "@williamp29/project-mcp-server"],
+      "env": {
+        "PROJECT_MCP_API_BASE_URL": "...",
+        "PROJECT_MCP_DB_HOST": "..."
+      }
+    }
+  }
+}
 ```
+*(Note: You can pass environment variables directly in the JSON config or load them from a file if your MCP client supports it.)*
 
-Or if installed via npm:
-```bash
-npx @williamp29/project-mcp-server
-```
+---
 
-## Integration in Your Project
+## Library Integration (Advanced)
 
-The recommended way to use this package is to install it in your project and create a custom entry point.
+For deep integration, install the package as a dependency in your Node.js project. This allows you to customize authentication, add custom tools, or use it programmatically.
 
-### Step 1: Install
+### 1. Install
 ```bash
 npm install @williamp29/project-mcp-server
 ```
 
-### Step 2: Create your MCP entry file
-Create a file called `mcp-serve.js` (or `.ts`) in your project root:
+### 2. Create an Entry Point
+Create a file (e.g., `mcp-server.ts`) to configure and start your server:
 
-```javascript
-// mcp-serve.js
+```typescript
 import { MCPServer } from "@williamp29/project-mcp-server";
 import { AuthStrategy, GlobalAuthContext } from "@williamp29/project-mcp-server/api-explorer";
 
-// Your custom authentication logic
-class MyAuth implements AuthStrategy {
-  name = "MyAuth";
+// (Optional) Define a custom authentication strategy
+class MyCustomAuth implements AuthStrategy {
+  name = "MyCustomAuth";
   async getHeaders() {
-    // Read from your own config, database, vault, etc.
+    // Fetch token from vault, env, or database
     return { "Authorization": `Bearer ${process.env.MY_API_TOKEN}` };
   }
 }
 
-const authContext = new GlobalAuthContext(new MyAuth());
-const server = new MCPServer("./openapi-spec.json", authContext);
-server.start();
+const server = new MCPServer({
+  specPath: "./openapi-spec.json", // Path to your OpenAPI spec
+  authContext: new GlobalAuthContext(new MyCustomAuth())
+});
+
+server.start().catch(console.error);
 ```
 
-### Step 3: Add the npm script
-In your project's `package.json`:
+### 3. Add Script to package.json
 ```json
 {
   "scripts": {
-    "mcp:serve": "node mcp-serve.js"
+    "mcp": "ts-node mcp-server.ts"
   }
 }
 ```
 
-### Step 4: Configure Cursor
-In your Cursor MCP settings (`mcp_settings.json`):
+### 4. Use in Cursor
 ```json
 {
-  "my-api-mcp": {
-    "command": "npm",
-    "args": ["run", "mcp:serve"],
-    "cwd": "/absolute/path/to/your/project"
+  "mcpServers": {
+    "my-integrated-project": {
+      "command": "npm",
+      "args": ["run", "mcp"],
+      "cwd": "/absolute/path/to/your/project"
+    }
   }
 }
 ```
 
-Now Cursor will run your custom script whenever it needs to use the MCP server.
-
 ---
 
-## Programmatic Usage
+## Configuration Reference
 
-If you are using this as a library in your own Node.js project:
+### Environment Variables
+These variables control the server behavior. They are automatically loaded if you use the `npx` method or if you use `dotenv` in your custom script.
 
-### Basic Setup
-```typescript
-import { MCPServer } from "@williamp29/project-mcp-server";
+| Variable | Description | Default |
+| :--- | :--- | :--- |
+| `PROJECT_MCP_API_BASE_URL` | Base URL of the target API | - |
+| `PROJECT_MCP_AUTH_TYPE` | Auth method: `bearer`, `identity`, `none` | `none` |
+| `PROJECT_MCP_AUTH_IDENTIFIER` | Default ID for `identity` auth | - |
+| `PROJECT_MCP_DB_HOST` | Database hostname | - |
+| `PROJECT_MCP_DB_PORT` | Database port | `3306` |
+| `PROJECT_MCP_DB_USER` | Database username | - |
+| `PROJECT_MCP_DB_PASSWORD` | Database password | - |
+| `PROJECT_MCP_DB_DATABASE` | Database name | - |
 
-const server = new MCPServer("./openapi-spec.json");
-server.start().catch(console.error);
-```
-
-### Custom Authentication Strategy
-You can implement your own logic for fetching or rotating tokens:
-
-```typescript
-import { MCPServer } from "@williamp29/project-mcp-server";
-import { AuthStrategy, GlobalAuthContext } from "@williamp29/project-mcp-server/api-explorer";
-
-class MyCustomAuth implements AuthStrategy {
-  name = "MyCustomAuth";
-  async getHeaders() {
-    const token = await fetchTokenFromVault();
-    return { "X-Custom-Auth": token };
-  }
-}
-
-const authContext = new GlobalAuthContext(new MyCustomAuth());
-const server = new MCPServer("./spec.json", authContext);
-server.start();
-```
-
-### Request Hooks
-Add custom logic to every request (logging, tracing, extra headers):
-
-```typescript
-import { addRequestHook } from "@williamp29/project-mcp-server/api-explorer";
-
-addRequestHook((config) => {
-  console.error(`[API] ${config.method?.toUpperCase()} ${config.url}`);
-  config.headers["X-Request-ID"] = "mcp-123";
-  return config;
-});
-```
+---
 
 ## Features
-- **Dynamic Exploration**: Automatically parses Swagger/OpenAPI 3.0 specs.
-- **Smart Execution**: Handles path parameters (e.g., `{id}`), query strings, and JSON bodies.
-- **Flexible Auth**: Support for standard Bearer tokens and custom Identity headers.
-- **Interceptors**: Easily extendable with request hooks for logging or custom headers.
-- **Impersonation**: Built-in `set_identity` tool to switch users on the fly.
+
+- **API Explorer**:
+  - Automatically parses OpenAPI 3.0 specifications.
+  - Exposes tools like `api_get_tags`, `api_get_endpoints`, and `api_call_endpoint`.
+  - Supports dynamic path parameters and JSON bodies.
+  - `api_set_identity`: Switch the active user context for API calls dynamically during a session.
+
+- **Database Explorer**:
+  - Inspect schemas with `db_list_tables`, `db_describe_tables`, and `db_get_schemas`.
+  - Discover database structure with `db_get_relationships` (supports table filtering).
+  - Analyze data with `db_get_table_stats` and `db_sample_rows`.
+  - Run validated SQL with `db_run_query`, `db_run_update_statement`, and `db_run_delete_statement`.
+  - Supports MySQL (driver included).

package/dist/api-explorer/api-executor.js

@@ -24,14 +24,12 @@ export class ApiExecutor {
         });
         // Add interceptor for dynamic auth and hooks
         this.client.interceptors.request.use(async (config) => {
-            // 1. Inject Dynamic Auth Headers
             const authHeaders = await this.authContext.getHeaders();
             // Log for debugging (stderr)
             if (Object.keys(authHeaders).length > 0) {
                 console.error(`[ApiExecutor] Injecting auth headers from strategy: ${this.authContext.strategy.name}`);
             }
             Object.assign(config.headers, authHeaders);
-            // 2. Run Request Hooks
             return await runRequestHooks(config);
         });
     }

package/dist/api-explorer/tool-generator.d.ts

@@ -20,32 +20,32 @@ export declare class ToolGenerator {
      * These definitions are used by MCPServer to register tools with the SDK.
      */
     getToolDefinitions(): {
-        get_tags: {
+        api_get_tags: {
             description: string;
         };
-        get_tag_endpoints: {
+        api_get_tag_endpoints: {
             description: string;
             inputSchema: z.ZodObject<{
                 tag: z.ZodString;
             }, z.core.$strip>;
         };
-        get_tags_endpoints: {
+        api_get_tags_endpoints: {
             description: string;
             inputSchema: z.ZodObject<{
                 tags: z.ZodArray<z.ZodString>;
             }, z.core.$strip>;
         };
-        get_all_endpoints: {
+        api_get_all_endpoints: {
             description: string;
         };
-        get_endpoint: {
+        api_get_endpoint: {
             description: string;
             inputSchema: z.ZodObject<{
                 method: z.ZodString;
                 path: z.ZodString;
             }, z.core.$strip>;
         };
-        get_endpoints: {
+        api_get_endpoints: {
             description: string;
             inputSchema: z.ZodObject<{
                 requests: z.ZodArray<z.ZodObject<{
@@ -54,7 +54,7 @@ export declare class ToolGenerator {
                 }, z.core.$strip>>;
             }, z.core.$strip>;
         };
-        call_endpoint: {
+        api_call_endpoint: {
             description: string;
             inputSchema: z.ZodObject<{
                 method: z.ZodString;

package/dist/api-explorer/tool-generator.js

@@ -17,32 +17,32 @@ export class ToolGenerator {
      */
     getToolDefinitions() {
         return {
-            get_tags: {
+            api_get_tags: {
                 description: "Get all unique tags defined in the API spec. This helps to group and discover endpoints.",
             },
-            get_tag_endpoints: {
+            api_get_tag_endpoints: {
                 description: "Get all endpoints associated with a specific tag. Returns a summary of each endpoint.",
                 inputSchema: z.object({
                     tag: z.string().describe("The tag to filter endpoints by."),
                 }),
             },
-            get_tags_endpoints: {
+            api_get_tags_endpoints: {
                 description: "Get all endpoints associated with multiple tags. Returns a summary of each endpoint.",
                 inputSchema: z.object({
                     tags: z.array(z.string()).describe("The tags to filter endpoints by."),
                 }),
             },
-            get_all_endpoints: {
+            api_get_all_endpoints: {
                 description: "Get a summarized list of all endpoints available in the API.",
             },
-            get_endpoint: {
+            api_get_endpoint: {
                 description: "Get detailed information about a specific endpoint, including parameters and request body schema.",
                 inputSchema: z.object({
                     method: z.string().describe("The HTTP method (GET, POST, etc.)."),
                     path: z.string().describe("The endpoint path."),
                 }),
             },
-            get_endpoints: {
+            api_get_endpoints: {
                 description: "Get detailed information for multiple specific endpoints.",
                 inputSchema: z.object({
                     requests: z.array(z.object({
@@ -51,7 +51,7 @@ export class ToolGenerator {
                     })).describe("List of endpoint requests."),
                 }),
             },
-            call_endpoint: {
+            api_call_endpoint: {
                 description: "Execute a request to a project's endpoint using the specified parameters and body.",
                 inputSchema: z.object({
                     method: z.string().describe("The HTTP method."),
@@ -64,17 +64,17 @@ export class ToolGenerator {
     }
     handleToolCall(name, args) {
         switch (name) {
-            case "get_tags":
+            case "api_get_tags":
                 return this.parser.getTags();
-            case "get_tag_endpoints":
+            case "api_get_tag_endpoints":
                 return this.parser.getEndpointsByTag(args.tag);
-            case "get_tags_endpoints":
+            case "api_get_tags_endpoints":
                 return this.parser.getEndpointsByTags(args.tags);
-            case "get_all_endpoints":
+            case "api_get_all_endpoints":
                 return this.parser.getEndpoints();
-            case "get_endpoint":
+            case "api_get_endpoint":
                 return this.parser.getEndpoint(args.method, args.path);
-            case "get_endpoints":
+            case "api_get_endpoints":
                 return args.requests.map((r) => this.parser.getEndpoint(r.method, r.path));
             default:
                 throw new Error(`Unknown tool: ${name}`);

package/dist/cli.d.ts

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-export {};
+import "dotenv/config";

package/dist/cli.js

@@ -1,12 +1,29 @@
 #!/usr/bin/env node
+import "dotenv/config";
 import { MCPServer } from "./index.js";
 import path from "path";
-import { fileURLToPath } from "url";
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const DEFAULT_SPEC_PATH = path.resolve(__dirname, "../openapi-spec.json");
-const specPath = process.argv[2] || DEFAULT_SPEC_PATH;
-const server = new MCPServer(specPath);
+const specPath = process.env.PROJECT_MCP_OPENAPI_SPEC || path.resolve(process.cwd(), "openapi-spec.json");
+let dbConfig = undefined;
+if (process.env.PROJECT_MCP_DB_HOST) {
+    dbConfig = {
+        driver: process.env.PROJECT_MCP_DB_DRIVER || "mysql",
+        host: process.env.PROJECT_MCP_DB_HOST || "localhost",
+        port: parseInt(process.env.PROJECT_MCP_DB_PORT || "3306", 10),
+        user: process.env.PROJECT_MCP_DB_USER || "",
+        password: process.env.PROJECT_MCP_DB_PASSWORD || "",
+        database: process.env.PROJECT_MCP_DB_DATABASE || "",
+        poolSize: parseInt(process.env.PROJECT_MCP_DB_POOL_SIZE || "10", 10),
+        enableRunQuery: process.env.PROJECT_MCP_DB_ENABLE_QUERY !== "false",
+        enableRunUpdateStatement: process.env.PROJECT_MCP_DB_ENABLE_UPDATE !== "false",
+        enableRunDeleteStatement: process.env.PROJECT_MCP_DB_ENABLE_DELETE === "true",
+        enableRunStatement: process.env.PROJECT_MCP_DB_ENABLE_STATEMENT === "true",
+    };
+}
+const server = new MCPServer({
+    specPath,
+    dbConfig
+});
 server.start().catch((error) => {
-    console.error("Fatal error in MCP server:", error);
+    console.error("Failed to start MCP server:", error);
     process.exit(1);
 });

package/dist/db-explorer/db-executor.d.ts

@@ -0,0 +1,21 @@
+import { DbDriver, DbConfig } from "./types.js";
+export declare class DbExecutor {
+    private driver;
+    private config;
+    constructor(driver: DbDriver, config: DbConfig);
+    getDriver(): DbDriver;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    listTables(): Promise<import("./types.js").TableInfo[]>;
+    describeTable(table: string): Promise<import("./types.js").ColumnInfo[]>;
+    describeTables(tables: string[]): Promise<Record<string, any>>;
+    getTableSchema(table: string): Promise<string>;
+    getTableSchemas(tables: string[]): Promise<Record<string, string>>;
+    getRelationships(tables?: string[]): Promise<import("./types.js").Relationship[]>;
+    getTableStats(table: string): Promise<import("./types.js").TableStats>;
+    sampleRows(table: string, limit?: number): Promise<any[]>;
+    runQuery(query: string): Promise<import("./types.js").QueryResult>;
+    runUpdateStatement(query: string): Promise<import("./types.js").UpdateResult>;
+    runDeleteStatement(query: string): Promise<import("./types.js").DeleteResult>;
+    runStatement(query: string): Promise<import("./types.js").StatementResult>;
+}

package/dist/db-explorer/db-executor.js

@@ -0,0 +1,77 @@
+import { SqlValidator } from "./sql-validator.js";
+export class DbExecutor {
+    driver;
+    config;
+    constructor(driver, config) {
+        this.driver = driver;
+        this.config = config;
+    }
+    getDriver() {
+        return this.driver;
+    }
+    async connect() {
+        await this.driver.connect();
+    }
+    async disconnect() {
+        await this.driver.disconnect();
+    }
+    async listTables() {
+        return await this.driver.listTables();
+    }
+    async describeTable(table) {
+        return await this.driver.describeTable(table);
+    }
+    async describeTables(tables) {
+        const results = {};
+        for (const table of tables) {
+            results[table] = await this.driver.describeTable(table);
+        }
+        return results;
+    }
+    async getTableSchema(table) {
+        return await this.driver.getTableSchema(table);
+    }
+    async getTableSchemas(tables) {
+        const results = {};
+        for (const table of tables) {
+            results[table] = await this.driver.getTableSchema(table);
+        }
+        return results;
+    }
+    async getRelationships(tables) {
+        return await this.driver.getRelationships(tables);
+    }
+    async getTableStats(table) {
+        return await this.driver.getTableStats(table);
+    }
+    async sampleRows(table, limit) {
+        return await this.driver.sampleRows(table, limit);
+    }
+    async runQuery(query) {
+        if (this.config.enableRunQuery === false) {
+            throw new Error("Tool 'run_query' is disabled.");
+        }
+        SqlValidator.isSelectOnly(query);
+        return await this.driver.executeQuery(query);
+    }
+    async runUpdateStatement(query) {
+        if (this.config.enableRunUpdateStatement === false) {
+            throw new Error("Tool 'run_update_statement' is disabled.");
+        }
+        SqlValidator.isUpdateOnly(query);
+        return await this.driver.executeUpdate(query);
+    }
+    async runDeleteStatement(query) {
+        if (this.config.enableRunDeleteStatement !== true) {
+            throw new Error("Tool 'run_delete_statement' is disabled.");
+        }
+        SqlValidator.isDeleteOnly(query);
+        return await this.driver.executeDelete(query);
+    }
+    async runStatement(query) {
+        if (this.config.enableRunStatement !== true) {
+            throw new Error("Tool 'run_statement' is disabled.");
+        }
+        return await this.driver.executeStatement(query);
+    }
+}

package/dist/db-explorer/db-tool-generator.d.ts

@@ -0,0 +1,67 @@
+import { z } from "zod";
+import { DbExecutor } from "./db-executor.js";
+export declare class DbToolGenerator {
+    private executor;
+    constructor(executor: DbExecutor);
+    getToolDefinitions(): {
+        db_list_tables: {
+            description: string;
+        };
+        db_describe_tables: {
+            description: string;
+            inputSchema: z.ZodObject<{
+                tables: z.ZodArray<z.ZodString>;
+            }, z.core.$strip>;
+        };
+        db_get_schemas: {
+            description: string;
+            inputSchema: z.ZodObject<{
+                tables: z.ZodArray<z.ZodString>;
+            }, z.core.$strip>;
+        };
+        db_get_relationships: {
+            description: string;
+            inputSchema: z.ZodObject<{
+                tables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strip>;
+        };
+        db_get_table_stats: {
+            description: string;
+            inputSchema: z.ZodObject<{
+                table: z.ZodString;
+            }, z.core.$strip>;
+        };
+        db_sample_rows: {
+            description: string;
+            inputSchema: z.ZodObject<{
+                table: z.ZodString;
+                limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+            }, z.core.$strip>;
+        };
+        db_run_query: {
+            description: string;
+            inputSchema: z.ZodObject<{
+                query: z.ZodString;
+            }, z.core.$strip>;
+        };
+        db_run_update_statement: {
+            description: string;
+            inputSchema: z.ZodObject<{
+                query: z.ZodString;
+            }, z.core.$strip>;
+        };
+        db_run_delete_statement: {
+            description: string;
+            inputSchema: z.ZodObject<{
+                query: z.ZodString;
+            }, z.core.$strip>;
+        };
+        db_run_statement: {
+            description: string;
+            inputSchema: z.ZodObject<{
+                query: z.ZodString;
+            }, z.core.$strip>;
+        };
+    };
+    handleToolCall(name: string, args: any): Promise<any[] | Record<string, any> | import("./types.js").TableStats | import("./types.js").QueryResult | import("./types.js").DeleteResult | import("./types.js").StatementResult>;
+}

package/dist/db-explorer/db-tool-generator.js

@@ -0,0 +1,95 @@
+import { z } from "zod";
+export class DbToolGenerator {
+    executor;
+    constructor(executor) {
+        this.executor = executor;
+    }
+    getToolDefinitions() {
+        return {
+            db_list_tables: {
+                description: "List all tables in the current database.",
+            },
+            db_describe_tables: {
+                description: "Get detailed information about columns for multiple tables.",
+                inputSchema: z.object({
+                    tables: z.array(z.string()).describe("List of table names to describe."),
+                }),
+            },
+            db_get_schemas: {
+                description: "Get the DDL statements for multiple tables.",
+                inputSchema: z.object({
+                    tables: z.array(z.string()).describe("List of table names."),
+                }),
+            },
+            db_get_relationships: {
+                description: "Get foreign key relationships in the database, optionally filtered by tables.",
+                inputSchema: z.object({
+                    tables: z.array(z.string()).optional().describe("Optional list of table names to filter relationships by."),
+                }),
+            },
+            db_get_table_stats: {
+                description: "Get row count and other statistics for a table.",
+                inputSchema: z.object({
+                    table: z.string().describe("The name of the table."),
+                }),
+            },
+            db_sample_rows: {
+                description: "Fetch sample rows from a table.",
+                inputSchema: z.object({
+                    table: z.string().describe("The name of the table."),
+                    limit: z.number().optional().default(10).describe("Maximum number of rows to fetch."),
+                }),
+            },
+            db_run_query: {
+                description: "Execute a read-only SELECT query. Blocks modification keywords.",
+                inputSchema: z.object({
+                    query: z.string().describe("The SQL SELECT query to execute."),
+                }),
+            },
+            db_run_update_statement: {
+                description: "Execute an INSERT or UPDATE statement. Blocks DELETE and other dangerous keywords.",
+                inputSchema: z.object({
+                    query: z.string().describe("The SQL INSERT/UPDATE statement."),
+                }),
+            },
+            db_run_delete_statement: {
+                description: "Execute a DELETE or TRUNCATE statement. Blocks DROP/ALTER.",
+                inputSchema: z.object({
+                    query: z.string().describe("The SQL DELETE/TRUNCATE statement."),
+                }),
+            },
+            db_run_statement: {
+                description: "Execute any SQL statement. Full access, use with extreme caution. Disabled by default.",
+                inputSchema: z.object({
+                    query: z.string().describe("The SQL statement to execute."),
+                }),
+            },
+        };
+    }
+    async handleToolCall(name, args) {
+        switch (name) {
+            case "db_list_tables":
+                return await this.executor.listTables();
+            case "db_describe_tables":
+                return await this.executor.describeTables(args.tables);
+            case "db_get_schemas":
+                return await this.executor.getTableSchemas(args.tables);
+            case "db_get_relationships":
+                return await this.executor.getRelationships(args.tables);
+            case "db_get_table_stats":
+                return await this.executor.getTableStats(args.table);
+            case "db_sample_rows":
+                return await this.executor.sampleRows(args.table, args.limit);
+            case "db_run_query":
+                return await this.executor.runQuery(args.query);
+            case "db_run_update_statement":
+                return await this.executor.runUpdateStatement(args.query);
+            case "db_run_delete_statement":
+                return await this.executor.runDeleteStatement(args.query);
+            case "db_run_statement":
+                return await this.executor.runStatement(args.query);
+            default:
+                throw new Error(`Unknown database tool: ${name}`);
+        }
+    }
+}

package/dist/db-explorer/drivers/index.d.ts

@@ -0,0 +1 @@
+export { MySQLDriver } from "./mysql-driver.js";

package/dist/db-explorer/drivers/index.js

@@ -0,0 +1 @@
+export { MySQLDriver } from "./mysql-driver.js";

package/dist/db-explorer/drivers/mysql-driver.d.ts

@@ -0,0 +1,20 @@
+import { DbDriver, DbConfig, TableInfo, ColumnInfo, Relationship, TableStats, QueryResult, UpdateResult, DeleteResult, StatementResult } from "../types.js";
+export declare class MySQLDriver implements DbDriver {
+    name: string;
+    private pool;
+    private config;
+    constructor(config: DbConfig);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    private getPool;
+    listTables(): Promise<TableInfo[]>;
+    describeTable(table: string): Promise<ColumnInfo[]>;
+    getTableSchema(table: string): Promise<string>;
+    getRelationships(tables?: string[]): Promise<Relationship[]>;
+    getTableStats(table: string): Promise<TableStats>;
+    sampleRows(table: string, limit?: number): Promise<any[]>;
+    executeQuery(query: string): Promise<QueryResult>;
+    executeUpdate(query: string): Promise<UpdateResult>;
+    executeDelete(query: string): Promise<DeleteResult>;
+    executeStatement(query: string): Promise<StatementResult>;
+}

package/dist/db-explorer/drivers/mysql-driver.js

@@ -0,0 +1,170 @@
+import mysql from "mysql2/promise";
+export class MySQLDriver {
+    name = "mysql";
+    pool = null;
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async connect() {
+        if (this.pool)
+            return;
+        this.pool = mysql.createPool({
+            host: this.config.host,
+            port: this.config.port,
+            user: this.config.user,
+            password: this.config.password,
+            database: this.config.database,
+            connectionLimit: this.config.poolSize || 10,
+            waitForConnections: true,
+            queueLimit: 0
+        });
+        const connection = await this.pool.getConnection();
+        connection.release();
+        console.error(`[MySQLDriver] Connected to ${this.config.host}:${this.config.port}/${this.config.database}`);
+    }
+    async disconnect() {
+        if (this.pool) {
+            await this.pool.end();
+            this.pool = null;
+        }
+    }
+    getPool() {
+        if (!this.pool)
+            throw new Error("Driver not connected. Call connect() first.");
+        return this.pool;
+    }
+    async listTables() {
+        const [rows] = await this.getPool().execute(`SELECT TABLE_NAME as name, TABLE_SCHEMA as \`schema\`, TABLE_TYPE as type, TABLE_COMMENT as comment 
+       FROM INFORMATION_SCHEMA.TABLES 
+       WHERE TABLE_SCHEMA = ?`, [this.config.database]);
+        return rows.map((r) => ({
+            name: r.name,
+            schema: r.schema,
+            type: r.type,
+            comment: r.comment || undefined
+        }));
+    }
+    async describeTable(table) {
+        const [rows] = await this.getPool().execute(`SELECT 
+        COLUMN_NAME as name, 
+        DATA_TYPE as type, 
+        COLUMN_TYPE as fullType,
+        IS_NULLABLE as nullable, 
+        COLUMN_DEFAULT as defaultValue, 
+        COLUMN_KEY as columnKey, 
+        EXTRA as extra,
+        COLUMN_COMMENT as comment,
+        CHARACTER_MAXIMUM_LENGTH as characterMaxLength,
+        NUMERIC_PRECISION as numericPrecision,
+        NUMERIC_SCALE as numericScale
+       FROM INFORMATION_SCHEMA.COLUMNS 
+       WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ?
+       ORDER BY ORDINAL_POSITION`, [this.config.database, table]);
+        return rows.map((r) => {
+            const isEnum = r.fullType.startsWith("enum(") || r.fullType.startsWith("set(");
+            let enumValues;
+            if (isEnum) {
+                const matches = r.fullType.match(/'([^']*)'/g);
+                if (matches) {
+                    enumValues = matches.map((m) => m.replace(/'/g, ""));
+                }
+            }
+            return {
+                name: r.name,
+                type: r.type,
+                fullType: r.fullType,
+                nullable: r.nullable === "YES",
+                defaultValue: r.defaultValue,
+                isPrimaryKey: r.columnKey === "PRI",
+                isForeignKey: r.columnKey === "MUL",
+                isAutoIncrement: r.extra?.includes("auto_increment") || false,
+                comment: r.comment || undefined,
+                extra: r.extra || undefined,
+                enumValues,
+                characterMaxLength: r.characterMaxLength ? Number(r.characterMaxLength) : undefined,
+                numericPrecision: r.numericPrecision ? Number(r.numericPrecision) : undefined,
+                numericScale: r.numericScale ? Number(r.numericScale) : undefined
+            };
+        });
+    }
+    async getTableSchema(table) {
+        const [rows] = await this.getPool().execute(`SHOW CREATE TABLE \`${table}\``);
+        return rows[0]?.["Create Table"] || "";
+    }
+    async getRelationships(tables) {
+        let query = `SELECT 
+        CONSTRAINT_NAME as constraintName, 
+        TABLE_NAME as fromTable, 
+        COLUMN_NAME as fromColumn, 
+        REFERENCED_TABLE_NAME as toTable, 
+        REFERENCED_COLUMN_NAME as toColumn
+       FROM INFORMATION_SCHEMA.KEY_COLUMN_USAGE
+       WHERE TABLE_SCHEMA = ? AND REFERENCED_TABLE_NAME IS NOT NULL`;
+        const params = [this.config.database];
+        if (tables && tables.length > 0) {
+            const placeholders = tables.map(() => "?").join(",");
+            query += ` AND (TABLE_NAME IN (${placeholders}) OR REFERENCED_TABLE_NAME IN (${placeholders}))`;
+            params.push(...tables, ...tables);
+        }
+        const [rows] = await this.getPool().execute(query, params);
+        return rows.map((r) => ({
+            constraintName: r.constraintName,
+            fromTable: r.fromTable,
+            fromColumn: r.fromColumn,
+            toTable: r.toTable,
+            toColumn: r.toColumn
+        }));
+    }
+    async getTableStats(table) {
+        const [rows] = await this.getPool().execute(`SELECT 
+        TABLE_ROWS as rowCount,
+        DATA_LENGTH as dataLength,
+        INDEX_LENGTH as indexLength,
+        CREATE_TIME as createTime,
+        UPDATE_TIME as updateTime
+       FROM INFORMATION_SCHEMA.TABLES 
+       WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ?`, [this.config.database, table]);
+        const r = rows[0];
+        if (!r)
+            throw new Error(`Table ${table} not found.`);
+        return {
+            rowCount: Number(r.rowCount),
+            dataLength: Number(r.dataLength),
+            indexLength: Number(r.indexLength),
+            createTime: r.createTime ? new Date(r.createTime) : undefined,
+            updateTime: r.updateTime ? new Date(r.updateTime) : undefined
+        };
+    }
+    async sampleRows(table, limit = 10) {
+        const safeLimit = Math.max(1, Math.floor(Number(limit) || 10));
+        const [rows] = await this.getPool().execute(`SELECT * FROM \`${table}\` LIMIT ${safeLimit}`);
+        return rows;
+    }
+    async executeQuery(query) {
+        const [rows] = await this.getPool().execute(query);
+        return { rows };
+    }
+    async executeUpdate(query) {
+        const [result] = await this.getPool().execute(query);
+        return {
+            affectedRows: result.affectedRows,
+            insertId: result.insertId,
+            message: result.info
+        };
+    }
+    async executeDelete(query) {
+        const [result] = await this.getPool().execute(query);
+        return {
+            affectedRows: result.affectedRows,
+            message: result.info
+        };
+    }
+    async executeStatement(query) {
+        const [result] = await this.getPool().execute(query);
+        return {
+            success: true,
+            data: result
+        };
+    }
+}

package/dist/db-explorer/index.d.ts

@@ -0,0 +1,5 @@
+export { DbExecutor } from "./db-executor.js";
+export { DbToolGenerator } from "./db-tool-generator.js";
+export type { DbConfig } from "./types.js";
+export * from "./types.js";
+export * from "./drivers/index.js";

package/dist/db-explorer/index.js

@@ -0,0 +1,4 @@
+export { DbExecutor } from "./db-executor.js";
+export { DbToolGenerator } from "./db-tool-generator.js";
+export * from "./types.js";
+export * from "./drivers/index.js";

package/dist/db-explorer/sql-validator.d.ts

@@ -0,0 +1,10 @@
+export declare class SqlValidator {
+    /**
+     * Blocks keywords that are not allowed for a given operation.
+     * Checks case-insensitively and avoids being fooled by keywords inside strings/comments.
+     */
+    static validate(query: string, blockedKeywords: string[]): void;
+    static isSelectOnly(query: string): void;
+    static isUpdateOnly(query: string): void;
+    static isDeleteOnly(query: string): void;
+}

package/dist/db-explorer/sql-validator.js

@@ -0,0 +1,44 @@
+export class SqlValidator {
+    /**
+     * Blocks keywords that are not allowed for a given operation.
+     * Checks case-insensitively and avoids being fooled by keywords inside strings/comments.
+     */
+    static validate(query, blockedKeywords) {
+        if (blockedKeywords.length === 0)
+            return;
+        const queryWithoutComments = query
+            .replace(/\/\*[\s\S]*?\*\/|([^:]|^)\/\/.*|--.*/g, "$1")
+            .trim();
+        const queryWithoutLiterals = queryWithoutComments
+            .replace(/'(?:''|[^'])*'/g, "''")
+            .replace(/"(?:""|[^"])*"/g, '""')
+            .replace(/`(?:``|[^`])*`/g, "``");
+        const tokens = queryWithoutLiterals.toUpperCase().split(/\s+/);
+        for (const keyword of blockedKeywords) {
+            if (tokens.includes(keyword.toUpperCase())) {
+                throw new Error(`Forbidden keyword detected: ${keyword}. Statement blocked for security.`);
+            }
+        }
+    }
+    static isSelectOnly(query) {
+        const q = query.trim().toUpperCase();
+        if (!q.startsWith("SELECT") && !q.startsWith("SHOW") && !q.startsWith("DESCRIBE") && !q.startsWith("EXPLAIN")) {
+            throw new Error("Only read-only queries (SELECT, SHOW, DESCRIBE, EXPLAIN) are allowed.");
+        }
+        this.validate(query, ["INSERT", "UPDATE", "DELETE", "DROP", "ALTER", "TRUNCATE", "REPLACE"]);
+    }
+    static isUpdateOnly(query) {
+        const q = query.trim().toUpperCase();
+        if (!q.startsWith("INSERT") && !q.startsWith("UPDATE") && !q.startsWith("REPLACE")) {
+            throw new Error("Only modification queries (INSERT, UPDATE, REPLACE) are allowed.");
+        }
+        this.validate(query, ["DELETE", "DROP", "ALTER", "TRUNCATE"]);
+    }
+    static isDeleteOnly(query) {
+        const q = query.trim().toUpperCase();
+        if (!q.startsWith("DELETE") && !q.startsWith("TRUNCATE")) {
+            throw new Error("Only removal queries (DELETE, TRUNCATE) are allowed.");
+        }
+        this.validate(query, ["DROP", "ALTER"]);
+    }
+}

package/dist/db-explorer/types.d.ts

@@ -0,0 +1,82 @@
+export interface DbDriver {
+    name: string;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    listTables(): Promise<TableInfo[]>;
+    describeTable(table: string): Promise<ColumnInfo[]>;
+    getTableSchema(table: string): Promise<string>;
+    getRelationships(tables?: string[]): Promise<Relationship[]>;
+    getTableStats(table: string): Promise<TableStats>;
+    sampleRows(table: string, limit?: number): Promise<any[]>;
+    executeQuery(query: string): Promise<QueryResult>;
+    executeUpdate(query: string): Promise<UpdateResult>;
+    executeDelete(query: string): Promise<DeleteResult>;
+    executeStatement(query: string): Promise<StatementResult>;
+}
+export interface DbConfig {
+    driver: 'mysql';
+    host: string;
+    port: number;
+    user: string;
+    password: string;
+    database: string;
+    poolSize?: number;
+    enableRunQuery?: boolean;
+    enableRunUpdateStatement?: boolean;
+    enableRunDeleteStatement?: boolean;
+    enableRunStatement?: boolean;
+}
+export interface TableInfo {
+    name: string;
+    schema: string;
+    type: 'BASE TABLE' | 'VIEW';
+    comment?: string;
+}
+export interface ColumnInfo {
+    name: string;
+    type: string;
+    fullType: string;
+    nullable: boolean;
+    defaultValue?: string | null;
+    isPrimaryKey: boolean;
+    isForeignKey: boolean;
+    isAutoIncrement: boolean;
+    comment?: string;
+    extra?: string;
+    enumValues?: string[];
+    characterMaxLength?: number;
+    numericPrecision?: number;
+    numericScale?: number;
+}
+export interface Relationship {
+    fromTable: string;
+    fromColumn: string;
+    toTable: string;
+    toColumn: string;
+    constraintName: string;
+}
+export interface TableStats {
+    rowCount: number;
+    dataLength?: number;
+    indexLength?: number;
+    createTime?: Date;
+    updateTime?: Date;
+}
+export interface QueryResult {
+    rows: any[];
+    fields?: any[];
+}
+export interface UpdateResult {
+    affectedRows: number;
+    insertId?: number | string;
+    message?: string;
+}
+export interface DeleteResult {
+    affectedRows: number;
+    message?: string;
+}
+export interface StatementResult {
+    success: boolean;
+    message?: string;
+    data?: any;
+}

package/dist/db-explorer/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -1 +1,2 @@
 export { MCPServer } from "./mcp-server.js";
+export * from "./db-explorer/index.js";

package/dist/index.js

@@ -1 +1,2 @@
 export { MCPServer } from "./mcp-server.js";
+export * from "./db-explorer/index.js";

package/dist/mcp-server.d.ts

@@ -1,4 +1,19 @@
 import { AuthContext } from "./api-explorer/auth/index.js";
+import type { DbConfig } from "./db-explorer/index.js";
+/**
+ * The main MCP Server implementation that coordinates the OpenAPI parser,
+ * tool generation, and API execution.
+ *
+ * It registers meta-tools that allow LLMs to:
+ * 1. Discover API structure (tags, endpoints, schemas).
+ * 2. Execute calls to any endpoint with dynamic authentication.
+ * 3. Impersonate users via the set_identity tool.
+ */
+export interface MCPServerOptions {
+    specPath: string;
+    authContext?: AuthContext;
+    dbConfig?: DbConfig;
+}
 /**
  * The main MCP Server implementation that coordinates the OpenAPI parser,
  * tool generation, and API execution.
@@ -9,17 +24,18 @@ import { AuthContext } from "./api-explorer/auth/index.js";
  * 3. Impersonate users via the set_identity tool.
  */
 export declare class MCPServer {
-    private specPath;
     private server;
     private parser;
     private toolGenerator;
     private apiExecutor;
     private authContext;
+    private dbExecutor?;
+    private dbToolGenerator?;
+    private specPath;
     /**
-     * @param specPath - Path to the OpenAPI specification file.
-     * @param authContext - Optional custom AuthContext. If not provided, creates one from environment variables.
+     * @param options - Configuration options for the MCP Server.
      */
-    constructor(specPath: string, authContext?: AuthContext);
+    constructor(options: MCPServerOptions);
     private initParser;
     private registerTools;
     /**

package/dist/mcp-server.js

@@ -5,6 +5,8 @@ import { OpenAPIParser } from "./api-explorer/openapi-parser.js";
 import { ToolGenerator } from "./api-explorer/tool-generator.js";
 import { ApiExecutor } from "./api-explorer/api-executor.js";
 import { createAuthContextFromEnv } from "./api-explorer/auth/index.js";
+import { DbExecutor, DbToolGenerator } from "./db-explorer/index.js";
+import { MySQLDriver } from "./db-explorer/drivers/mysql-driver.js";
 /**
  * The main MCP Server implementation that coordinates the OpenAPI parser,
  * tool generation, and API execution.
@@ -15,22 +17,28 @@ import { createAuthContextFromEnv } from "./api-explorer/auth/index.js";
  * 3. Impersonate users via the set_identity tool.
  */
 export class MCPServer {
-    specPath;
     server;
     parser;
     toolGenerator;
     apiExecutor;
     authContext;
+    dbExecutor;
+    dbToolGenerator;
+    specPath;
     /**
-     * @param specPath - Path to the OpenAPI specification file.
-     * @param authContext - Optional custom AuthContext. If not provided, creates one from environment variables.
+     * @param options - Configuration options for the MCP Server.
      */
-    constructor(specPath, authContext) {
-        this.specPath = specPath;
+    constructor(options) {
+        this.specPath = options.specPath;
         this.parser = new OpenAPIParser();
         this.toolGenerator = new ToolGenerator(this.parser);
-        this.authContext = authContext || createAuthContextFromEnv();
+        this.authContext = options.authContext || createAuthContextFromEnv();
         this.apiExecutor = new ApiExecutor(undefined, this.authContext);
+        if (options.dbConfig) {
+            const driver = new MySQLDriver(options.dbConfig);
+            this.dbExecutor = new DbExecutor(driver, options.dbConfig);
+            this.dbToolGenerator = new DbToolGenerator(this.dbExecutor);
+        }
         this.server = new McpServer({
             name: "project-mcp-server",
             version: "1.0.0",
@@ -40,6 +48,9 @@ export class MCPServer {
         try {
             await this.parser.loadSpec(this.specPath);
             console.error(`Loaded OpenAPI spec from ${this.specPath}`);
+            if (this.dbExecutor) {
+                await this.dbExecutor.connect();
+            }
             this.registerTools();
         }
         catch (error) {
@@ -56,7 +67,7 @@ export class MCPServer {
             }, async (args) => {
                 try {
                     let result;
-                    if (name === "call_endpoint") {
+                    if (name === "api_call_endpoint") {
                         result = await this.apiExecutor.callEndpoint(args);
                     }
                     else {
@@ -74,6 +85,29 @@ export class MCPServer {
                 }
             });
         });
+        if (this.dbToolGenerator) {
+            const dbDefinitions = this.dbToolGenerator.getToolDefinitions();
+            Object.entries(dbDefinitions).forEach(([name, def]) => {
+                const toolDef = def;
+                this.server.registerTool(name, {
+                    description: toolDef.description,
+                    inputSchema: toolDef.inputSchema,
+                }, async (args) => {
+                    try {
+                        const result = await this.dbToolGenerator.handleToolCall(name, args);
+                        return {
+                            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                        };
+                    }
+                    catch (error) {
+                        return {
+                            content: [{ type: "text", text: `Error: ${error.message}` }],
+                            isError: true,
+                        };
+                    }
+                });
+            });
+        }
         this.server.registerTool("set_identity", {
             description: "Set the identity (identifier) for future API requests. Requires an 'identity' auth strategy to be active.",
             inputSchema: z.object({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamp29/project-mcp-server",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "description": "A ModelContextProtocol server to let agents discover your project, such as APIs (using OpenAPI) or other resources.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -29,19 +29,27 @@
       "types": "./dist/api-explorer/index.d.ts",
       "import": "./dist/api-explorer/index.js",
       "default": "./dist/api-explorer/index.js"
+    },
+    "./db-explorer": {
+      "types": "./dist/db-explorer/index.d.ts",
+      "import": "./dist/db-explorer/index.js",
+      "default": "./dist/db-explorer/index.js"
     }
   },
   "scripts": {
     "build": "tsc",
     "start": "node dist/cli.js",
     "dev": "ts-node src/cli.ts",
-    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js"
+    "inspector": "npx @modelcontextprotocol/inspector node dist/cli.js",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "publish": "npm publish --access public"
   },
   "dependencies": {
     "@apidevtools/swagger-parser": "^12.1.0",
     "@modelcontextprotocol/sdk": "^1.25.2",
     "axios": "^1.13.2",
-    "dotenv": "^17.2.3",
+    "dotenv": "^16.4.5",
+    "mysql2": "^3.16.1",
     "openapi-types": "^12.1.3",
     "zod": "^4.3.5"
   },