npm package: @hellocrossman/mcp-sdk
Description: Turn your Express API into an MCP server with zero configuration. Auto-discovers routes, database tables, and generates AI-enhanced tools.
Author: HelloCrossman
Latest version: 0.4.2

# @hellocrossman/mcp-sdk

Turn your Express API into an MCP server with zero configuration.

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

```bash
npm install @hellocrossman/mcp-sdk
```

## 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';
import { createMcpServer } from '@hellocrossman/mcp-sdk';

const app = express();

// Your existing routes
app.get('/api/customers', (req, res) => { /* ... */ });
app.post('/api/orders', (req, res) => { /* ... */ });

// Add MCP in one line
createMcpServer({ app });

app.listen(3000);
```

## 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 |

### Database Tables
If `DATABASE_URL` is in your environment (PostgreSQL), the SDK auto-discovers every table and generates tools:

- **`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

```typescript
createMcpServer({
  app,                              // Your Express app (required)
  path: '/mcp',                     // MCP endpoint path (default: '/mcp')
  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
  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)
});
```

## 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 });
```

**Disable database discovery:**
```typescript
createMcpServer({ app, database: false });
```

## Security

- Only routes matching `routePrefix` are exposed (default: `/api`)
- 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

**Claude Desktop:**
```json
{
  "mcpServers": {
    "my-app": {
      "url": "https://yourapp.com/mcp"
    }
  }
}
```

**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

MIT