@hellocrossman/mcp-sdk 0.1.2 → 0.3.1

package/README.md

@@ -1,8 +1,8 @@
 # @hellocrossman/mcp-sdk
 
-Turn your Express API into an MCP server with two lines of code.
+Turn your Express API into an MCP server with zero configuration.
 
-Your customers can access your business data and logic through AI assistants (Claude, ChatGPT, Cursor) instead of traditional UIs.
+Auto-discovers your routes, database tables, and generates AI-enhanced tools so your customers can access your business data through AI assistants (Claude, ChatGPT, Cursor).
 
 ## Install
 
@@ -10,7 +10,15 @@ Your customers can access your business data and logic through AI assistants (Cl
 npm install @hellocrossman/mcp-sdk
 ```
 
-## Quick Start
+## Zero-Config Setup
+
+```bash
+npx @hellocrossman/mcp-sdk init
+```
+
+This automatically finds your Express app file, adds the MCP setup, and you're done. Restart your app and visit `/mcp` to see your tools.
+
+## Manual Setup
 
 ```typescript
 import express from 'express';
@@ -21,7 +29,6 @@ const app = express();
 // Your existing routes
 app.get('/api/customers', (req, res) => { /* ... */ });
 app.post('/api/orders', (req, res) => { /* ... */ });
-app.get('/api/orders/:id', (req, res) => { /* ... */ });
 
 // Add MCP in one line
 createMcpServer({ app });
@@ -29,14 +36,55 @@ createMcpServer({ app });
 app.listen(3000);
 ```
 
-That's it. Visit `localhost:3000/mcp` to see your auto-discovered tools.
+## What Gets Discovered
+
+The SDK automatically finds and exposes:
+
+### Express Routes
+Every API route becomes a callable tool:
+
+| HTTP Method | Tool Name Example | Description |
+|---|---|---|
+| GET | `get_customers_by_id` | Fetches a record by ID |
+| POST | `create_orders` | Creates a new record |
+| PUT/PATCH | `update_orders_by_id` | Updates a record |
+| DELETE | `delete_orders_by_id` | Deletes a record |
 
-## How It Works
+### Database Tables
+If `DATABASE_URL` is in your environment (PostgreSQL), the SDK auto-discovers every table and generates tools:
 
-1. **Auto-discovers your routes** -- Reads your Express router and finds all registered API routes
-2. **Generates MCP tools** -- Each route becomes a tool with a name, description, and input schema
-3. **Serves the MCP protocol** -- Creates a `/mcp` endpoint that speaks Streamable HTTP transport
-4. **Calls your actual routes** -- When a tool is invoked, it makes an internal HTTP request to your real endpoint, so all your auth, validation, and middleware still runs
+- **`list_<table>`** -- Query all records with filtering and pagination
+- **`get_<table>_by_id`** -- Fetch a single record by primary key
+
+No extra configuration needed. The SDK detects the database connection from your environment variables automatically.
+
+### Smart Security
+Sensitive tables are **auto-hidden** by default:
+- `users`, `accounts`, `sessions`, `tokens`, `passwords`, `api_keys`, `migrations`
+
+Sensitive columns are redacted in query results:
+- `password`, `password_hash`, `secret`, `api_key`, `access_token`, `credit_card`
+
+### AI-Enhanced Descriptions
+Tool names and descriptions are automatically enriched by AI to be clear and business-oriented. Instead of `list_scans`, you get `browse_scan_history` with a description like "Retrieve all scan records to review analysis results and status."
+
+## Discovery Report
+
+On startup, you'll see a clean summary in your console:
+
+```
+[mcp-sdk] ---- Discovery Report ----
+[mcp-sdk] Express routes: 4 found, 4 tools generated
+[mcp-sdk]   + create_scans (POST /api/scans)
+[mcp-sdk]   + get_scan_details (GET /api/scans/:id)
+[mcp-sdk] Database: 8 tables found, 12 tools generated
+[mcp-sdk]   + list_roadmap_items (DB_QUERY)
+[mcp-sdk]   + get_feature_details (DB_QUERY)
+[mcp-sdk] Auto-hidden (sensitive): users, sessions
+[mcp-sdk] AI enrichment: applied
+[mcp-sdk] Total tools: 16
+[mcp-sdk] ----------------------------
+```
 
 ## Options
 
@@ -44,35 +92,57 @@ That's it. Visit `localhost:3000/mcp` to see your auto-discovered tools.
 createMcpServer({
   app,                              // Your Express app (required)
   path: '/mcp',                     // MCP endpoint path (default: '/mcp')
-  name: 'my-app',                   // Server name shown to AI clients (default: 'mcp-server')
-  version: '1.0.0',                 // Server version (default: '1.0.0')
+  name: 'my-app',                   // Server name shown to AI clients
+  version: '1.0.0',                 // Server version
   description: 'My MCP server',     // Server description
-  routePrefix: '/api',              // Only expose routes starting with this (default: '/api')
-  excludeRoutes: ['/api/admin/*'],  // Hide specific routes (supports * wildcards)
+  routePrefix: '/api',              // Only expose routes starting with this
+  excludeRoutes: ['/api/admin/*'],  // Hide specific routes (supports wildcards)
+  
+  // Database options
+  database: true,                   // Auto-detect database (default: true)
+  excludeTables: ['internal_logs'], // Hide specific tables
+  includeTables: ['products'],      // Only expose these tables (overrides exclude)
+  includeWrites: false,             // Generate create tools for tables (default: false)
+  
+  // AI enrichment
+  enrichment: true,                 // Auto-enrich tool descriptions (default: true)
 });
 ```
 
-## What Gets Exposed
+## Controlling What's Exposed
+
+**Hide specific tables:**
+```typescript
+createMcpServer({ app, excludeTables: ['internal_logs', 'analytics'] });
+```
+
+**Only expose specific tables:**
+```typescript
+createMcpServer({ app, includeTables: ['products', 'orders'] });
+```
+
+**Enable write operations:**
+```typescript
+createMcpServer({ app, includeWrites: true });
+```
 
-| HTTP Method | Tool Prefix | Example Route | Tool Name |
-|---|---|---|---|
-| GET | `get_` | `/api/customers/:id` | `get_customers_by_id` |
-| POST | `create_` | `/api/orders` | `create_orders` |
-| PUT/PATCH | `update_` | `/api/orders/:id` | `update_orders_by_id` |
-| DELETE | `delete_` | `/api/orders/:id` | `delete_orders_by_id` |
+**Disable database discovery:**
+```typescript
+createMcpServer({ app, database: false });
+```
 
 ## Security
 
 - Only routes matching `routePrefix` are exposed (default: `/api`)
-- Use `excludeRoutes` to hide admin or internal endpoints
-- Tool execution goes through your existing Express middleware stack -- auth, rate limiting, validation all still apply
-- No direct database access -- the SDK only calls your routes
+- Sensitive tables are auto-hidden (users, sessions, tokens, migrations, etc.)
+- Sensitive columns are redacted in all query results
+- Database tools are read-only by default (opt-in for writes)
+- Route-based tools go through your existing Express middleware (auth, rate limiting, validation)
+- Use `excludeRoutes` and `excludeTables` for additional control
 
 ## Connecting AI Clients
 
-Once your MCP server is running, AI assistants can connect to it:
-
-**Claude Desktop** -- Add to your MCP settings:
+**Claude Desktop:**
 ```json
 {
   "mcpServers": {
@@ -83,13 +153,14 @@ Once your MCP server is running, AI assistants can connect to it:
 }
 ```
 
-**Cursor** -- Add the MCP server URL in Cursor settings under MCP Servers.
+**Cursor:** Add the MCP server URL in Cursor settings under MCP Servers.
 
 ## Requirements
 
 - Node.js >= 18
 - Express >= 4
 - Zod >= 3
+- pg >= 8 (optional, for database discovery)
 
 ## License
 

package/dist/cjs/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cjs/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":""}