dealsmart-mcp-server

Universal data access layer for AI agents, IDEs, and external integrations

Note: This package will migrate to @dealsmartai/mcp-server in a future release. The unscoped name is temporary.

Installation

# npm
npm install dealsmart-mcp-server

# pnpm
pnpm add dealsmart-mcp-server

# yarn
yarn add dealsmart-mcp-server

CLI Usage

# Start in STDIO mode (for IDE integration)
npx dealsmart-mcp-server

# Start HTTP server (for production)
npx dealsmart-mcp-server --http

# Authentication
npx dealsmart-mcp-server login
npx dealsmart-mcp-server logout
npx dealsmart-mcp-server status

Claude Web/Desktop Connector (Zero-Credential Setup)

Connect to DealSmart CRM from Claude Web or Desktop with no OAuth credentials required.

Step 1: Login via CLI

# Production (default)
npx dealsmart-mcp-server login

# Demo environment
npx dealsmart-mcp-server login --env demo

# Dev environment
npx dealsmart-mcp-server login --env dev

# Local development
npx dealsmart-mcp-server login --env local

This opens your browser to authenticate via Clerk. Token is saved to ~/.dealsmart/config.json.

Step 2: Configure Claude Connector

In Claude Web/Desktop → Settings → Custom Connectors, add:

| Field | Production | Demo | Dev | |-------|------------|------|-----| | Name | DealSmart CRM | DealSmart CRM (Demo) | DealSmart CRM (Dev) | | URL | https://mcp.dealsmartai.com | https://mcp-demo.dealsmartai.com | https://mcp-dev.dealsmartai.com | | OAuth Client ID | (leave empty) | (leave empty) | (leave empty) | | OAuth Client Secret | (leave empty) | (leave empty) | (leave empty) |

Environment URLs

| Environment | MCP Server URL | Web Service URL | |-------------|----------------|-----------------| | Production | https://mcp.dealsmartai.com | https://app.dealsmartai.com | | Demo | https://mcp-demo.dealsmartai.com | https://demo.dealsmartai.com | | Dev | https://mcp-dev.dealsmartai.com | https://dev.dealsmartai.com | | Local | http://localhost:8040 | http://localhost:3000 |

How It Works

1. CLI login authenticates you via Clerk and saves a session token locally
2. Claude connector sends requests to the MCP server URL
3. MCP server validates the token from your config file automatically
4. No OAuth secrets needed - the CLI handles all authentication

Claude Code / Cursor Integration

Add to your .mcp.json or MCP configuration:

{
  "mcpServers": {
    "dealsmart": {
      "command": "npx",
      "args": ["dealsmart-mcp-server"],
      "env": {
        "DATABASE_URL": "postgresql://...",
        "CLERK_SECRET_KEY": "..."
      }
    }
  }
}

Development (Monorepo)

Location: apps/ai/mcp-server/ Package: dealsmart-mcp-server

Quick Start

# Build the server
pnpm --filter dealsmart-mcp-server build

# Run STDIO transport (for Claude Code/Cursor)
pnpm --filter dealsmart-mcp-server start:stdio

HTTP Mode (Production)

# Build and run HTTP server
pnpm --filter dealsmart-mcp-server start:http

Available Resources

| Resource | URI Pattern | Description | |----------|-------------|-------------| | Opportunity Context | opportunities://{opportunityId} | Full deal context (customer, vehicles, appointments) | | Customer Profile | customers://{customerId} | Customer data with CCPA compliance flags | | Activity History | activities://{opportunityId} | Last 50 conversation records | | Appointments | appointments://{opportunityId} | Active appointments for opportunity | | Inventory List | inventory://{organizationId} | Top 20 available vehicles | | Inventory by Make | inventory://{organizationId}/make/{make} | Vehicles filtered by make | | Inventory by Make/Model | inventory://{organizationId}/make/{make}/model/{model} | Vehicles filtered by make and model |

Configuration

Environment Variables

# Required
DATABASE_URL="postgresql://user:pass@host:port/db"
PLATFORM_API_KEY="your-api-key-here"

# Optional
MCP_SERVER_PORT=8040          # HTTP transport port (default: 8040)
NODE_ENV=production           # Environment (default: development)

Local Claude Code Integration

Add to your .mcp.json (for local monorepo development):

{
  "mcpServers": {
    "dealsmart": {
      "command": "node",
      "args": ["apps/ai/mcp-server/dist/bin/mcp-server.js"],
      "env": {
        "DATABASE_URL": "postgresql://...",
        "CLERK_SECRET_KEY": "..."
      }
    }
  }
}

Project Structure

apps/ai/mcp-server/
├── src/
│   ├── resources/         # 7 MCP resource handlers
│   ├── transports/        # STDIO + HTTP + Proxy transports
│   ├── auth/              # API key + Clerk authentication
│   ├── core/
│   │   ├── database/      # Drizzle ORM schema (inlined)
│   │   └── context/       # Loaders, builders, types
│   ├── server.ts          # Server factory
│   └── config.ts          # Configuration
├── ARCHITECTURE.md        # Detailed technical docs
└── package.json           # dealsmart-mcp-server

Development Commands

# Build
pnpm --filter dealsmart-mcp-server build

# Type check
pnpm --filter dealsmart-mcp-server check-types

# Lint
pnpm --filter dealsmart-mcp-server lint

# Run STDIO transport
pnpm --filter dealsmart-mcp-server start:stdio

# Run HTTP transport
pnpm --filter dealsmart-mcp-server start:http

# Development mode (with tsx)
pnpm --filter dealsmart-mcp-server dev

Adding a New Resource

1. Create resource handler in src/resources/:

// src/resources/my-resource.ts
import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';

export function registerMyResource(server: McpServer): void {
  server.registerResource(
    'my-resource',
    new ResourceTemplate('myresource://{id}', { list: undefined }),
    {
      title: 'My Resource',
      description: 'Description of what this resource provides',
      mimeType: 'application/json',
    },
    async (uri, params) => {
      const id = params.id as string;
      const data = await loadMyData(id);

      return {
        contents: [{
          uri: uri.href,
          mimeType: 'application/json',
          text: JSON.stringify(data, null, 2),
        }],
      };
    },
  );
}

2. Register in src/resources/index.ts

3. Test locally and rebuild

Documentation

• ARCHITECTURE.md - Detailed technical architecture
• ../docs/MCP_ARCHITECTURE_DECISION.md - Architecture decision record
• ../docs/MCP_EPIC_ANALYSIS.md - Epic analysis and roadmap

Status: Public Release | Version: 0.1.0 | Updated: 2026-01-20