@channlize/mcp 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# @channlize/mcp
+
+## 0.3.0
+
+### Minor Changes
+
+- 7e72a95: Rebuild the MCP server on the official MCP TypeScript SDK v2 (`@modelcontextprotocol/server`, `McpServer.registerTool`), with zod input and output schemas, structured content, tool annotations and clear tool errors.
+
+  - New server-key tools: `get_project`, `get_analytics`, `list_conversations`, `get_conversation`, `create_conversation`, `list_contacts`, `get_contact`, `create_contact`, `list_event_definitions`, `list_event_deliveries`, `query_logs`, `track_log`. `notify_event` now resolves the project from the key when `CHANNLIZE_PROJECT_ID` is unset.
+  - Keys: `CHANNLIZE_SERVER_API_KEY` enables the server tools and `CHANNLIZE_WIDGET_KEY` the visitor tools (contact form, chat). `CHANNLIZE_API_KEY` accepts either key and detects it by prefix. A widget key passed as the server key fails at startup with a clear message. Only tools for the configured keys are listed.
+  - New Streamable HTTP transport (`--transport http`, localhost-only by default, with Host/Origin checks). stdio stays the default.
+  - Rewritten resources (`channlize://project` plus quick-start, React and Events docs) and prompts (`triage-conversations`, `summarize-conversation`, `check-events`, `setup-events`, `setup-live-chat`, `integrate-contact-form`). The `customize-styling` and `handle-webhooks` prompts and the old schema/API-reference resources are removed, since they described APIs that don't exist.
+  - Breaking: requires Node.js 20+. `listTools` / `getTool` / `listResources` / `getPrompt` and `setConfig` are no longer exported; use `buildServer(config)` to get a configured `McpServer`.
+
+## 0.2.0
+
+### Minor Changes
+
+- c113208: Add Events: post a Slack message from your server when something happens.
+
+  - `@channlize/core`: `client.notify(event, data?, { idempotencyKey?, channel? })` and a standalone `createNotifier()` that reads `CHANNLIZE_SERVER_API_KEY` / `CHANNLIZE_API_KEY` and `CHANNLIZE_PROJECT_ID`. Both call `POST /v1/notify` with the server API key (write scope). Event keys and data can be typed with `createNotifier<AppEvents>()` or by augmenting `ChannlizeEvents`. `trackEvent` / `trackServerEvent` are unchanged and now documented as log tracking. Fix: an explicit `baseUrl: undefined` or `timeout: undefined` no longer overrides the defaults.
+  - `@channlize/mcp`: new `notify_event` tool, enabled with `--server-api-key` / `CHANNLIZE_SERVER_API_KEY`.
+  - `@channlize/react`: docs only. `useChannlizeAnalytics().track` is documented as log tracking.
+
+### Patch Changes
+
+- Updated dependencies [c113208]
+  - @channlize/core@0.2.0
+
+## 0.1.1
+
+### Patch Changes
+
+- 9ddf630: Errors thrown by the client now carry the API's human-readable `message`
+  (field messages joined for validation failures) instead of the error code,
+  and `ChannlizeError.code` is set from the API's `error` code.
+
+  `CreateContactResponse` gains the fields the API actually returns:
+  `success`, `conversationId` and `message`. The old `id`, `status` and
+  `slackThreadUrl` fields were never returned and are deprecated. The MCP
+  `submit_contact_form` tool now reports `conversationId`.
+
+- Updated dependencies [9ddf630]
+  - @channlize/core@0.1.0

package/README.md

@@ -1,394 +1,178 @@
 # @channlize/mcp
 
-Model Context Protocol (MCP) server for Channlize - enables AI agents to understand and interact with the Channlize platform.
+[Model Context Protocol](https://modelcontextprotocol.io) server for [Channlize](https://channlize.com). It lets an AI assistant (Claude, Cursor, VS Code Copilot, Windsurf…) read your support inbox, contacts, logs and Events, and send Events to Slack.
 
-## Overview
+- Built on the official MCP TypeScript SDK v2 (`@modelcontextprotocol/server` 2.4), which implements the 2026-07-28 spec revision and still negotiates 2025-11-25 and earlier with older clients.
+- Transports: **stdio** (default) and **Streamable HTTP** (`--transport http`). The deprecated HTTP+SSE transport isn't offered.
+- Requires Node.js 20 or later.
 
-The Channlize MCP server provides AI agents (like Claude) with:
+## Keys
 
-- **Resources**: Documentation, API schemas, and integration guides
-- **Tools**: Ability to submit forms, create chat sessions, and send messages
-- **Prompts**: Templates for common integration patterns
+| Key | Where | Enables |
+| --- | --- | --- |
+| Server API key `ch_live_…` (secret) | `CHANNLIZE_SERVER_API_KEY` | Inbox, contacts, Events and log tools. `read` scope for the read tools, `write` scope to send Events and logs and open conversations or contacts. |
+| Widget key `wk_…` (public, optional) | `CHANNLIZE_WIDGET_KEY` | Visitor-side tools (contact form, chat session), for testing your setup. |
 
-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.
+Create both in the dashboard under **SDK & Integration → API keys**. A read-only key is enough to explore and triage; use a `write` key only if the assistant should post to Slack.
 
-## Installation
+Other settings:
+
+- `CHANNLIZE_PROJECT_ID`: the project for Events and logs. It defaults to the first project of the key's organization.
+- `CHANNLIZE_API_KEY`: either kind of key, detected by its prefix.
+- `CHANNLIZE_BASE_URL`: default `https://api.channlize.com`.
+- `CHANNLIZE_TIMEOUT`: in ms, default 10000.
+
+Each one has a matching flag (`--server-api-key`, `--widget-key`, `--project-id`, …); run `npx -y @channlize/mcp --help` to list them.
+
+## Setup
+
+### Claude Code
 
 ```bash
-npm install @channlize/mcp
+claude mcp add channlize \
+  --env CHANNLIZE_SERVER_API_KEY=ch_live_… \
+  --env CHANNLIZE_PROJECT_ID=<project-id> \
+  -- npx -y @channlize/mcp
 ```
 
-## Quick Start
+Add `--scope user` to use it in every project. Check it with `claude mcp list`, or `/mcp` inside Claude Code.
 
-### Standalone Server (Claude Desktop)
+### Claude Desktop
 
-Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+Edit `claude_desktop_config.json`:
 
-```json
-{
-  "mcpServers": {
-    "channlize": {
-      "command": "npx",
-      "args": [
-        "@channlize/mcp",
-        "--api-key",
-        "your-widget-key-here",
-        "--project-id",
-        "your-project-id-here"
-      ]
-    }
-  }
-}
-```
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
 
-Or using environment variables:
+Then restart Claude.
 
 ```json
 {
   "mcpServers": {
     "channlize": {
       "command": "npx",
-      "args": ["@channlize/mcp"],
+      "args": ["-y", "@channlize/mcp"],
       "env": {
-        "CHANNLIZE_API_KEY": "your-widget-key-here",
-        "CHANNLIZE_PROJECT_ID": "your-project-id-here",
-        "CHANNLIZE_BASE_URL": "https://api.channlize.com"
+        "CHANNLIZE_SERVER_API_KEY": "ch_live_…",
+        "CHANNLIZE_PROJECT_ID": "<project-id>"
       }
     }
   }
 }
 ```
 
-### 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?
-```
+### Cursor
 
-Claude will read the `channlize://schema/contact-form` resource to understand the data structure.
+Use `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project), with the same `mcpServers` block as Claude Desktop.
 
-## Available Tools
+### VS Code (GitHub Copilot agent mode)
 
-Tools allow AI agents to interact with Channlize:
+In `.vscode/mcp.json`, VS Code prompts for the key once and stores it securely:
 
-### 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
+```json
 {
-  "name": "submit_contact_form",
-  "arguments": {
-    "name": "John Doe",
-    "email": "john@example.com",
-    "message": "I need help with my account",
-    "subject": "Account Support"
+  "inputs": [
+    {
+      "type": "promptString",
+      "id": "channlize-key",
+      "description": "Channlize server API key (ch_live_…)",
+      "password": true
+    }
+  ],
+  "servers": {
+    "channlize": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@channlize/mcp"],
+      "env": {
+        "CHANNLIZE_SERVER_API_KEY": "${input:channlize-key}",
+        "CHANNLIZE_PROJECT_ID": "<project-id>"
+      }
+    }
   }
 }
 ```
 
-### 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.
+### Windsurf
 
-**Arguments:**
-- `framework` (optional): React framework being used (e.g., Next.js, Vite)
-- `styling` (optional): Styling approach (e.g., Tailwind, CSS Modules)
+Use `~/.codeium/windsurf/mcp_config.json`, with the same `mcpServers` block as Claude Desktop.
 
-### setup-live-chat
+### Streamable HTTP
 
-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:
+For clients that connect over HTTP:
 
 ```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
+CHANNLIZE_SERVER_API_KEY=ch_live_… npx -y @channlize/mcp --transport http --port 3333
+# → http://127.0.0.1:3333/mcp
 ```
 
-### Environment Variables
+It binds to `127.0.0.1` by default and rejects requests whose `Host` or `Origin` isn't localhost, which guards against DNS rebinding. Anyone who can reach the port acts with your key, so don't expose it on a public interface.
 
-- `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)
+## Tools
 
-## Example Interactions
+Server API key:
 
-### With Claude Desktop
+| Tool | Scope | What it does |
+| --- | --- | --- |
+| `get_project` | any | Project name and ID, totals, the key's permissions, Slack connection |
+| `get_analytics` | any | Daily conversations and messages for the last 30 days |
+| `list_conversations` | read | Recent conversations, filtered by status or priority |
+| `get_conversation` | read | One conversation with its message thread |
+| `create_conversation` | write | Open a conversation for a customer (posted to Slack) |
+| `list_contacts` | read | Customers, paginated |
+| `get_contact` | read | One customer |
+| `create_contact` | write | Find or create a customer by email |
+| `notify_event` | write | Post an Event to Slack (`user.subscribed`…), idempotent with a key |
+| `list_event_definitions` | read | Events set up on the project, including drafts |
+| `list_event_deliveries` | read | Recent Event deliveries with status and skip/fail reason |
+| `query_logs` | read | Search log tracking by severity, source, text and time |
+| `track_log` | write | Record a log line |
 
-Once configured, you can ask Claude to:
+Widget key (visitor side): `submit_contact_form`, `create_chat_session`, `send_message`, `get_chat_messages` and `close_chat_session`.
 
-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?"
+Each tool declares input and output schemas and annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`), and returns `structuredContent`. Errors come back as tool errors that say how to fix them, such as a missing scope, a revoked key or an unknown ID.
 
-2. **Submit forms:**
-   - "Submit a contact form with name 'John Doe', email 'john@example.com', and message 'Need help with billing'"
+You can't reply to a conversation or change its status or priority through the API yet. The team does that in the Slack thread or the dashboard.
 
-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;
-}
-```
+## Resources and prompts
 
-### Helper Functions
+Resources:
 
-```typescript
-// Resources
-function listResources(): Resource[];
-function getResource(uri: string): Resource | undefined;
+- `channlize://project`: the live project, as JSON.
+- `channlize://docs/quick-start`
+- `channlize://docs/react-components`
+- `channlize://docs/events`
 
-// Tools
-function listTools(): ToolDefinition[];
-function getTool(name: string): ToolDefinition | undefined;
+Prompts:
 
-// Prompts
-function listPrompts(): PromptDefinition[];
-function getPrompt(name: string): PromptDefinition | undefined;
+- `triage-conversations`: rank open conversations and draft replies.
+- `summarize-conversation`
+- `check-events`: explain skipped or failed deliveries.
+- `setup-events`, `setup-live-chat`, `integrate-contact-form`: add Channlize to the codebase you're working in.
 
-// Factory
-function createMCPServer(options?: MCPServerOptions): ChannlizeMCPServer;
-```
+## Troubleshooting
 
-## Custom Integrations
+- **"A Channlize key is required"**: set `CHANNLIZE_SERVER_API_KEY` in the client's `env` block, then restart the client.
+- **"holds a widget key (wk_…)"**: you passed the public widget key as the server key. Create a server API key, or pass the widget key as `CHANNLIZE_WIDGET_KEY`.
+- **401 invalid key**: the key was revoked, has expired or was mistyped. Create a new one.
+- **403 lacks required permission**: the key is read-only. Create a key with the `write` scope for `notify_event`, `track_log`, `create_conversation` and `create_contact`.
+- **404 project not found**: `CHANNLIZE_PROJECT_ID` is wrong, or belongs to another organization.
+- **The server doesn't start**: check `node --version` (20+) and run `npx -y @channlize/mcp --help`. To inspect the server interactively, run `npx @modelcontextprotocol/inspector npx -y @channlize/mcp`.
 
-You can build custom MCP integrations using the library:
+## Programmatic use
 
-```typescript
-import { createMCPServer, listTools, listResources } from '@channlize/mcp';
-import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
+```ts
+import { ChannlizeMCPServer, buildServer } from '@channlize/mcp';
 
-// Create server with your config
-const server = createMCPServer({
-  config: {
-    apiKey: process.env.CHANNLIZE_API_KEY!,
-    projectId: process.env.CHANNLIZE_PROJECT_ID,
-  },
+const server = new ChannlizeMCPServer({
+  config: { serverApiKey: process.env.CHANNLIZE_SERVER_API_KEY },
 });
+await server.runStdio(); // or: await server.runHttp({ port: 3333 })
 
-// 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));
+// Or get a configured McpServer for your own transport:
+const mcp = buildServer({ serverApiKey: '…' });
 ```
 
-## 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
-
-
-
-
-
+MIT