mcp-server-db2i 1.2.1 → 1.3.1

package/README.md

@@ -1,7 +1,49 @@
 # mcp-server-db2i
 
+[![CI](https://github.com/Strom-Capital/mcp-server-db2i/actions/workflows/ci.yml/badge.svg)](https://github.com/Strom-Capital/mcp-server-db2i/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/mcp-server-db2i)](https://www.npmjs.com/package/mcp-server-db2i)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![MCP](https://img.shields.io/badge/MCP-2025--11--25-green?logo=anthropic&logoColor=white)](https://modelcontextprotocol.io/)
+[![IBM i](https://img.shields.io/badge/IBM%20i-V7R3+-green?logo=ibm&logoColor=white)](https://www.ibm.com/products/ibm-i)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-≥20.6-green?logo=node.js&logoColor=white)](https://nodejs.org/)
+[![Docker](https://img.shields.io/badge/Docker-supported-blue?logo=docker&logoColor=white)](docs/docker.md)
+[![npm downloads](https://img.shields.io/npm/dm/mcp-server-db2i)](https://www.npmjs.com/package/mcp-server-db2i)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/Strom-Capital/mcp-server-db2i/pulls)
+[![GitHub last commit](https://img.shields.io/github/last-commit/Strom-Capital/mcp-server-db2i)](https://github.com/Strom-Capital/mcp-server-db2i/commits/main)
+
 A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for IBM DB2 for i (DB2i). This server enables AI assistants like Claude and Cursor to query and inspect IBM i databases using the JT400 JDBC driver.
 
+## Architecture
+
+AI clients connect to the MCP Server via stdio (IDEs) or HTTP (agents), which executes read-only queries against DB2 for i using the JT400 JDBC driver.
+
+```mermaid
+graph LR
+    subgraph clients ["AI Clients"]
+        claude("Claude")
+        cursor("Cursor IDE")
+        agents("Custom Agents")
+    end
+
+    subgraph server ["MCP Server"]
+        stdio["stdio"]
+        http["HTTP + Auth"]
+        tools[["MCP Tools"]]
+        jdbc["JT400 JDBC"]
+    end
+
+    subgraph ibmi ["IBM i"]
+        db2[("DB2 for i")]
+    end
+
+    claude & cursor -->|MCP Protocol| stdio
+    agents -->|REST API| http
+    stdio & http --> tools
+    tools --> jdbc
+    jdbc -->|JDBC| db2
+```
+
 ## Features
 
 - **Read-only SQL queries** - Execute SELECT statements safely with automatic result limiting
@@ -10,190 +52,37 @@ A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for IB
 - **View inspection** - List and explore database views
 - **Secure by design** - Only SELECT queries allowed, credentials via environment variables
 - **Docker support** - Run as a container for easy deployment
+- **HTTP Transport** - REST API with token authentication for web/agent integration
+- **Dual Transport** - Run stdio and HTTP simultaneously
 
-## Available Tools
+## Quick Start
 
-| Tool | Description |
-|------|-------------|
-| `execute_query` | Execute read-only SELECT queries |
-| `list_schemas` | List schemas/libraries (with optional filter) |
-| `list_tables` | List tables in a schema (with optional filter) |
-| `describe_table` | Get detailed column information |
-| `list_views` | List views in a schema (with optional filter) |
-| `list_indexes` | List SQL indexes for a table |
-| `get_table_constraints` | Get primary keys, foreign keys, unique constraints |
-
-> **Note:** `list_indexes` and `get_table_constraints` query the `QSYS2` SQL catalog views and only return SQL-defined objects. Legacy DDS Logical Files and Physical File constraints are not included. This is standard DB2 for i behavior.
-
-### Filter Syntax
-
-The list tools support pattern matching:
-- `CUST` - Contains "CUST"
-- `CUST*` - Starts with "CUST"
-- `*LOG` - Ends with "LOG"
-- `ORD*FILE` - Starts with "ORD", ends with "FILE"
-
-## Installation
-
-### Prerequisites
-
-- Node.js 18 or higher
-- Java Runtime Environment (JRE) 11 or higher (for JDBC)
-- Access to an IBM i system
-
-### Option 1: npm (recommended)
+### Installation
 
 ```bash
 npm install -g mcp-server-db2i
 ```
 
-### Option 2: From source
-
-```bash
-git clone https://github.com/Strom-Capital/mcp-server-db2i.git
-cd mcp-server-db2i
-npm install
-npm run build
-```
-
-### Option 3: Docker
+Or with Docker:
 
 ```bash
 docker build -t mcp-server-db2i .
 ```
 
-## Configuration
+### Configuration
 
-Create a `.env` file or set environment variables:
+Create a `.env` file with your IBM i credentials:
 
 ```env
-# Required
 DB2I_HOSTNAME=your-ibm-i-host.com
 DB2I_USERNAME=your-username
 DB2I_PASSWORD=your-password
-
-# Optional - Database
-DB2I_PORT=446                              # Default: 446
-DB2I_DATABASE=*LOCAL                       # Default: *LOCAL
-DB2I_SCHEMA=your-default-schema            # Default schema for all tools (can be overridden per-call)
-DB2I_JDBC_OPTIONS=naming=system;date format=iso
-
-# Optional - Logging
-LOG_LEVEL=info                             # debug, info, warn, error, fatal (default: info)
-NODE_ENV=production                        # production = JSON logs, development = pretty logs
-LOG_PRETTY=true                            # Override: force pretty (true) or JSON (false) logs
-LOG_COLORS=true                            # Override: force colors on/off (auto-detected by default)
-
-# Optional - Rate Limiting
-RATE_LIMIT_WINDOW_MS=900000                # Time window in ms (default: 900000 = 15 minutes)
-RATE_LIMIT_MAX_REQUESTS=100                # Max requests per window (default: 100)
-RATE_LIMIT_ENABLED=true                    # Set to 'false' to disable (default: true)
-
-# Optional - Query Limits
-QUERY_DEFAULT_LIMIT=1000                   # Default rows returned (default: 1000)
-QUERY_MAX_LIMIT=10000                      # Maximum rows allowed (default: 10000)
-```
-
-### Environment Variables
-
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `DB2I_HOSTNAME` | Yes | - | IBM i hostname or IP address |
-| `DB2I_USERNAME` | Yes* | - | IBM i user profile |
-| `DB2I_PASSWORD` | Yes* | - | User password |
-| `DB2I_USERNAME_FILE` | No | - | Path to file containing username (overrides `DB2I_USERNAME`) |
-| `DB2I_PASSWORD_FILE` | No | - | Path to file containing password (overrides `DB2I_PASSWORD`) |
-| `DB2I_PORT` | No | `446` | JDBC port (446 is standard for IBM i) |
-| `DB2I_DATABASE` | No | `*LOCAL` | Database name |
-| `DB2I_SCHEMA` | No | - | Default schema/library for tools. If set, you don't need to specify schema in each tool call. |
-| `DB2I_JDBC_OPTIONS` | No | - | Additional JDBC options (semicolon-separated) |
-| `LOG_LEVEL` | No | `info` | Log level: `debug`, `info`, `warn`, `error`, `fatal` |
-| `NODE_ENV` | No | - | Set to `production` for JSON logs, otherwise pretty-printed |
-| `LOG_PRETTY` | No | - | Override log format: `true` = pretty, `false` = JSON |
-| `LOG_COLORS` | No | auto | Override colors: `true`/`false` (auto-detects TTY by default) |
-| `RATE_LIMIT_WINDOW_MS` | No | `900000` | Rate limit time window in milliseconds (15 min) |
-| `RATE_LIMIT_MAX_REQUESTS` | No | `100` | Maximum requests allowed per window |
-| `RATE_LIMIT_ENABLED` | No | `true` | Set to `false` or `0` to disable rate limiting |
-| `QUERY_DEFAULT_LIMIT` | No | `1000` | Default number of rows returned by queries |
-| `QUERY_MAX_LIMIT` | No | `10000` | Maximum rows allowed (caps user-provided limits) |
-
-*Either the environment variable or the corresponding `*_FILE` variable must be set. File-based secrets take priority when both are provided.
-
-### JDBC Options
-
-Common JDBC options for IBM i (JT400/JTOpen driver):
-
-| Option | Values | Description |
-|--------|--------|-------------|
-| `naming` | `system`, `sql` | `system` uses `/` for library separator, `sql` uses `.` for schema separator |
-| `libraries` | `LIB1,LIB2,...` | Library list for resolving unqualified names |
-| `date format` | `iso`, `usa`, `eur`, `jis`, `mdy`, `dmy`, `ymd` | Date format for date fields |
-| `time format` | `iso`, `usa`, `eur`, `jis`, `hms` | Time format for time fields |
-| `errors` | `full`, `basic` | Level of detail in error messages (`full` helps debugging) |
-| `translate binary` | `true`, `false` | Whether to translate binary/CCSID data |
-| `secure` | `true`, `false` | Enable SSL/TLS encryption |
-
-Example: `naming=system;date format=iso;errors=full`
-
-## Usage with Cursor
-
-Add to your Cursor MCP settings (`~/.cursor/mcp.json`):
-
-### Using Docker (recommended)
-
-```json
-{
-  "mcpServers": {
-    "db2i": {
-      "command": "docker",
-      "args": [
-        "run", "-i", "--rm",
-        "-e", "DB2I_HOSTNAME=your-host",
-        "-e", "DB2I_USERNAME=your-user",
-        "-e", "DB2I_PASSWORD=your-password",
-        "mcp-server-db2i:latest"
-      ]
-    }
-  }
-}
-```
-
-### Using Docker with env file
-
-```json
-{
-  "mcpServers": {
-    "db2i": {
-      "command": "docker",
-      "args": [
-        "run", "-i", "--rm",
-        "--env-file", "/path/to/your/.env",
-        "mcp-server-db2i:latest"
-      ]
-    }
-  }
-}
+DB2I_SCHEMA=your-default-schema  # Optional
 ```
 
-### Using docker-compose
+### Client Setup
 
-Create a `.env` file in the project root, then:
-
-```json
-{
-  "mcpServers": {
-    "db2i": {
-      "command": "docker-compose",
-      "args": ["run", "--rm", "mcp-server-db2i"],
-      "cwd": "/path/to/mcp-server-db2i"
-    }
-  }
-}
-```
-
-The `docker-compose.yml` automatically reads from `.env` in the same directory.
-
-### Using npx (after npm install)
+Add to your MCP client config (e.g., `~/.cursor/mcp.json`):
 
 ```json
 {
@@ -202,34 +91,39 @@ The `docker-compose.yml` automatically reads from `.env` in the same directory.
       "command": "npx",
       "args": ["mcp-server-db2i"],
       "env": {
-        "DB2I_HOSTNAME": "your-host",
-        "DB2I_USERNAME": "your-user",
-        "DB2I_PASSWORD": "your-password"
+        "DB2I_HOSTNAME": "${env:DB2I_HOSTNAME}",
+        "DB2I_USERNAME": "${env:DB2I_USERNAME}",
+        "DB2I_PASSWORD": "${env:DB2I_PASSWORD}"
       }
     }
   }
 }
 ```
 
-### Local development
+This uses environment variable expansion to keep credentials out of config files. Set the variables in your shell profile (`~/.zshrc` or `~/.bashrc`).
 
-```json
-{
-  "mcpServers": {
-    "db2i": {
-      "command": "npx",
-      "args": ["tsx", "/path/to/mcp-server-db2i/src/index.ts"],
-      "env": {
-        "DB2I_HOSTNAME": "your-host",
-        "DB2I_USERNAME": "your-user",
-        "DB2I_PASSWORD": "your-password"
-      }
-    }
-  }
-}
-```
+See the [Client Setup Guide](docs/client-setup.md) for Cursor, Claude Desktop, Claude Code, and Docker setup options.
+
+## Available Tools
 
-## Example Queries
+| Tool | Description |
+|------|-------------|
+| `execute_query` | Execute read-only SELECT queries |
+| `list_schemas` | List schemas/libraries (with optional filter) |
+| `list_tables` | List tables in a schema (with optional filter) |
+| `describe_table` | Get detailed column information |
+| `list_views` | List views in a schema (with optional filter) |
+| `list_indexes` | List SQL indexes for a table |
+| `get_table_constraints` | Get primary keys, foreign keys, unique constraints |
+
+### Filter Syntax
+
+The list tools support pattern matching:
+- `CUST` - Contains "CUST"
+- `CUST*` - Starts with "CUST"
+- `*LOG` - Ends with "LOG"
+
+## Example Usage
 
 Once connected, you can ask the AI assistant:
 
@@ -239,141 +133,30 @@ Once connected, you can ask the AI assistant:
 - "What indexes exist on the ORDERS table?"
 - "Run this query: SELECT * FROM MYLIB.CUSTOMERS WHERE STATUS = 'A'"
 
-## Development
-
-```bash
-# Install dependencies
-npm install
-
-# Run in development mode
-npm run dev
-
-# Build for production
-npm run build
-
-# Run production build
-npm start
-
-# Run tests
-npm test
-
-# Run tests in watch mode
-npm run test:watch
-
-# Lint code
-npm run lint
-
-# Lint and fix
-npm run lint:fix
-
-# Type check
-npm run typecheck
-```
-
-## Security
-
-- **Read-only access**: Only SELECT statements are permitted
-- **No credentials in code**: All sensitive data via environment variables or file-based secrets
-- **Query validation**: AST-based SQL parsing plus regex validation blocks dangerous operations
-- **Result limiting**: Default limit of 1000 rows, configurable max limit (default: 10000)
-- **Rate limiting**: Configurable request throttling to prevent abuse (100 req/15 min default)
-- **Structured logging**: Automatic redaction of sensitive fields like passwords
-
-### Rate Limiting
-
-The server includes built-in rate limiting to protect the IBM i database from excessive queries:
-
-- **Default**: 100 requests per 15-minute window
-- **Scope**: Per server instance (for stdio transport, this effectively means per-client since each MCP client spawns its own server process)
-- **Configurable**: Adjust via `RATE_LIMIT_*` environment variables or disable entirely
-
-When the rate limit is exceeded, queries return an error with `waitTimeSeconds` indicating when to retry.
-
-### Credential Management
-
-The server supports multiple methods for providing credentials, listed from most to least secure:
-
-#### Option 1: Docker Secrets (Recommended for Production)
-
-Docker secrets provide the most secure credential management. Secrets are mounted as files and never exposed in environment variables or process listings.
-
-1. Create secret files:
-
-```bash
-mkdir -p ./secrets
-echo "your-username" > ./secrets/db2i_username.txt
-echo "your-password" > ./secrets/db2i_password.txt
-chmod 600 ./secrets/*.txt
-```
-
-2. Configure docker-compose.yml to use secrets:
-
-```yaml
-services:
-  mcp-server-db2i:
-    # ... other config ...
-    environment:
-      - DB2I_HOSTNAME=${DB2I_HOSTNAME}
-      - DB2I_USERNAME_FILE=/run/secrets/db2i_username
-      - DB2I_PASSWORD_FILE=/run/secrets/db2i_password
-    secrets:
-      - db2i_username
-      - db2i_password
-
-secrets:
-  db2i_username:
-    file: ./secrets/db2i_username.txt
-  db2i_password:
-    file: ./secrets/db2i_password.txt
-```
-
-For Docker Swarm or Kubernetes, use their native secret management instead of file-based secrets.
-
-#### Option 2: External Secret Management
-
-For enterprise deployments, integrate with secret management systems:
-
-- **HashiCorp Vault**: Inject secrets at runtime
-- **AWS Secrets Manager**: Use IAM roles for access
-- **Azure Key Vault**: Integrate with managed identities
-
-These systems can populate the `*_FILE` environment variables or inject secrets directly.
-
-#### Option 3: Environment Variables (Development Only)
-
-Plain environment variables are convenient for development but expose credentials through:
-- `docker inspect` output
-- Process listings (`ps aux`)
-- Shell history
-- Log files
-
-```bash
-# .env file (ensure it's in .gitignore)
-DB2I_USERNAME=your-username
-DB2I_PASSWORD=your-password
-```
-
-**Warning**: Never commit `.env` files or credentials to version control.
-
-### File-Based Secret Variables
+## Documentation
 
-| Variable | Description |
-|----------|-------------|
-| `DB2I_USERNAME_FILE` | Path to file containing username (takes priority over `DB2I_USERNAME`) |
-| `DB2I_PASSWORD_FILE` | Path to file containing password (takes priority over `DB2I_PASSWORD`) |
+| Guide | Description |
+|-------|-------------|
+| [HTTP Transport](docs/http-transport.md) | REST API with token authentication |
+| [Configuration](docs/configuration.md) | All environment variables and JDBC options |
+| [Security](docs/security.md) | Credentials, rate limiting, query validation |
+| [Client Setup](docs/client-setup.md) | Cursor, Claude, Claude Code setup |
+| [Docker Guide](docs/docker.md) | Container deployment |
+| [Development](docs/development.md) | Contributing and local setup |
 
 ## Compatibility
 
 - IBM i V7R3 and later (V7R5 recommended)
-- Works with any IBM i system accessible via JDBC over TCP/IP
+- Node.js 20.6 or higher
+- Java Runtime Environment (JRE) 11 or higher
 
 ## Related Projects
 
-- **[IBM ibmi-mcp-server](https://github.com/IBM/ibmi-mcp-server)** - IBM's official MCP server for IBM i systems. Offers YAML-based SQL tool definitions, AI agent frameworks, and production deployment options. Requires [Mapepire](https://mapepire-ibmi.github.io/) to be installed on your IBM i system, but if you can manage that prerequisite, it's worth checking out for more advanced use cases.
+- **[IBM ibmi-mcp-server](https://github.com/IBM/ibmi-mcp-server)** - IBM's official MCP server for IBM i systems. Offers YAML-based SQL tool definitions and AI agent frameworks. Requires [Mapepire](https://mapepire-ibmi.github.io/).
 
 ## Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+Contributions are welcome! See the [Development Guide](docs/development.md) for setup instructions.
 
 ## License
 
@@ -384,4 +167,3 @@ MIT License - see [LICENSE](LICENSE) for details.
 - [node-jt400](https://www.npmjs.com/package/node-jt400) - JT400 JDBC driver wrapper for Node.js
 - [Model Context Protocol](https://modelcontextprotocol.io/) - The protocol specification
 - [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk) - Official TypeScript SDK
-- [IBM ibmi-mcp-server](https://github.com/IBM/ibmi-mcp-server) - SQL security validation patterns inspired by their approach to AST-based query validation

package/dist/auth/authMiddleware.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Authentication Middleware for HTTP Transport
+ *
+ * Express middleware to validate Bearer tokens on protected routes.
+ * Supports multiple authentication modes:
+ * - 'required': Full /auth flow with per-user DB credentials (default)
+ * - 'token': Pre-shared static token, uses env DB credentials
+ * - 'none': No authentication required, uses env DB credentials
+ */
+import type { Request, Response, NextFunction } from 'express';
+import { type AuthMode } from '../config.js';
+import type { TokenSession } from './types.js';
+/**
+ * Extended Express Request with auth context
+ */
+export interface AuthenticatedRequest extends Request {
+    /** The validated token session */
+    tokenSession?: TokenSession;
+    /** The raw token string */
+    authToken?: string;
+}
+/**
+ * Authentication middleware for protected routes
+ *
+ * Behavior depends on MCP_AUTH_MODE:
+ * - 'required': Validates Bearer token from /auth flow, attaches token session
+ * - 'token': Validates Bearer token against static MCP_AUTH_TOKEN
+ * - 'none': Skips authentication entirely
+ *
+ * @example
+ * app.post('/mcp', authMiddleware, (req, res) => {
+ *   const session = (req as AuthenticatedRequest).tokenSession;
+ *   // Use session.config for DB connection (only in 'required' mode)
+ * });
+ */
+export declare function authMiddleware(req: Request, res: Response, next: NextFunction): void;
+/**
+ * Get the current auth mode for use in route handlers
+ */
+export declare function getAuthModeFromConfig(): AuthMode;
+/**
+ * Optional authentication middleware
+ *
+ * Similar to authMiddleware but doesn't require authentication.
+ * If a valid token is provided, attaches the session to the request.
+ * If no token or invalid token, continues without error.
+ *
+ * Useful for endpoints that work with or without authentication.
+ */
+export declare function optionalAuthMiddleware(req: Request, res: Response, next: NextFunction): void;
+/**
+ * Auth rate limiting middleware
+ *
+ * Limits authentication attempts per IP to prevent brute force.
+ * Should be applied to the /auth endpoint.
+ */
+export declare function authRateLimitMiddleware(req: Request, res: Response, next: NextFunction): void;
+/**
+ * Record a failed auth attempt for rate limiting
+ */
+export declare function recordFailedAuthAttempt(req: Request): void;
+/**
+ * Clear rate limit for an IP (on successful auth)
+ */
+export declare function clearAuthRateLimit(req: Request): void;
+//# sourceMappingURL=authMiddleware.d.ts.map

package/dist/auth/authMiddleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authMiddleware.d.ts","sourceRoot":"","sources":["../../src/auth/authMiddleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAI/D,OAAO,EAAiB,KAAK,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAI/C;;GAEG;AACH,MAAM,WAAW,oBAAqB,SAAQ,OAAO;IACnD,kCAAkC;IAClC,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,2BAA2B;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAkBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,YAAY,GACjB,IAAI,CAuGN;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,QAAQ,CAEhD;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,YAAY,GACjB,IAAI,CAeN;AA8BD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,YAAY,GACjB,IAAI,CAwBN;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAa1D;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAGrD"}