@channlize/mcp 0.1.0

package/README.md

@@ -0,0 +1,394 @@
+# @channlize/mcp
+
+Model Context Protocol (MCP) server for Channlize - enables AI agents to understand and interact with the Channlize platform.
+
+## Overview
+
+The Channlize MCP server provides AI agents (like Claude) with:
+
+- **Resources**: Documentation, API schemas, and integration guides
+- **Tools**: Ability to submit forms, create chat sessions, and send messages
+- **Prompts**: Templates for common integration patterns
+
+This package can be used both as a standalone MCP server (for Claude Desktop and other MCP clients) or as a library to build custom MCP integrations.
+
+## Installation
+
+```bash
+npm install @channlize/mcp
+```
+
+## Quick Start
+
+### Standalone Server (Claude Desktop)
+
+Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "channlize": {
+      "command": "npx",
+      "args": [
+        "@channlize/mcp",
+        "--api-key",
+        "your-widget-key-here",
+        "--project-id",
+        "your-project-id-here"
+      ]
+    }
+  }
+}
+```
+
+Or using environment variables:
+
+```json
+{
+  "mcpServers": {
+    "channlize": {
+      "command": "npx",
+      "args": ["@channlize/mcp"],
+      "env": {
+        "CHANNLIZE_API_KEY": "your-widget-key-here",
+        "CHANNLIZE_PROJECT_ID": "your-project-id-here",
+        "CHANNLIZE_BASE_URL": "https://api.channlize.com"
+      }
+    }
+  }
+}
+```
+
+### Library Usage
+
+```typescript
+import { ChannlizeMCPServer } from '@channlize/mcp';
+
+const server = new ChannlizeMCPServer({
+  name: 'my-channlize-server',
+  version: '1.0.0',
+  config: {
+    apiKey: process.env.CHANNLIZE_API_KEY!,
+    projectId: process.env.CHANNLIZE_PROJECT_ID,
+    baseUrl: process.env.CHANNLIZE_BASE_URL,
+  },
+});
+
+// Run with stdio transport (for MCP clients)
+await server.runStdio();
+
+// Or get the underlying Server instance for custom transports
+const mcpServer = server.getServer();
+```
+
+## Available Resources
+
+Resources provide read-only context about Channlize:
+
+| URI | Description |
+|-----|-------------|
+| `channlize://schema/contact-form` | JSON schema for contact form data structure |
+| `channlize://schema/chat-session` | JSON schema for chat session data structure |
+| `channlize://docs/api-reference` | Complete Channlize API reference documentation |
+| `channlize://docs/quick-start` | Quick start guide for using Channlize SDK |
+| `channlize://docs/react-components` | Documentation for React components and hooks |
+
+### Example Usage in Claude
+
+```
+Can you show me the contact form schema?
+```
+
+Claude will read the `channlize://schema/contact-form` resource to understand the data structure.
+
+## Available Tools
+
+Tools allow AI agents to interact with Channlize:
+
+### submit_contact_form
+
+Submit a contact form inquiry to Channlize.
+
+**Parameters:**
+- `name` (string, required): Contact's full name
+- `email` (string, required): Contact's email address
+- `message` (string, required): The message content
+- `subject` (string, optional): Subject line
+- `customFields` (object, optional): Additional custom fields
+- `pageUrl` (string, optional): URL where form was submitted
+- `userAgent` (string, optional): User agent string
+
+**Example:**
+```typescript
+{
+  "name": "submit_contact_form",
+  "arguments": {
+    "name": "John Doe",
+    "email": "john@example.com",
+    "message": "I need help with my account",
+    "subject": "Account Support"
+  }
+}
+```
+
+### create_chat_session
+
+Create a new real-time chat session.
+
+**Parameters:**
+- `metadata` (object, optional): Custom session metadata
+
+**Returns:** Session ID and SSE endpoint for real-time updates
+
+### send_message
+
+Send a message in an existing chat session.
+
+**Parameters:**
+- `sessionId` (string, required): The chat session ID
+- `content` (string, required): Message content
+
+### get_chat_messages
+
+Retrieve messages from a chat session.
+
+**Parameters:**
+- `sessionId` (string, required): The chat session ID
+- `limit` (number, optional): Max messages to retrieve (default: 50)
+- `offset` (number, optional): Number of messages to skip (default: 0)
+
+### close_chat_session
+
+Close an active chat session.
+
+**Parameters:**
+- `sessionId` (string, required): The chat session ID to close
+
+## Available Prompts
+
+Prompts provide templates for common integration scenarios:
+
+### integrate-contact-form
+
+Guide for adding a Channlize contact form to a React application.
+
+**Arguments:**
+- `framework` (optional): React framework being used (e.g., Next.js, Vite)
+- `styling` (optional): Styling approach (e.g., Tailwind, CSS Modules)
+
+### setup-live-chat
+
+Guide for implementing the Channlize live chat widget.
+
+**Arguments:**
+- `placement` (optional): Widget placement (e.g., "page", "popup", "sidebar")
+
+### customize-styling
+
+Guide for theming and customizing Channlize components.
+
+### handle-webhooks
+
+Guide for integrating Channlize webhooks into custom workflows.
+
+## CLI Usage
+
+The standalone server can be run directly from the command line:
+
+```bash
+# Using npx
+npx @channlize/mcp --api-key wk_123abc --project-id proj_456def
+
+# Or install globally
+npm install -g @channlize/mcp
+channlize-mcp --api-key wk_123abc --project-id proj_456def
+
+# Using environment variables
+export CHANNLIZE_API_KEY=wk_123abc
+export CHANNLIZE_PROJECT_ID=proj_456def
+channlize-mcp
+```
+
+### CLI Options
+
+```
+--api-key <key>        Channlize API key (widget key) [required]
+--project-id <id>      Channlize project ID
+--base-url <url>       Channlize API base URL (default: https://api.channlize.com)
+--timeout <ms>         Request timeout in milliseconds (default: 10000)
+-h, --help             Show help message
+```
+
+### Environment Variables
+
+- `CHANNLIZE_API_KEY`: Your Channlize widget key
+- `CHANNLIZE_PROJECT_ID`: Your project ID
+- `CHANNLIZE_BASE_URL`: API base URL (optional)
+- `CHANNLIZE_TIMEOUT`: Request timeout in ms (optional)
+
+## Example Interactions
+
+### With Claude Desktop
+
+Once configured, you can ask Claude to:
+
+1. **Learn about Channlize:**
+   - "What is Channlize and how does it work?"
+   - "Show me how to integrate a contact form"
+   - "What's the structure of a chat session?"
+
+2. **Submit forms:**
+   - "Submit a contact form with name 'John Doe', email 'john@example.com', and message 'Need help with billing'"
+
+3. **Manage chat sessions:**
+   - "Create a new chat session"
+   - "Send a message 'Hello!' to session session_123"
+   - "Get messages from session session_123"
+
+4. **Get integration help:**
+   - "Show me how to add a contact form to my Next.js app with Tailwind CSS"
+   - "How do I set up webhooks for Channlize?"
+
+## API Reference
+
+### ChannlizeMCPServer
+
+Main server class for creating MCP servers.
+
+```typescript
+class ChannlizeMCPServer {
+  constructor(options?: MCPServerOptions);
+  
+  setConfig(config: ChannlizeMCPConfig): void;
+  getServer(): Server;
+  runStdio(): Promise<void>;
+  close(): Promise<void>;
+}
+```
+
+### Types
+
+```typescript
+interface ChannlizeMCPConfig {
+  apiKey: string;
+  projectId?: string;
+  baseUrl?: string;
+  timeout?: number;
+}
+
+interface MCPServerOptions {
+  name?: string;
+  version?: string;
+  config?: ChannlizeMCPConfig;
+}
+```
+
+### Helper Functions
+
+```typescript
+// Resources
+function listResources(): Resource[];
+function getResource(uri: string): Resource | undefined;
+
+// Tools
+function listTools(): ToolDefinition[];
+function getTool(name: string): ToolDefinition | undefined;
+
+// Prompts
+function listPrompts(): PromptDefinition[];
+function getPrompt(name: string): PromptDefinition | undefined;
+
+// Factory
+function createMCPServer(options?: MCPServerOptions): ChannlizeMCPServer;
+```
+
+## Custom Integrations
+
+You can build custom MCP integrations using the library:
+
+```typescript
+import { createMCPServer, listTools, listResources } from '@channlize/mcp';
+import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
+
+// Create server with your config
+const server = createMCPServer({
+  config: {
+    apiKey: process.env.CHANNLIZE_API_KEY!,
+    projectId: process.env.CHANNLIZE_PROJECT_ID,
+  },
+});
+
+// Use custom transport (e.g., HTTP + SSE)
+const transport = new SSEServerTransport('/mcp', response);
+await server.getServer().connect(transport);
+
+// List available capabilities
+console.log('Resources:', listResources().map(r => r.uri));
+console.log('Tools:', listTools().map(t => t.name));
+```
+
+## Security
+
+- API keys are required for all tool operations
+- Keys are never exposed in resource responses
+- Webhook signature verification recommended for production
+- Use environment variables for sensitive credentials
+
+## Error Handling
+
+The server handles and reports errors gracefully:
+
+```typescript
+try {
+  await client.submitContactForm(data);
+} catch (error) {
+  // Error details returned to MCP client
+  console.error({
+    success: false,
+    error: error.message,
+    code: error.code,
+    statusCode: error.statusCode,
+  });
+}
+```
+
+## Requirements
+
+- Node.js 18+
+- Valid Channlize API key (widget key)
+- Active Channlize project
+
+## Related Packages
+
+- [@channlize/core](../core) - Core TypeScript SDK
+- [@channlize/react](../react) - React components and hooks
+
+## Contributing
+
+See the main [SDK repository](https://github.com/channlize/sdk) for contribution guidelines.
+
+## License
+
+MIT - see [LICENSE](../../LICENSE) file for details.
+
+## Support
+
+- Documentation: https://docs.channlize.com
+- GitHub Issues: https://github.com/channlize/sdk/issues
+- Email: support@channlize.com
+
+## Changelog
+
+### 0.1.0 (Initial Release)
+
+- MCP server with stdio transport
+- 5 resources (schemas + docs)
+- 5 tools (form submission, chat management)
+- 4 prompts (integration guides)
+- Library and CLI support
+- Full TypeScript support
+
+
+
+
+

package/dist/index.d.mts

@@ -0,0 +1,118 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+export { AuthenticationError, ChannlizeConfig, ChannlizeError, ChatMessage, ChatSession, ContactFormData, CreateChatSessionResponse, CreateContactResponse, FileAttachment, RateLimitError, SendMessageResponse, ValidationError } from '@channlize/core';
+
+/**
+ * MCP-specific types and configuration for Channlize
+ */
+interface ChannlizeMCPConfig {
+    /** Channlize API key (widget key) */
+    apiKey: string;
+    /** Channlize project ID */
+    projectId?: string;
+    /** Base URL for Channlize API */
+    baseUrl?: string;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+}
+interface MCPServerOptions {
+    /** Server name */
+    name?: string;
+    /** Server version */
+    version?: string;
+    /** 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;
+}
+declare function getResource(uri: string): Resource | undefined;
+declare function listResources(): Resource[];
+
+/**
+ * MCP Tools for Channlize
+ * Wraps ChannlizeClient methods for AI agent interaction
+ */
+
+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[];
+
+/**
+ * MCP Prompts for Channlize
+ * Templates for common integration patterns and use cases
+ */
+interface PromptDefinition {
+    name: string;
+    description: string;
+    arguments?: Array<{
+        name: string;
+        description: string;
+        required?: boolean;
+    }>;
+    getPrompt: (args?: Record<string, string>) => string;
+}
+declare function getPrompt(name: string): PromptDefinition | undefined;
+declare function listPrompts(): PromptDefinition[];
+
+/**
+ * @channlize/mcp
+ * Model Context Protocol (MCP) server for Channlize
+ * Enables AI agents to interact with Channlize platform
+ */
+
+/**
+ * Channlize MCP Server
+ * Provides resources, tools, and prompts for AI agents
+ */
+declare class ChannlizeMCPServer {
+    private server;
+    private config?;
+    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
+     */
+    runStdio(): Promise<void>;
+    /**
+     * Close the server
+     */
+    close(): Promise<void>;
+}
+/**
+ * Create and return a new Channlize MCP Server instance
+ */
+declare function createMCPServer(options?: MCPServerOptions): ChannlizeMCPServer;
+
+export { type ChannlizeMCPConfig, ChannlizeMCPServer, type MCPServerOptions, type ResourceContext, type ToolContext, createMCPServer, ChannlizeMCPServer as default, getPrompt, getResource, getTool, listPrompts, listResources, listTools };

package/dist/index.d.ts

@@ -0,0 +1,118 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+export { AuthenticationError, ChannlizeConfig, ChannlizeError, ChatMessage, ChatSession, ContactFormData, CreateChatSessionResponse, CreateContactResponse, FileAttachment, RateLimitError, SendMessageResponse, ValidationError } from '@channlize/core';
+
+/**
+ * MCP-specific types and configuration for Channlize
+ */
+interface ChannlizeMCPConfig {
+    /** Channlize API key (widget key) */
+    apiKey: string;
+    /** Channlize project ID */
+    projectId?: string;
+    /** Base URL for Channlize API */
+    baseUrl?: string;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+}
+interface MCPServerOptions {
+    /** Server name */
+    name?: string;
+    /** Server version */
+    version?: string;
+    /** 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;
+}
+declare function getResource(uri: string): Resource | undefined;
+declare function listResources(): Resource[];
+
+/**
+ * MCP Tools for Channlize
+ * Wraps ChannlizeClient methods for AI agent interaction
+ */
+
+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[];
+
+/**
+ * MCP Prompts for Channlize
+ * Templates for common integration patterns and use cases
+ */
+interface PromptDefinition {
+    name: string;
+    description: string;
+    arguments?: Array<{
+        name: string;
+        description: string;
+        required?: boolean;
+    }>;
+    getPrompt: (args?: Record<string, string>) => string;
+}
+declare function getPrompt(name: string): PromptDefinition | undefined;
+declare function listPrompts(): PromptDefinition[];
+
+/**
+ * @channlize/mcp
+ * Model Context Protocol (MCP) server for Channlize
+ * Enables AI agents to interact with Channlize platform
+ */
+
+/**
+ * Channlize MCP Server
+ * Provides resources, tools, and prompts for AI agents
+ */
+declare class ChannlizeMCPServer {
+    private server;
+    private config?;
+    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
+     */
+    runStdio(): Promise<void>;
+    /**
+     * Close the server
+     */
+    close(): Promise<void>;
+}
+/**
+ * Create and return a new Channlize MCP Server instance
+ */
+declare function createMCPServer(options?: MCPServerOptions): ChannlizeMCPServer;
+
+export { type ChannlizeMCPConfig, ChannlizeMCPServer, type MCPServerOptions, type ResourceContext, type ToolContext, createMCPServer, ChannlizeMCPServer as default, getPrompt, getResource, getTool, listPrompts, listResources, listTools };