MCP Server

The MCP (Model Context Protocol) Server enables AI assistants like Claude Desktop and Cursor to interact with your TopGun database through natural language. Query, mutate, and search your data without writing code.

What is MCP?

MCP (Model Context Protocol) is Anthropic’s open protocol for connecting AI assistants to external data sources. It provides a standardized way for AI tools to:

• Query data from your TopGun maps
• Mutate data (create, update, delete)
• Search using hybrid BM25 + exact matching
• Subscribe to real-time changes
• Inspect schema and statistics

Installation

npm install @topgunbuild/mcp-server
# or
pnpm add @topgunbuild/mcp-server

Claude Desktop Setup

1. Install the MCP server globally:

npm install -g @topgunbuild/mcp-server

2. Configure Claude Desktop by editing ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "topgun": {
      "command": "npx",
      "args": ["@topgunbuild/mcp-server"],
      "env": {
        "TOPGUN_URL": "ws://localhost:8080"
      }
    }
  }
}

3. Restart Claude Desktop

4. Try asking: “Show me all tasks in my TopGun database”

Cursor Setup

Add the following to .cursor/config.json in your workspace:

{
  "mcp": {
    "servers": {
      "topgun": {
        "command": "npx",
        "args": ["@topgunbuild/mcp-server"],
        "env": {
          "TOPGUN_URL": "ws://localhost:8080"
        }
      }
    }
  }
}

Available Tools

The MCP server exposes these tools to AI assistants:

Example Prompts

Once configured, you can use natural language:

• “Show me all tasks with status ‘done’”
• “Create a new task called ‘Review PR #123’ with high priority”
• “Find tasks mentioning authentication”
• “What fields does the users map have?”
• “Watch for new high-priority tasks”

Programmatic Usage

For custom integrations, you can use the server programmatically:

import { TopGunMCPServer } from '@topgunbuild/mcp-server';

const server = new TopGunMCPServer({
  topgunUrl: 'ws://localhost:8080',
  authToken: process.env.TOPGUN_TOKEN,
  allowedMaps: ['tasks', 'users', 'projects'],
  enableMutations: true,
  enableSubscriptions: true,
  defaultLimit: 10,
  maxLimit: 100,
  debug: false,
});

await server.start();

CLI Options

topgun-mcp [options]

Options:
  --url, -u <url>         TopGun server URL (default: ws://localhost:8080)
  --token, -t <token>     Authentication token
  --maps, -m <maps>       Comma-separated list of allowed maps
  --no-mutations          Disable mutation operations
  --no-subscriptions      Disable subscription operations
  --http                  Start HTTP transport instead of stdio
  --port, -p <port>       HTTP port (default: 3000)
  --debug, -d             Enable debug logging
  --help, -h              Show help
  --version, -v           Show version

HTTP Transport

For web-based MCP clients or custom integrations, start the server with HTTP transport:

# Start MCP server with HTTP transport
topgun-mcp --http --port 3000

# With authentication and restricted maps
topgun-mcp --http --port 3000 \
  --url ws://production.example.com:8080 \
  --token $TOPGUN_TOKEN \
  --maps tasks,users \
  --no-mutations

HTTP Endpoints

Configuration Reference

Environment Variables

Security Best Practices

1. Restrict Maps: Use allowedMaps to limit which data the AI can access
2. Read-Only Mode: Set enableMutations: false for read-only access
3. Authentication: Always use auth tokens in production
4. Local Execution: The MCP server runs locally—data never leaves your machine

// Production-safe configuration
const server = new TopGunMCPServer({
  topgunUrl: 'wss://production.example.com',
  authToken: process.env.TOPGUN_TOKEN,
  allowedMaps: ['public-tasks', 'public-users'], // Restrict access
  enableMutations: false, // Read-only
  enableSubscriptions: false,
  maxLimit: 50,
});