@channlize/mcp 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. package/CHANGELOG.md +44 -0
  2. package/README.md +112 -328
  3. package/dist/index.d.mts +86 -77
  4. package/dist/index.d.ts +86 -77
  5. package/dist/index.js +1094 -1599
  6. package/dist/index.js.map +1 -1
  7. package/dist/index.mjs +1084 -1601
  8. package/dist/index.mjs.map +1 -1
  9. package/dist/server.js +1202 -1704
  10. package/dist/server.js.map +1 -1
  11. package/package.json +18 -14
package/dist/index.d.mts CHANGED
@@ -1,17 +1,35 @@
1
- import { Server } from '@modelcontextprotocol/sdk/server/index.js';
2
- export { AuthenticationError, ChannlizeConfig, ChannlizeError, ChatMessage, ChatSession, ContactFormData, CreateChatSessionResponse, CreateContactResponse, FileAttachment, RateLimitError, SendMessageResponse, ValidationError } from '@channlize/core';
1
+ import * as node_http from 'node:http';
2
+ import { McpServer } from '@modelcontextprotocol/server';
3
+ export { AuthenticationError, ChannlizeConfig, ChannlizeError, ChatMessage, ChatSession, ContactFormData, CreateChatSessionResponse, CreateContactResponse, FileAttachment, NotifyResponse, RateLimitError, SendMessageResponse, ValidationError } from '@channlize/core';
3
4
 
4
5
  /**
5
6
  * MCP-specific types and configuration for Channlize
6
7
  */
7
8
  interface ChannlizeMCPConfig {
8
- /** Channlize API key (widget key) */
9
- apiKey: string;
10
- /** Channlize project ID */
9
+ /**
10
+ * Server API key (`ch_live_…`) for the project, conversation, contact,
11
+ * Events and log tools. A `read`-scoped key exposes the read tools; add
12
+ * the `write` scope to send events and logs and to open conversations.
13
+ */
14
+ serverApiKey?: string;
15
+ /**
16
+ * Public widget key (`wk_…`), only for the visitor-side tools (contact
17
+ * form, chat session). Optional.
18
+ */
19
+ widgetKey?: string;
20
+ /**
21
+ * Either kind of key, detected by its prefix (`wk_` → widget key,
22
+ * otherwise server key). Fills `serverApiKey` / `widgetKey` when unset.
23
+ */
24
+ apiKey?: string;
25
+ /**
26
+ * Project ID for Events, logs and project-scoped reads. Defaults to the
27
+ * first project of the key's organization.
28
+ */
11
29
  projectId?: string;
12
- /** Base URL for Channlize API */
30
+ /** Base URL for the Channlize API (default https://api.channlize.com) */
13
31
  baseUrl?: string;
14
- /** Request timeout in milliseconds */
32
+ /** Request timeout in milliseconds (default 10000) */
15
33
  timeout?: number;
16
34
  }
17
35
  interface MCPServerOptions {
@@ -22,97 +40,88 @@ interface MCPServerOptions {
22
40
  /** Channlize configuration */
23
41
  config?: ChannlizeMCPConfig;
24
42
  }
25
- interface ToolContext {
26
- config: ChannlizeMCPConfig;
27
- }
28
- interface ResourceContext {
29
- config?: ChannlizeMCPConfig;
30
- }
31
43
 
32
- /**
33
- * MCP Resources for Channlize
34
- * Provides read-only context about schemas, API docs, and guides
35
- */
36
- interface Resource {
37
- uri: string;
38
- name: string;
39
- description: string;
40
- mimeType: string;
41
- getText(): string;
44
+ interface HttpServerOptions {
45
+ /** Interface to bind (default 127.0.0.1). */
46
+ host?: string;
47
+ /** Port (default 3333). */
48
+ port?: number;
49
+ /** Endpoint path (default /mcp). */
50
+ path?: string;
42
51
  }
43
- declare function getResource(uri: string): Resource | undefined;
44
- declare function listResources(): Resource[];
45
52
 
53
+ /** A configuration problem the user must fix; the CLI prints it and exits 1. */
54
+ declare class ConfigError extends Error {
55
+ constructor(message: string);
56
+ }
57
+ type KeyKind = 'widget' | 'server';
58
+ /** `wk_…` is the public widget key; anything else is a server API key (`ch_live_…`). */
59
+ declare function keyKind(key: string): KeyKind;
60
+ interface ResolvedConfig {
61
+ serverApiKey?: string;
62
+ widgetKey?: string;
63
+ projectId?: string;
64
+ baseUrl: string;
65
+ timeout: number;
66
+ }
46
67
  /**
47
- * MCP Tools for Channlize
48
- * Wraps ChannlizeClient methods for AI agent interaction
68
+ * Normalizes the config: `apiKey` (either kind, detected by prefix) fills
69
+ * whichever of `serverApiKey` / `widgetKey` is missing, and a key passed in
70
+ * the wrong slot fails with a message that says which one to use.
49
71
  */
50
-
51
- interface ToolDefinition {
52
- name: string;
53
- description: string;
54
- inputSchema: {
55
- type: 'object';
56
- properties: Record<string, any>;
57
- required?: string[];
58
- };
59
- handler: (args: any, context: ToolContext) => Promise<any>;
60
- }
61
- declare function getTool(name: string): ToolDefinition | undefined;
62
- declare function listTools(): ToolDefinition[];
72
+ declare function resolveConfig(config: ChannlizeMCPConfig): ResolvedConfig;
73
+ /** Reads `ChannlizeMCPConfig` from the environment (CLI flags override it). */
74
+ declare function configFromEnv(env?: NodeJS.ProcessEnv): ChannlizeMCPConfig;
63
75
 
64
76
  /**
65
- * MCP Prompts for Channlize
66
- * Templates for common integration patterns and use cases
77
+ * A failed Channlize call, worded for the model: what went wrong and how
78
+ * to fix it (wrong key, missing scope, unknown id). Tool handlers throw it
79
+ * and the MCP server returns it as a tool error (`isError: true`).
67
80
  */
68
- interface PromptDefinition {
69
- name: string;
70
- description: string;
71
- arguments?: Array<{
72
- name: string;
73
- description: string;
74
- required?: boolean;
75
- }>;
76
- getPrompt: (args?: Record<string, string>) => string;
81
+ declare class ToolError extends Error {
82
+ statusCode?: number | undefined;
83
+ code?: string | undefined;
84
+ constructor(message: string, statusCode?: number | undefined, code?: string | undefined);
77
85
  }
78
- declare function getPrompt(name: string): PromptDefinition | undefined;
79
- declare function listPrompts(): PromptDefinition[];
86
+
87
+ declare const VERSION: string;
80
88
 
81
89
  /**
82
- * @channlize/mcp
83
- * Model Context Protocol (MCP) server for Channlize
84
- * Enables AI agents to interact with Channlize platform
90
+ * Builds a configured `McpServer` (tools, resources and prompts) without
91
+ * connecting it. Tools are registered for the keys you pass: server-key
92
+ * tools for `serverApiKey`, visitor tools for `widgetKey`.
85
93
  */
86
-
94
+ declare function buildServer(config: ChannlizeMCPConfig, info?: {
95
+ name?: string;
96
+ version?: string;
97
+ }): McpServer;
87
98
  /**
88
- * Channlize MCP Server
89
- * Provides resources, tools, and prompts for AI agents
99
+ * Channlize MCP server. Validates the configuration on construction (a
100
+ * missing key or a widget key passed as the server key throws
101
+ * `ConfigError`).
90
102
  */
91
103
  declare class ChannlizeMCPServer {
92
104
  private server;
93
- private config?;
105
+ private readonly config;
106
+ private readonly info;
94
107
  constructor(options?: MCPServerOptions);
95
- private setupHandlers;
96
- /**
97
- * Set or update the Channlize configuration
98
- */
99
- setConfig(config: ChannlizeMCPConfig): void;
100
- /**
101
- * Get the underlying MCP server instance
102
- */
103
- getServer(): Server;
104
- /**
105
- * Start the server with stdio transport
106
- */
108
+ /** The underlying `McpServer`. */
109
+ getServer(): McpServer;
110
+ /** Serve over stdio (what desktop and IDE clients launch). */
107
111
  runStdio(): Promise<void>;
108
112
  /**
109
- * Close the server
113
+ * Serve Streamable HTTP at `http://<host>:<port>/mcp` (default
114
+ * 127.0.0.1:3333). Each request gets a fresh server; nothing is shared.
110
115
  */
116
+ runHttp(options?: HttpServerOptions): Promise<{
117
+ url: string;
118
+ server: node_http.Server;
119
+ close: () => Promise<void>;
120
+ }>;
111
121
  close(): Promise<void>;
112
122
  }
113
- /**
114
- * Create and return a new Channlize MCP Server instance
115
- */
123
+ /** Create a new Channlize MCP server. */
116
124
  declare function createMCPServer(options?: MCPServerOptions): ChannlizeMCPServer;
117
125
 
118
- export { type ChannlizeMCPConfig, ChannlizeMCPServer, type MCPServerOptions, type ResourceContext, type ToolContext, createMCPServer, ChannlizeMCPServer as default, getPrompt, getResource, getTool, listPrompts, listResources, listTools };
126
+ export { ChannlizeMCPServer, ConfigError, ToolError, VERSION, buildServer, configFromEnv, createMCPServer, ChannlizeMCPServer as default, keyKind, resolveConfig };
127
+ export type { ChannlizeMCPConfig, HttpServerOptions, KeyKind, MCPServerOptions, ResolvedConfig };
package/dist/index.d.ts CHANGED
@@ -1,17 +1,35 @@
1
- import { Server } from '@modelcontextprotocol/sdk/server/index.js';
2
- export { AuthenticationError, ChannlizeConfig, ChannlizeError, ChatMessage, ChatSession, ContactFormData, CreateChatSessionResponse, CreateContactResponse, FileAttachment, RateLimitError, SendMessageResponse, ValidationError } from '@channlize/core';
1
+ import * as node_http from 'node:http';
2
+ import { McpServer } from '@modelcontextprotocol/server';
3
+ export { AuthenticationError, ChannlizeConfig, ChannlizeError, ChatMessage, ChatSession, ContactFormData, CreateChatSessionResponse, CreateContactResponse, FileAttachment, NotifyResponse, RateLimitError, SendMessageResponse, ValidationError } from '@channlize/core';
3
4
 
4
5
  /**
5
6
  * MCP-specific types and configuration for Channlize
6
7
  */
7
8
  interface ChannlizeMCPConfig {
8
- /** Channlize API key (widget key) */
9
- apiKey: string;
10
- /** Channlize project ID */
9
+ /**
10
+ * Server API key (`ch_live_…`) for the project, conversation, contact,
11
+ * Events and log tools. A `read`-scoped key exposes the read tools; add
12
+ * the `write` scope to send events and logs and to open conversations.
13
+ */
14
+ serverApiKey?: string;
15
+ /**
16
+ * Public widget key (`wk_…`), only for the visitor-side tools (contact
17
+ * form, chat session). Optional.
18
+ */
19
+ widgetKey?: string;
20
+ /**
21
+ * Either kind of key, detected by its prefix (`wk_` → widget key,
22
+ * otherwise server key). Fills `serverApiKey` / `widgetKey` when unset.
23
+ */
24
+ apiKey?: string;
25
+ /**
26
+ * Project ID for Events, logs and project-scoped reads. Defaults to the
27
+ * first project of the key's organization.
28
+ */
11
29
  projectId?: string;
12
- /** Base URL for Channlize API */
30
+ /** Base URL for the Channlize API (default https://api.channlize.com) */
13
31
  baseUrl?: string;
14
- /** Request timeout in milliseconds */
32
+ /** Request timeout in milliseconds (default 10000) */
15
33
  timeout?: number;
16
34
  }
17
35
  interface MCPServerOptions {
@@ -22,97 +40,88 @@ interface MCPServerOptions {
22
40
  /** Channlize configuration */
23
41
  config?: ChannlizeMCPConfig;
24
42
  }
25
- interface ToolContext {
26
- config: ChannlizeMCPConfig;
27
- }
28
- interface ResourceContext {
29
- config?: ChannlizeMCPConfig;
30
- }
31
43
 
32
- /**
33
- * MCP Resources for Channlize
34
- * Provides read-only context about schemas, API docs, and guides
35
- */
36
- interface Resource {
37
- uri: string;
38
- name: string;
39
- description: string;
40
- mimeType: string;
41
- getText(): string;
44
+ interface HttpServerOptions {
45
+ /** Interface to bind (default 127.0.0.1). */
46
+ host?: string;
47
+ /** Port (default 3333). */
48
+ port?: number;
49
+ /** Endpoint path (default /mcp). */
50
+ path?: string;
42
51
  }
43
- declare function getResource(uri: string): Resource | undefined;
44
- declare function listResources(): Resource[];
45
52
 
53
+ /** A configuration problem the user must fix; the CLI prints it and exits 1. */
54
+ declare class ConfigError extends Error {
55
+ constructor(message: string);
56
+ }
57
+ type KeyKind = 'widget' | 'server';
58
+ /** `wk_…` is the public widget key; anything else is a server API key (`ch_live_…`). */
59
+ declare function keyKind(key: string): KeyKind;
60
+ interface ResolvedConfig {
61
+ serverApiKey?: string;
62
+ widgetKey?: string;
63
+ projectId?: string;
64
+ baseUrl: string;
65
+ timeout: number;
66
+ }
46
67
  /**
47
- * MCP Tools for Channlize
48
- * Wraps ChannlizeClient methods for AI agent interaction
68
+ * Normalizes the config: `apiKey` (either kind, detected by prefix) fills
69
+ * whichever of `serverApiKey` / `widgetKey` is missing, and a key passed in
70
+ * the wrong slot fails with a message that says which one to use.
49
71
  */
50
-
51
- interface ToolDefinition {
52
- name: string;
53
- description: string;
54
- inputSchema: {
55
- type: 'object';
56
- properties: Record<string, any>;
57
- required?: string[];
58
- };
59
- handler: (args: any, context: ToolContext) => Promise<any>;
60
- }
61
- declare function getTool(name: string): ToolDefinition | undefined;
62
- declare function listTools(): ToolDefinition[];
72
+ declare function resolveConfig(config: ChannlizeMCPConfig): ResolvedConfig;
73
+ /** Reads `ChannlizeMCPConfig` from the environment (CLI flags override it). */
74
+ declare function configFromEnv(env?: NodeJS.ProcessEnv): ChannlizeMCPConfig;
63
75
 
64
76
  /**
65
- * MCP Prompts for Channlize
66
- * Templates for common integration patterns and use cases
77
+ * A failed Channlize call, worded for the model: what went wrong and how
78
+ * to fix it (wrong key, missing scope, unknown id). Tool handlers throw it
79
+ * and the MCP server returns it as a tool error (`isError: true`).
67
80
  */
68
- interface PromptDefinition {
69
- name: string;
70
- description: string;
71
- arguments?: Array<{
72
- name: string;
73
- description: string;
74
- required?: boolean;
75
- }>;
76
- getPrompt: (args?: Record<string, string>) => string;
81
+ declare class ToolError extends Error {
82
+ statusCode?: number | undefined;
83
+ code?: string | undefined;
84
+ constructor(message: string, statusCode?: number | undefined, code?: string | undefined);
77
85
  }
78
- declare function getPrompt(name: string): PromptDefinition | undefined;
79
- declare function listPrompts(): PromptDefinition[];
86
+
87
+ declare const VERSION: string;
80
88
 
81
89
  /**
82
- * @channlize/mcp
83
- * Model Context Protocol (MCP) server for Channlize
84
- * Enables AI agents to interact with Channlize platform
90
+ * Builds a configured `McpServer` (tools, resources and prompts) without
91
+ * connecting it. Tools are registered for the keys you pass: server-key
92
+ * tools for `serverApiKey`, visitor tools for `widgetKey`.
85
93
  */
86
-
94
+ declare function buildServer(config: ChannlizeMCPConfig, info?: {
95
+ name?: string;
96
+ version?: string;
97
+ }): McpServer;
87
98
  /**
88
- * Channlize MCP Server
89
- * Provides resources, tools, and prompts for AI agents
99
+ * Channlize MCP server. Validates the configuration on construction (a
100
+ * missing key or a widget key passed as the server key throws
101
+ * `ConfigError`).
90
102
  */
91
103
  declare class ChannlizeMCPServer {
92
104
  private server;
93
- private config?;
105
+ private readonly config;
106
+ private readonly info;
94
107
  constructor(options?: MCPServerOptions);
95
- private setupHandlers;
96
- /**
97
- * Set or update the Channlize configuration
98
- */
99
- setConfig(config: ChannlizeMCPConfig): void;
100
- /**
101
- * Get the underlying MCP server instance
102
- */
103
- getServer(): Server;
104
- /**
105
- * Start the server with stdio transport
106
- */
108
+ /** The underlying `McpServer`. */
109
+ getServer(): McpServer;
110
+ /** Serve over stdio (what desktop and IDE clients launch). */
107
111
  runStdio(): Promise<void>;
108
112
  /**
109
- * Close the server
113
+ * Serve Streamable HTTP at `http://<host>:<port>/mcp` (default
114
+ * 127.0.0.1:3333). Each request gets a fresh server; nothing is shared.
110
115
  */
116
+ runHttp(options?: HttpServerOptions): Promise<{
117
+ url: string;
118
+ server: node_http.Server;
119
+ close: () => Promise<void>;
120
+ }>;
111
121
  close(): Promise<void>;
112
122
  }
113
- /**
114
- * Create and return a new Channlize MCP Server instance
115
- */
123
+ /** Create a new Channlize MCP server. */
116
124
  declare function createMCPServer(options?: MCPServerOptions): ChannlizeMCPServer;
117
125
 
118
- export { type ChannlizeMCPConfig, ChannlizeMCPServer, type MCPServerOptions, type ResourceContext, type ToolContext, createMCPServer, ChannlizeMCPServer as default, getPrompt, getResource, getTool, listPrompts, listResources, listTools };
126
+ export { ChannlizeMCPServer, ConfigError, ToolError, VERSION, buildServer, configFromEnv, createMCPServer, ChannlizeMCPServer as default, keyKind, resolveConfig };
127
+ export type { ChannlizeMCPConfig, HttpServerOptions, KeyKind, MCPServerOptions, ResolvedConfig };