@channlize/mcp 0.1.1 → 0.4.0

package/dist/index.d.mts

@@ -1,17 +1,35 @@
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-export { AuthenticationError, ChannlizeConfig, ChannlizeError, ChatMessage, ChatSession, ContactFormData, CreateChatSessionResponse, CreateContactResponse, FileAttachment, RateLimitError, SendMessageResponse, ValidationError } from '@channlize/core';
+import * as node_http from 'node:http';
+import { McpServer } from '@modelcontextprotocol/server';
+export { AuthenticationError, ChannlizeConfig, ChannlizeError, ChatMessage, ChatSession, ContactFormData, CreateChatSessionResponse, CreateContactResponse, FileAttachment, KeyKind, NotifyResponse, RateLimitError, SendMessageResponse, ValidationError, keyKind } from '@channlize/core';
 
 /**
  * MCP-specific types and configuration for Channlize
  */
 interface ChannlizeMCPConfig {
-    /** Channlize API key (widget key) */
-    apiKey: string;
-    /** Channlize project ID */
+    /**
+     * Server API key (`ch_live_…`) for the project, conversation, contact,
+     * Events and log tools. A `read`-scoped key exposes the read tools; add
+     * the `write` scope to send events and logs and to open conversations.
+     */
+    serverApiKey?: string;
+    /**
+     * Public widget key (`wk_…`), only for the visitor-side tools (contact
+     * form, chat session). Optional.
+     */
+    widgetKey?: string;
+    /**
+     * Either kind of key, detected by its prefix (`wk_` → widget key,
+     * otherwise server key). Fills `serverApiKey` / `widgetKey` when unset.
+     */
+    apiKey?: string;
+    /**
+     * Project ID for Events, logs and project-scoped reads. Defaults to the
+     * first project of the key's organization.
+     */
     projectId?: string;
-    /** Base URL for Channlize API */
+    /** Base URL for the Channlize API (default https://api.channlize.com) */
     baseUrl?: string;
-    /** Request timeout in milliseconds */
+    /** Request timeout in milliseconds (default 10000) */
     timeout?: number;
 }
 interface MCPServerOptions {
@@ -22,98 +40,85 @@ interface MCPServerOptions {
     /** Channlize configuration */
     config?: ChannlizeMCPConfig;
 }
-interface ToolContext {
-    config: ChannlizeMCPConfig;
-}
-interface ResourceContext {
-    config?: ChannlizeMCPConfig;
-}
 
-/**
- * MCP Resources for Channlize
- * Provides read-only context about schemas, API docs, and guides
- */
-interface Resource {
-    uri: string;
-    name: string;
-    description: string;
-    mimeType: string;
-    getText(): string;
+interface HttpServerOptions {
+    /** Interface to bind (default 127.0.0.1). */
+    host?: string;
+    /** Port (default 3333). */
+    port?: number;
+    /** Endpoint path (default /mcp). */
+    path?: string;
 }
-declare function getResource(uri: string): Resource | undefined;
-declare function listResources(): Resource[];
 
+/** A configuration problem the user must fix; the CLI prints it and exits 1. */
+declare class ConfigError extends Error {
+    constructor(message: string);
+}
+interface ResolvedConfig {
+    serverApiKey?: string;
+    widgetKey?: string;
+    projectId?: string;
+    baseUrl: string;
+    timeout: number;
+}
 /**
- * MCP Tools for Channlize
- * Wraps ChannlizeClient methods for AI agent interaction
+ * Normalizes the config: `apiKey` (either kind, detected by prefix) fills
+ * whichever of `serverApiKey` / `widgetKey` is missing, and a key passed in
+ * the wrong slot fails with a message that says which one to use.
  */
-
-interface ToolDefinition {
-    name: string;
-    description: string;
-    inputSchema: {
-        type: 'object';
-        properties: Record<string, any>;
-        required?: string[];
-    };
-    handler: (args: any, context: ToolContext) => Promise<any>;
-}
-declare function getTool(name: string): ToolDefinition | undefined;
-declare function listTools(): ToolDefinition[];
+declare function resolveConfig(config: ChannlizeMCPConfig): ResolvedConfig;
+/** Reads `ChannlizeMCPConfig` from the environment (CLI flags override it). */
+declare function configFromEnv(env?: NodeJS.ProcessEnv): ChannlizeMCPConfig;
 
 /**
- * MCP Prompts for Channlize
- * Templates for common integration patterns and use cases
+ * A failed Channlize call, worded for the model: what went wrong and how
+ * to fix it (wrong key, missing scope, unknown id). Tool handlers throw it
+ * and the MCP server returns it as a tool error (`isError: true`).
  */
-interface PromptDefinition {
-    name: string;
-    description: string;
-    arguments?: Array<{
-        name: string;
-        description: string;
-        required?: boolean;
-    }>;
-    getPrompt: (args?: Record<string, string>) => string;
+declare class ToolError extends Error {
+    statusCode?: number | undefined;
+    code?: string | undefined;
+    constructor(message: string, statusCode?: number | undefined, code?: string | undefined);
 }
-declare function getPrompt(name: string): PromptDefinition | undefined;
-declare function listPrompts(): PromptDefinition[];
+
+declare const VERSION: string;
 
 /**
- * @channlize/mcp
- * Model Context Protocol (MCP) server for Channlize
- * Enables AI agents to interact with Channlize platform
+ * Builds a configured `McpServer` (tools, resources and prompts) without
+ * connecting it. Tools are registered for the keys you pass: server-key
+ * tools for `serverApiKey`, visitor tools for `widgetKey`.
  */
-
+declare function buildServer(config: ChannlizeMCPConfig, info?: {
+    name?: string;
+    version?: string;
+}): McpServer;
 /**
- * Channlize MCP Server
- * Provides resources, tools, and prompts for AI agents
+ * Channlize MCP server. Validates the configuration on construction (a
+ * missing key or a widget key passed as the server key throws
+ * `ConfigError`).
  */
 declare class ChannlizeMCPServer {
     private server;
-    private config?;
+    private readonly config;
+    private readonly info;
     constructor(options?: MCPServerOptions);
-    private setupHandlers;
-    /**
-     * Set or update the Channlize configuration
-     */
-    setConfig(config: ChannlizeMCPConfig): void;
-    /**
-     * Get the underlying MCP server instance
-     */
-    getServer(): Server;
-    /**
-     * Start the server with stdio transport
-     */
+    /** The underlying `McpServer`. */
+    getServer(): McpServer;
+    /** Serve over stdio (what desktop and IDE clients launch). */
     runStdio(): Promise<void>;
     /**
-     * Close the server
+     * Serve Streamable HTTP at `http://<host>:<port>/mcp` (default
+     * 127.0.0.1:3333). Each request gets a fresh server; nothing is shared.
      */
+    runHttp(options?: HttpServerOptions): Promise<{
+        url: string;
+        server: node_http.Server;
+        close: () => Promise<void>;
+    }>;
     close(): Promise<void>;
 }
-/**
- * Create and return a new Channlize MCP Server instance
- */
+/** Create a new Channlize MCP server. */
 declare function createMCPServer(options?: MCPServerOptions): ChannlizeMCPServer;
 
-export { ChannlizeMCPServer, createMCPServer, ChannlizeMCPServer as default, getPrompt, getResource, getTool, listPrompts, listResources, listTools };
-export type { ChannlizeMCPConfig, MCPServerOptions, ResourceContext, ToolContext };
+export { ChannlizeMCPServer, ConfigError, ToolError, VERSION, buildServer, configFromEnv, createMCPServer, ChannlizeMCPServer as default, resolveConfig };
+export type { ChannlizeMCPConfig, HttpServerOptions, MCPServerOptions, ResolvedConfig };

package/dist/index.d.ts

@@ -1,17 +1,35 @@
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-export { AuthenticationError, ChannlizeConfig, ChannlizeError, ChatMessage, ChatSession, ContactFormData, CreateChatSessionResponse, CreateContactResponse, FileAttachment, RateLimitError, SendMessageResponse, ValidationError } from '@channlize/core';
+import * as node_http from 'node:http';
+import { McpServer } from '@modelcontextprotocol/server';
+export { AuthenticationError, ChannlizeConfig, ChannlizeError, ChatMessage, ChatSession, ContactFormData, CreateChatSessionResponse, CreateContactResponse, FileAttachment, KeyKind, NotifyResponse, RateLimitError, SendMessageResponse, ValidationError, keyKind } from '@channlize/core';
 
 /**
  * MCP-specific types and configuration for Channlize
  */
 interface ChannlizeMCPConfig {
-    /** Channlize API key (widget key) */
-    apiKey: string;
-    /** Channlize project ID */
+    /**
+     * Server API key (`ch_live_…`) for the project, conversation, contact,
+     * Events and log tools. A `read`-scoped key exposes the read tools; add
+     * the `write` scope to send events and logs and to open conversations.
+     */
+    serverApiKey?: string;
+    /**
+     * Public widget key (`wk_…`), only for the visitor-side tools (contact
+     * form, chat session). Optional.
+     */
+    widgetKey?: string;
+    /**
+     * Either kind of key, detected by its prefix (`wk_` → widget key,
+     * otherwise server key). Fills `serverApiKey` / `widgetKey` when unset.
+     */
+    apiKey?: string;
+    /**
+     * Project ID for Events, logs and project-scoped reads. Defaults to the
+     * first project of the key's organization.
+     */
     projectId?: string;
-    /** Base URL for Channlize API */
+    /** Base URL for the Channlize API (default https://api.channlize.com) */
     baseUrl?: string;
-    /** Request timeout in milliseconds */
+    /** Request timeout in milliseconds (default 10000) */
     timeout?: number;
 }
 interface MCPServerOptions {
@@ -22,98 +40,85 @@ interface MCPServerOptions {
     /** Channlize configuration */
     config?: ChannlizeMCPConfig;
 }
-interface ToolContext {
-    config: ChannlizeMCPConfig;
-}
-interface ResourceContext {
-    config?: ChannlizeMCPConfig;
-}
 
-/**
- * MCP Resources for Channlize
- * Provides read-only context about schemas, API docs, and guides
- */
-interface Resource {
-    uri: string;
-    name: string;
-    description: string;
-    mimeType: string;
-    getText(): string;
+interface HttpServerOptions {
+    /** Interface to bind (default 127.0.0.1). */
+    host?: string;
+    /** Port (default 3333). */
+    port?: number;
+    /** Endpoint path (default /mcp). */
+    path?: string;
 }
-declare function getResource(uri: string): Resource | undefined;
-declare function listResources(): Resource[];
 
+/** A configuration problem the user must fix; the CLI prints it and exits 1. */
+declare class ConfigError extends Error {
+    constructor(message: string);
+}
+interface ResolvedConfig {
+    serverApiKey?: string;
+    widgetKey?: string;
+    projectId?: string;
+    baseUrl: string;
+    timeout: number;
+}
 /**
- * MCP Tools for Channlize
- * Wraps ChannlizeClient methods for AI agent interaction
+ * Normalizes the config: `apiKey` (either kind, detected by prefix) fills
+ * whichever of `serverApiKey` / `widgetKey` is missing, and a key passed in
+ * the wrong slot fails with a message that says which one to use.
  */
-
-interface ToolDefinition {
-    name: string;
-    description: string;
-    inputSchema: {
-        type: 'object';
-        properties: Record<string, any>;
-        required?: string[];
-    };
-    handler: (args: any, context: ToolContext) => Promise<any>;
-}
-declare function getTool(name: string): ToolDefinition | undefined;
-declare function listTools(): ToolDefinition[];
+declare function resolveConfig(config: ChannlizeMCPConfig): ResolvedConfig;
+/** Reads `ChannlizeMCPConfig` from the environment (CLI flags override it). */
+declare function configFromEnv(env?: NodeJS.ProcessEnv): ChannlizeMCPConfig;
 
 /**
- * MCP Prompts for Channlize
- * Templates for common integration patterns and use cases
+ * A failed Channlize call, worded for the model: what went wrong and how
+ * to fix it (wrong key, missing scope, unknown id). Tool handlers throw it
+ * and the MCP server returns it as a tool error (`isError: true`).
  */
-interface PromptDefinition {
-    name: string;
-    description: string;
-    arguments?: Array<{
-        name: string;
-        description: string;
-        required?: boolean;
-    }>;
-    getPrompt: (args?: Record<string, string>) => string;
+declare class ToolError extends Error {
+    statusCode?: number | undefined;
+    code?: string | undefined;
+    constructor(message: string, statusCode?: number | undefined, code?: string | undefined);
 }
-declare function getPrompt(name: string): PromptDefinition | undefined;
-declare function listPrompts(): PromptDefinition[];
+
+declare const VERSION: string;
 
 /**
- * @channlize/mcp
- * Model Context Protocol (MCP) server for Channlize
- * Enables AI agents to interact with Channlize platform
+ * Builds a configured `McpServer` (tools, resources and prompts) without
+ * connecting it. Tools are registered for the keys you pass: server-key
+ * tools for `serverApiKey`, visitor tools for `widgetKey`.
  */
-
+declare function buildServer(config: ChannlizeMCPConfig, info?: {
+    name?: string;
+    version?: string;
+}): McpServer;
 /**
- * Channlize MCP Server
- * Provides resources, tools, and prompts for AI agents
+ * Channlize MCP server. Validates the configuration on construction (a
+ * missing key or a widget key passed as the server key throws
+ * `ConfigError`).
  */
 declare class ChannlizeMCPServer {
     private server;
-    private config?;
+    private readonly config;
+    private readonly info;
     constructor(options?: MCPServerOptions);
-    private setupHandlers;
-    /**
-     * Set or update the Channlize configuration
-     */
-    setConfig(config: ChannlizeMCPConfig): void;
-    /**
-     * Get the underlying MCP server instance
-     */
-    getServer(): Server;
-    /**
-     * Start the server with stdio transport
-     */
+    /** The underlying `McpServer`. */
+    getServer(): McpServer;
+    /** Serve over stdio (what desktop and IDE clients launch). */
     runStdio(): Promise<void>;
     /**
-     * Close the server
+     * Serve Streamable HTTP at `http://<host>:<port>/mcp` (default
+     * 127.0.0.1:3333). Each request gets a fresh server; nothing is shared.
      */
+    runHttp(options?: HttpServerOptions): Promise<{
+        url: string;
+        server: node_http.Server;
+        close: () => Promise<void>;
+    }>;
     close(): Promise<void>;
 }
-/**
- * Create and return a new Channlize MCP Server instance
- */
+/** Create a new Channlize MCP server. */
 declare function createMCPServer(options?: MCPServerOptions): ChannlizeMCPServer;
 
-export { ChannlizeMCPServer, createMCPServer, ChannlizeMCPServer as default, getPrompt, getResource, getTool, listPrompts, listResources, listTools };
-export type { ChannlizeMCPConfig, MCPServerOptions, ResourceContext, ToolContext };
+export { ChannlizeMCPServer, ConfigError, ToolError, VERSION, buildServer, configFromEnv, createMCPServer, ChannlizeMCPServer as default, resolveConfig };
+export type { ChannlizeMCPConfig, HttpServerOptions, MCPServerOptions, ResolvedConfig };