@topgunbuild/mcp-server 0.9.0

package/dist/index.d.mts

@@ -0,0 +1,410 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { TopGunClient } from '@topgunbuild/client';
+
+/**
+ * TopGun MCP Server Types
+ */
+
+/**
+ * Configuration for the MCP server
+ */
+interface MCPServerConfig {
+    /**
+     * Name of the MCP server (shown to AI clients)
+     * @default 'topgun-mcp-server'
+     */
+    name?: string;
+    /**
+     * Version of the MCP server
+     * @default '1.0.0'
+     */
+    version?: string;
+    /**
+     * TopGun client instance to use
+     * If not provided, a new client will be created with topgunUrl
+     */
+    client?: TopGunClient;
+    /**
+     * TopGun server URL (WebSocket)
+     * Used when client is not provided
+     * @default 'ws://localhost:8080'
+     */
+    topgunUrl?: string;
+    /**
+     * Authentication token for TopGun server
+     */
+    authToken?: string;
+    /**
+     * Restrict available maps (if not specified, all maps are available)
+     */
+    allowedMaps?: string[];
+    /**
+     * Enable mutation tools (set, remove)
+     * @default true
+     */
+    enableMutations?: boolean;
+    /**
+     * Enable subscription tools
+     * @default true
+     */
+    enableSubscriptions?: boolean;
+    /**
+     * Default limit for query results
+     * @default 10
+     */
+    defaultLimit?: number;
+    /**
+     * Maximum limit for query results
+     * @default 100
+     */
+    maxLimit?: number;
+    /**
+     * Subscription timeout in seconds
+     * @default 60
+     */
+    subscriptionTimeoutSeconds?: number;
+    /**
+     * Enable debug logging
+     * @default false
+     */
+    debug?: boolean;
+}
+/**
+ * Resolved configuration with all defaults applied
+ */
+interface ResolvedMCPServerConfig {
+    name: string;
+    version: string;
+    topgunUrl: string;
+    authToken?: string;
+    allowedMaps?: string[];
+    enableMutations: boolean;
+    enableSubscriptions: boolean;
+    defaultLimit: number;
+    maxLimit: number;
+    subscriptionTimeoutSeconds: number;
+    debug: boolean;
+}
+/**
+ * MCP Tool definition
+ */
+interface MCPTool {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+/**
+ * MCP Tool call result
+ */
+interface MCPToolResult {
+    content: Array<{
+        type: 'text' | 'image' | 'resource';
+        text?: string;
+        data?: string;
+        mimeType?: string;
+    }>;
+    isError?: boolean;
+}
+/**
+ * Query tool arguments
+ */
+interface QueryToolArgs {
+    map: string;
+    filter?: Record<string, unknown>;
+    sort?: {
+        field: string;
+        order: 'asc' | 'desc';
+    };
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Mutate tool arguments
+ */
+interface MutateToolArgs {
+    map: string;
+    operation: 'set' | 'remove';
+    key: string;
+    data?: Record<string, unknown>;
+}
+/**
+ * Search tool arguments
+ */
+interface SearchToolArgs {
+    map: string;
+    query: string;
+    methods?: Array<'exact' | 'fulltext' | 'range'>;
+    limit?: number;
+    minScore?: number;
+}
+/**
+ * Subscribe tool arguments
+ */
+interface SubscribeToolArgs {
+    map: string;
+    filter?: Record<string, unknown>;
+    timeout?: number;
+}
+/**
+ * Schema tool arguments
+ */
+interface SchemaToolArgs {
+    map: string;
+}
+/**
+ * Stats tool arguments
+ */
+interface StatsToolArgs {
+    map?: string;
+}
+/**
+ * Explain tool arguments
+ */
+interface ExplainToolArgs {
+    map: string;
+    filter?: Record<string, unknown>;
+}
+/**
+ * List maps tool arguments (no args required)
+ */
+interface ListMapsToolArgs {
+}
+/**
+ * Tool execution context
+ */
+interface ToolContext {
+    client: TopGunClient;
+    config: ResolvedMCPServerConfig;
+}
+
+/**
+ * TopGun MCP Server
+ *
+ * Model Context Protocol server for TopGun database.
+ * Enables AI assistants (Claude, Cursor) to interact with TopGun data.
+ */
+
+/**
+ * TopGun MCP Server
+ *
+ * Provides MCP protocol interface for AI assistants to interact
+ * with TopGun databases.
+ *
+ * @example
+ * ```typescript
+ * const server = new TopGunMCPServer({
+ *   topgunUrl: 'ws://localhost:8080',
+ *   allowedMaps: ['tasks', 'users'],
+ * });
+ *
+ * await server.start();
+ * ```
+ */
+declare class TopGunMCPServer {
+    private readonly server;
+    private readonly client;
+    private readonly config;
+    private readonly toolContext;
+    private readonly logger;
+    private isStarted;
+    private externalClient;
+    constructor(config?: MCPServerConfig);
+    /**
+     * Register MCP protocol handlers
+     */
+    private registerHandlers;
+    /**
+     * Start the MCP server with stdio transport
+     */
+    start(): Promise<void>;
+    /**
+     * Start the MCP server with a custom transport
+     */
+    startWithTransport(transport: {
+        start(): Promise<void>;
+    }): Promise<void>;
+    /**
+     * Stop the server and cleanup resources
+     */
+    stop(): Promise<void>;
+    /**
+     * Execute a tool directly (for testing)
+     */
+    callTool(name: string, args: unknown): Promise<unknown>;
+    /**
+     * Get the underlying MCP server instance
+     */
+    getServer(): Server;
+    /**
+     * Get the TopGun client instance
+     */
+    getClient(): TopGunClient;
+    /**
+     * Get resolved configuration
+     */
+    getConfig(): ResolvedMCPServerConfig;
+}
+
+/**
+ * HTTP/SSE Transport for MCP Server
+ *
+ * Provides HTTP-based transport for web MCP clients
+ */
+
+/**
+ * HTTP Server configuration
+ */
+interface HTTPServerConfig {
+    /**
+     * Port to listen on
+     * @default 3000
+     */
+    port?: number;
+    /**
+     * Host to bind to
+     * @default '0.0.0.0'
+     */
+    host?: string;
+    /**
+     * CORS allowed origins
+     * @default ['*']
+     */
+    corsOrigins?: string[];
+    /**
+     * Path for MCP endpoint
+     * @default '/mcp'
+     */
+    mcpPath?: string;
+    /**
+     * Path for SSE events
+     * @default '/mcp/events'
+     */
+    eventPath?: string;
+    /**
+     * Enable debug logging
+     * @default false
+     */
+    debug?: boolean;
+}
+/**
+ * HTTP Transport wrapper for MCP Server
+ */
+declare class HTTPTransport {
+    private readonly config;
+    private httpServer?;
+    private isRunning;
+    private activeSessions;
+    constructor(config?: HTTPServerConfig);
+    /**
+     * Start HTTP server with MCP transport
+     */
+    start(mcpServer: TopGunMCPServer): Promise<void>;
+    /**
+     * Stop HTTP server
+     */
+    stop(): Promise<void>;
+    /**
+     * Handle incoming HTTP request
+     */
+    private handleRequest;
+    /**
+     * Handle SSE connection for real-time MCP
+     */
+    private handleSSEConnection;
+    /**
+     * Handle stateless MCP POST request
+     */
+    private handleMCPRequest;
+    /**
+     * Read request body
+     */
+    private readBody;
+    /**
+     * Set CORS headers
+     */
+    private setCorsHeaders;
+    /**
+     * Debug logging
+     */
+    private log;
+    /**
+     * Get current session count
+     */
+    getSessionCount(): number;
+    /**
+     * Check if running
+     */
+    isActive(): boolean;
+}
+/**
+ * Create and start an HTTP transport
+ */
+declare function createHTTPServer(mcpServer: TopGunMCPServer, config?: HTTPServerConfig): Promise<HTTPTransport>;
+
+/**
+ * topgun_query - Query data from a TopGun map with filters
+ */
+
+declare const queryTool: MCPTool;
+
+/**
+ * topgun_mutate - Create, update, or delete data in a TopGun map
+ */
+
+declare const mutateTool: MCPTool;
+
+/**
+ * topgun_search - Perform hybrid search (exact + full-text) across a map
+ */
+
+declare const searchTool: MCPTool;
+
+/**
+ * topgun_subscribe - Watch a map for real-time changes
+ */
+
+declare const subscribeTool: MCPTool;
+
+/**
+ * topgun_schema - Get schema information about a map
+ */
+
+declare const schemaTool: MCPTool;
+
+/**
+ * topgun_stats - Get statistics about TopGun maps
+ */
+
+declare const statsTool: MCPTool;
+
+/**
+ * topgun_explain - Explain how a query would be executed
+ */
+
+declare const explainTool: MCPTool;
+
+/**
+ * topgun_list_maps - List all available maps
+ */
+
+declare const listMapsTool: MCPTool;
+
+/**
+ * MCP Tools Index
+ * Exports all tool definitions and handlers
+ */
+
+/**
+ * All available tools
+ */
+declare const allTools: MCPTool[];
+/**
+ * Tool handlers map
+ */
+declare const toolHandlers: Record<string, (args: unknown, ctx: ToolContext) => Promise<MCPToolResult>>;
+
+export { type ExplainToolArgs, type HTTPServerConfig, HTTPTransport, type ListMapsToolArgs, type MCPServerConfig, type MCPTool, type MCPToolResult, type MutateToolArgs, type QueryToolArgs, type ResolvedMCPServerConfig, type SchemaToolArgs, type SearchToolArgs, type StatsToolArgs, type SubscribeToolArgs, type ToolContext, TopGunMCPServer, allTools, createHTTPServer, explainTool, listMapsTool, mutateTool, queryTool, schemaTool, searchTool, statsTool, subscribeTool, toolHandlers };