@anychat-ai/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Redirect Ventures Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,174 @@
+# @anychat-ai/mcp
+
+**Drive your [Anychat](https://www.anychat.ai) workspace from Claude Code, Claude Desktop, Cursor, or any MCP host.**
+
+Anychat is the agent framework for business messaging — RCS, WhatsApp, Apple Messages for Business, SMS and Webchat. This [Model Context Protocol](https://modelcontextprotocol.io) server exposes the Anychat public API as tools, so an AI agent can read and change your agents, playbooks, channels, people and outreach _with your own API key and your own permissions_ — nothing it does exceeds what you could do with `curl`.
+
+Docs: <https://docs.anychat.ai/integrations/mcp/> · API reference: <https://docs.anychat.ai/reference/agent-api/>
+
+## Setup
+
+1. Create an API key in the Anychat console: **Workspace → API keys**. Give it only the scopes you want your agent to have (e.g. `agents:write`, `people:read`, `messages:read`).
+2. Add the server to your host.
+
+**Claude Code**
+
+```bash
+claude mcp add anychat --env ANYCHAT_API_KEY=sk-any-... -- npx -y @anychat-ai/mcp
+```
+
+**Claude Desktop / Cursor / other MCP hosts** — add to the `mcpServers` config:
+
+```json
+{
+  "mcpServers": {
+    "anychat": {
+      "command": "npx",
+      "args": ["-y", "@anychat-ai/mcp"],
+      "env": { "ANYCHAT_API_KEY": "sk-any-..." }
+    }
+  }
+}
+```
+
+**Check the key** (prints org, role, scopes):
+
+```bash
+ANYCHAT_API_KEY=sk-any-... npx -y @anychat-ai/mcp check
+```
+
+## Environment
+
+| Variable           | Required | Default                   |
+| ------------------ | -------- | ------------------------- |
+| `ANYCHAT_API_KEY`  | yes      | —                         |
+| `ANYCHAT_API_URL`  | no       | `https://api.anychat.ai`  |
+| `ANYCHAT_DOCS_URL` | no       | `https://docs.anychat.ai` |
+
+Flags: `--read-only` registers only read tools. Subcommands: `check`, `tools`, `--version`, `--help`.
+
+## Tools
+
+94 tools, a 1:1 projection of the [Agent API](https://docs.anychat.ai/reference/agent-api/) grouped as the reference is (orient → Definition → Capabilities → Channels → People → Activity → Org → Docs). `npx -y @anychat-ai/mcp tools` prints the live table.
+
+Every tool carries MCP annotations: `read` tools are `readOnlyHint`; `write` tools change configuration; `destructive` tools (deletes, provisioning requests, imports over an existing agent, secret rotation) are `destructiveHint` so your host asks before running them.
+
+<details>
+<summary>Full tool table</summary>
+
+| Tool                          | Kind        | Scope                  | Purpose                                             |
+| ----------------------------- | ----------- | ---------------------- | --------------------------------------------------- |
+| `whoami`                      | read        | `(any)`                | Who am I                                            |
+| `list_agents`                 | read        | `agents:read`          | List agents                                         |
+| `get_agent`                   | read        | `agents:read`          | Get agent                                           |
+| `create_agent`                | write       | `agents:write`         | Create agent                                        |
+| `update_agent`                | write       | `agents:write`         | Update agent                                        |
+| `delete_agent`                | destructive | `agents:write`         | Delete agent                                        |
+| `export_agent`                | read        | `agents:read`          | Export agent                                        |
+| `import_agent`                | destructive | `agents:write`         | Import agent document                               |
+| `apply_agent_template`        | destructive | `templates:apply`      | Apply agent template                                |
+| `list_agent_updates`          | read        | `agents:read`          | List available catalog updates                      |
+| `apply_agent_update`          | write       | `agents:write`         | Apply one catalog update                            |
+| `list_catalog_items`          | read        | `catalogs:read`        | List a system catalog                               |
+| `get_catalog_item`            | read        | `catalogs:read`        | Get a catalog item                                  |
+| `get_identity`                | read        | `agents:read`          | Get agent identity                                  |
+| `update_identity`             | write       | `agents:write`         | Update agent identity                               |
+| `get_personality`             | read        | `agents:read`          | Get agent personality                               |
+| `set_personality`             | write       | `agents:write`         | Set agent personality                               |
+| `import_personality_template` | write       | `templates:apply`      | Import personality template                         |
+| `get_objectives`              | read        | `agents:read`          | Get agent objectives                                |
+| `set_objectives`              | write       | `agents:write`         | Set agent objectives                                |
+| `import_objective_template`   | write       | `templates:apply`      | Import objective template                           |
+| `get_guardrails`              | read        | `agents:read`          | Get agent guardrails                                |
+| `set_guardrails`              | write       | `agents:write`         | Set agent guardrails                                |
+| `update_guardrails`           | write       | `agents:write`         | Update agent guardrails                             |
+| `import_guardrail_template`   | write       | `templates:apply`      | Import guardrail template                           |
+| `list_playbooks`              | read        | `agents:read`          | List playbooks                                      |
+| `get_playbook`                | read        | `agents:read`          | Get playbook                                        |
+| `create_playbook`             | write       | `agents:write`         | Create playbook                                     |
+| `update_playbook`             | write       | `agents:write`         | Update playbook                                     |
+| `delete_playbook`             | destructive | `agents:write`         | Delete playbook                                     |
+| `set_default_playbook`        | write       | `agents:write`         | Set default playbook                                |
+| `import_playbook_template`    | write       | `templates:apply`      | Import playbook template                            |
+| `list_message_templates`      | read        | `agents:read`          | List message templates                              |
+| `get_message_template`        | read        | `agents:read`          | Get message template                                |
+| `upsert_message_template`     | write       | `agents:write`         | Create or replace message template                  |
+| `delete_message_template`     | destructive | `agents:write`         | Delete message template                             |
+| `preview_message_template`    | read        | `agents:read`          | Preview message template                            |
+| `list_tool_bindings`          | read        | `agents:read`          | List tool bindings                                  |
+| `get_tool_binding`            | read        | `agents:read`          | Get a tool binding                                  |
+| `upsert_tool_binding`         | write       | `agents:write`         | Create or replace a tool binding                    |
+| `update_tool_binding`         | write       | `agents:write`         | Update a tool binding (merge)                       |
+| `set_tool_binding_enabled`    | write       | `agents:write`         | Enable or disable a tool binding                    |
+| `delete_tool_binding`         | destructive | `agents:write`         | Delete a tool binding                               |
+| `get_oauth_status`            | read        | `agents:read`          | Get OAuth connection status                         |
+| `disconnect_oauth`            | destructive | `agents:write`         | Disconnect an OAuth grant                           |
+| `get_outreach_config`         | read        | `agents:read`          | Get outreach config                                 |
+| `replace_outreach_config`     | write       | `agents:write`         | Replace outreach config                             |
+| `preview_outreach`            | read        | `agents:read`          | Preview outreach greeting                           |
+| `list_outreach_links`         | read        | `agents:read`          | List outreach links                                 |
+| `create_outreach_link`        | write       | `agents:write`         | Create an outreach link                             |
+| `update_outreach_link`        | write       | `agents:write`         | Pause or resume an outreach link                    |
+| `delete_outreach_link`        | destructive | `agents:write`         | Delete an outreach link                             |
+| `list_knowledge_documents`    | read        | `knowledge:read`       | List knowledge documents                            |
+| `list_channels`               | read        | `agents:read`          | List channel bindings                               |
+| `get_channel`                 | read        | `agents:read`          | Get a channel binding                               |
+| `request_channel`             | destructive | `agents:write`         | Request a managed channel                           |
+| `bind_channel`                | write       | `agents:write`         | Bind an unmanaged channel (bring your own provider) |
+| `update_channel`              | write       | `agents:write`         | Update a channel binding                            |
+| `disable_channel`             | write       | `agents:write`         | Disable a channel binding                           |
+| `enable_channel`              | write       | `agents:write`         | Enable a channel binding                            |
+| `delete_channel`              | destructive | `agents:write`         | Delete a channel binding                            |
+| `list_people`                 | read        | `people:read`          | List people                                         |
+| `get_person`                  | read        | `people:read`          | Get a person                                        |
+| `create_person`               | write       | `people:write`         | Create a person                                     |
+| `update_person`               | write       | `people:write`         | Update a person                                     |
+| `delete_person`               | destructive | `people:write`         | Delete a person                                     |
+| `merge_people`                | write       | `people:write`         | Merge two people                                    |
+| `export_people`               | read        | `people:export`        | Export people (bulk)                                |
+| `import_people`               | write       | `people:write`         | Import people                                       |
+| `list_person_appointments`    | read        | `people:read`          | List a person's appointments                        |
+| `list_appointments`           | read        | `people:read`          | List appointments (all people)                      |
+| `list_segments`               | read        | `people:read`          | List people segments                                |
+| `get_segment`                 | read        | `people:read`          | Get a people segment                                |
+| `create_segment`              | write       | `people:write`         | Create a people segment                             |
+| `update_segment`              | write       | `people:write`         | Replace a people segment                            |
+| `delete_segment`              | destructive | `people:write`         | Delete a people segment                             |
+| `list_messages`               | read        | `messages:read`        | List messages                                       |
+| `list_conversations`          | read        | `messages:read`        | List conversations                                  |
+| `list_users`                  | read        | `messages:read`        | List users                                          |
+| `list_logs`                   | read        | `messages:read`        | List runtime logs                                   |
+| `list_activity`               | read        | `messages:read`        | List activity feed                                  |
+| `get_org`                     | read        | `(any)`                | Get org                                             |
+| `update_org`                  | write       | `org:admin`            | Update org                                          |
+| `list_api_keys`               | read        | `org:admin`            | List API keys                                       |
+| `get_api_key`                 | read        | `org:admin`            | Get API key                                         |
+| `list_webhooks`               | read        | `webhooks:manage`      | List webhooks                                       |
+| `get_webhook`                 | read        | `webhooks:manage`      | Get webhook                                         |
+| `create_webhook`              | write       | `webhooks:manage`      | Create webhook                                      |
+| `update_webhook`              | write       | `webhooks:manage`      | Update webhook                                      |
+| `delete_webhook`              | destructive | `webhooks:manage`      | Delete webhook                                      |
+| `rotate_webhook_secret`       | destructive | `webhooks:manage`      | Rotate webhook signing secret                       |
+| `search_docs`                 | read        | `(none — public docs)` | Search Anychat docs                                 |
+| `list_docs`                   | read        | `(none — public docs)` | List Anychat docs pages                             |
+| `read_doc`                    | read        | `(none — public docs)` | Read an Anychat docs page                           |
+
+</details>
+
+## Programmatic use
+
+```ts
+import { AnychatClient, createServer } from '@anychat-ai/mcp';
+const client = new AnychatClient({ apiKey: process.env.ANYCHAT_API_KEY! });
+const server = createServer({ client }); // an McpServer — attach any transport
+```
+
+## Security
+
+- The server holds no credentials of its own; every request carries the key you gave it, and the Anychat API enforces the key's org, role and scopes exactly as it would for you.
+- Treat tool results as data: they contain your agents' configuration and your customers' records.
+- Requests are tagged `X-Anychat-Agent: mcp` so they can be told apart in your access logs.
+
+## License
+
+MIT © Redirect Ventures Inc.

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * `anychat-mcp` — stdio MCP server over the Anychat public API.
+ *
+ *   ANYCHAT_API_KEY=sk-any-... npx -y @anychat-ai/mcp
+ *
+ * Env:
+ *   ANYCHAT_API_KEY   required — API key from the console (Workspace → API keys)
+ *   ANYCHAT_API_URL   optional — API origin (default https://api.anychat.ai)
+ *   ANYCHAT_DOCS_URL  optional — docs origin (default https://docs.anychat.ai)
+ *
+ * Subcommands:
+ *   (none)      start the stdio server
+ *   check       verify the key: prints org, role, scopes, and exits
+ *   --read-only register only read tools
+ *   --version / --help
+ *
+ * All diagnostics go to stderr; stdout is the MCP transport.
+ */
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const client_1 = require("./client");
+const docs_1 = require("./docs");
+const server_1 = require("./server");
+const tools_1 = require("./tools");
+const version_1 = require("./version");
+const HELP = `anychat-mcp ${version_1.VERSION} — Anychat MCP server
+
+Usage:
+  anychat-mcp [--read-only]     start the stdio MCP server
+  anychat-mcp check             verify ANYCHAT_API_KEY and print org/role/scopes
+  anychat-mcp tools             list the tool table
+  anychat-mcp --version | --help
+
+Environment:
+  ANYCHAT_API_KEY   required — API key from the console (Workspace → API keys)
+  ANYCHAT_API_URL   optional — default ${client_1.DEFAULT_API_URL}
+  ANYCHAT_DOCS_URL  optional — default ${docs_1.DEFAULT_DOCS_URL}
+
+Docs: https://docs.anychat.ai/integrations/mcp/`;
+async function main(argv) {
+    const args = new Set(argv);
+    if (args.has('--help') || args.has('-h')) {
+        process.stderr.write(HELP + '\n');
+        return 0;
+    }
+    if (args.has('--version') || args.has('-v')) {
+        process.stdout.write(version_1.VERSION + '\n');
+        return 0;
+    }
+    if (args.has('tools')) {
+        for (const t of tools_1.allTools) {
+            process.stdout.write(`${t.name.padEnd(28)} ${t.kind.padEnd(11)} ${t.scope.padEnd(16)} ${t.title}\n`);
+        }
+        return 0;
+    }
+    const apiKey = process.env.ANYCHAT_API_KEY;
+    if (!apiKey) {
+        process.stderr.write('anychat-mcp: ANYCHAT_API_KEY is not set. Create a key in the Anychat console (Workspace → API keys) and export it.\n');
+        return 2;
+    }
+    const client = new client_1.AnychatClient({
+        apiKey,
+        baseUrl: process.env.ANYCHAT_API_URL,
+        userAgent: `anychat-mcp/${version_1.VERSION}`,
+    });
+    if (args.has('check')) {
+        try {
+            const me = await client.me();
+            process.stdout.write(`OK — org ${me.org.id}${me.org.name ? ` (${me.org.name})` : ''}, role ${me.org.role}, scopes: ${me.scopes.join(', ') || '(none)'}\nAPI: ${client.baseUrl}\n`);
+            return 0;
+        }
+        catch (err) {
+            process.stderr.write(`anychat-mcp: check failed — ${err.message}\n`);
+            return 1;
+        }
+    }
+    const server = (0, server_1.createServer)({
+        client,
+        docs: new docs_1.DocsIndex({ baseUrl: process.env.ANYCHAT_DOCS_URL }),
+        readOnly: args.has('--read-only'),
+    });
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    process.stderr.write(`anychat-mcp ${version_1.VERSION} ready (${client.baseUrl})\n`);
+    // Keep running until the host closes stdin.
+    return new Promise(resolve => {
+        process.stdin.on('close', () => resolve(0));
+        process.on('SIGINT', () => resolve(0));
+        process.on('SIGTERM', () => resolve(0));
+    });
+}
+main(process.argv.slice(2)).then(code => process.exit(code), err => {
+    process.stderr.write(`anychat-mcp: ${err?.stack || err}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":"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"}

package/dist/client.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Thin HTTP client for the Anychat public API (`/v1`).
+ *
+ * Deliberately dumb: no retries, no caching beyond the `/v1/me` org lookup,
+ * no knowledge of resources. Tools are a 1:1 projection of documented routes
+ * (https://docs.anychat.ai/reference/agent-api/) and this class only owns the
+ * transport: base URL, bearer key, org path prefix, error shaping.
+ *
+ * Every request carries the caller's own API key — the server can do nothing
+ * the key holder couldn't do with curl. `X-Anychat-Agent` identifies this
+ * automation to the api's access log (see console-copilot design §5).
+ */
+export declare const DEFAULT_API_URL = "https://api.anychat.ai";
+export interface AnychatClientOptions {
+    /** API origin, e.g. `https://api.anychat.ai`. `/v1` is appended. */
+    baseUrl?: string;
+    /** Anychat API key (`sk-any-…`) or a console session bearer token. */
+    apiKey: string;
+    /** Value for `X-Anychat-Agent`; defaults to `mcp`. */
+    agent?: string;
+    /** User-Agent suffix; defaults to the package version. */
+    userAgent?: string;
+    /** Injectable fetch for tests. */
+    fetchImpl?: typeof fetch;
+}
+/** Shape of `GET /v1/me`. */
+export interface MeInfo {
+    caller: {
+        kind: string;
+        id: string;
+    };
+    org: {
+        id: string;
+        name?: string;
+        role: string;
+    };
+    isSysop?: boolean;
+    scopes: string[];
+    rateLimit: unknown;
+}
+export type QueryValue = string | number | boolean | undefined | null;
+export type Query = Record<string, QueryValue>;
+export interface RequestOptions {
+    query?: Query;
+    body?: unknown;
+    /** Extra headers (rare — e.g. `If-Match`). */
+    headers?: Record<string, string>;
+}
+/** Error thrown for non-2xx responses. `body` is the parsed JSON when present. */
+export declare class AnychatApiError extends Error {
+    readonly status: number;
+    readonly body?: unknown | undefined;
+    readonly method?: string | undefined;
+    readonly path?: string | undefined;
+    constructor(status: number, message: string, body?: unknown | undefined, method?: string | undefined, path?: string | undefined);
+}
+export declare class AnychatClient {
+    readonly baseUrl: string;
+    private readonly apiKey;
+    private readonly agent;
+    private readonly userAgent;
+    private readonly fetchImpl;
+    private mePromise?;
+    constructor(opts: AnychatClientOptions);
+    /** `GET /v1/me`, cached for the life of the client. */
+    me(): Promise<MeInfo>;
+    /** The org id this key is bound to. */
+    orgId(): Promise<string>;
+    /**
+     * Build an org-scoped path: `orgPath('/agents')` → `/orgs/{org}/agents`.
+     * Path segments the caller supplies must already be encoded (use
+     * `encodeURIComponent` for ids that can contain `/` such as `@anychat/...`).
+     */
+    orgPath(subPath: string): Promise<string>;
+    get<T = unknown>(path: string, query?: Query): Promise<T>;
+    post<T = unknown>(path: string, body?: unknown, query?: Query): Promise<T>;
+    put<T = unknown>(path: string, body?: unknown, query?: Query): Promise<T>;
+    patch<T = unknown>(path: string, body?: unknown, query?: Query): Promise<T>;
+    delete<T = unknown>(path: string, query?: Query): Promise<T>;
+    /**
+     * Issue a request against `/v1{path}`. Returns parsed JSON, or `null` for
+     * 204 / empty bodies. Throws {@link AnychatApiError} on non-2xx.
+     */
+    request<T = unknown>(method: string, path: string, opts?: RequestOptions): Promise<T>;
+}
+/**
+ * Extract a human message from an error body. The api answers with RFC 7807
+ * problem details (`title`, `detail`, `code`, `errors[]`) on newer routes and
+ * `{ statusCode, message }` on older ones; strings and empty bodies happen too.
+ */
+export declare function errorMessage(body: unknown, fallback?: string): string;

package/dist/client.js

@@ -0,0 +1,154 @@
+"use strict";
+/**
+ * Thin HTTP client for the Anychat public API (`/v1`).
+ *
+ * Deliberately dumb: no retries, no caching beyond the `/v1/me` org lookup,
+ * no knowledge of resources. Tools are a 1:1 projection of documented routes
+ * (https://docs.anychat.ai/reference/agent-api/) and this class only owns the
+ * transport: base URL, bearer key, org path prefix, error shaping.
+ *
+ * Every request carries the caller's own API key — the server can do nothing
+ * the key holder couldn't do with curl. `X-Anychat-Agent` identifies this
+ * automation to the api's access log (see console-copilot design §5).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AnychatClient = exports.AnychatApiError = exports.DEFAULT_API_URL = void 0;
+exports.errorMessage = errorMessage;
+exports.DEFAULT_API_URL = 'https://api.anychat.ai';
+/** Error thrown for non-2xx responses. `body` is the parsed JSON when present. */
+class AnychatApiError extends Error {
+    status;
+    body;
+    method;
+    path;
+    constructor(status, message, body, method, path) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.method = method;
+        this.path = path;
+        this.name = 'AnychatApiError';
+    }
+}
+exports.AnychatApiError = AnychatApiError;
+class AnychatClient {
+    baseUrl;
+    apiKey;
+    agent;
+    userAgent;
+    fetchImpl;
+    mePromise;
+    constructor(opts) {
+        if (!opts.apiKey)
+            throw new Error('AnychatClient: apiKey is required');
+        this.baseUrl = (opts.baseUrl || exports.DEFAULT_API_URL).replace(/\/+$/, '');
+        this.apiKey = opts.apiKey;
+        this.agent = opts.agent || 'mcp';
+        this.userAgent = opts.userAgent || `anychat-mcp`;
+        this.fetchImpl = opts.fetchImpl || fetch;
+    }
+    /** `GET /v1/me`, cached for the life of the client. */
+    me() {
+        if (!this.mePromise) {
+            this.mePromise = this.request('GET', '/me').catch(err => {
+                this.mePromise = undefined; // don't cache failures
+                throw err;
+            });
+        }
+        return this.mePromise;
+    }
+    /** The org id this key is bound to. */
+    async orgId() {
+        return (await this.me()).org.id;
+    }
+    /**
+     * Build an org-scoped path: `orgPath('/agents')` → `/orgs/{org}/agents`.
+     * Path segments the caller supplies must already be encoded (use
+     * `encodeURIComponent` for ids that can contain `/` such as `@anychat/...`).
+     */
+    async orgPath(subPath) {
+        const org = await this.orgId();
+        return `/orgs/${encodeURIComponent(org)}${subPath.startsWith('/') ? '' : '/'}${subPath}`;
+    }
+    get(path, query) {
+        return this.request('GET', path, { query });
+    }
+    post(path, body, query) {
+        return this.request('POST', path, { body, query });
+    }
+    put(path, body, query) {
+        return this.request('PUT', path, { body, query });
+    }
+    patch(path, body, query) {
+        return this.request('PATCH', path, { body, query });
+    }
+    delete(path, query) {
+        return this.request('DELETE', path, { query });
+    }
+    /**
+     * Issue a request against `/v1{path}`. Returns parsed JSON, or `null` for
+     * 204 / empty bodies. Throws {@link AnychatApiError} on non-2xx.
+     */
+    async request(method, path, opts = {}) {
+        const url = new URL(`${this.baseUrl}/v1${path.startsWith('/') ? '' : '/'}${path}`);
+        for (const [k, v] of Object.entries(opts.query || {})) {
+            if (v === undefined || v === null || v === '')
+                continue;
+            url.searchParams.set(k, String(v));
+        }
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            Accept: 'application/json',
+            'User-Agent': this.userAgent,
+            'X-Anychat-Agent': this.agent,
+            ...(opts.headers || {}),
+        };
+        let body;
+        if (opts.body !== undefined) {
+            headers['Content-Type'] = 'application/json';
+            body = JSON.stringify(opts.body);
+        }
+        const res = await this.fetchImpl(url, { method, headers, body });
+        const text = await res.text();
+        let parsed = null;
+        if (text) {
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                parsed = text;
+            }
+        }
+        if (!res.ok) {
+            throw new AnychatApiError(res.status, errorMessage(parsed, res.statusText) || `HTTP ${res.status}`, parsed, method, path);
+        }
+        return parsed;
+    }
+}
+exports.AnychatClient = AnychatClient;
+/**
+ * Extract a human message from an error body. The api answers with RFC 7807
+ * problem details (`title`, `detail`, `code`, `errors[]`) on newer routes and
+ * `{ statusCode, message }` on older ones; strings and empty bodies happen too.
+ */
+function errorMessage(body, fallback = '') {
+    if (typeof body === 'string')
+        return body;
+    if (!body || typeof body !== 'object')
+        return fallback;
+    const b = body;
+    const head = b.message || b.title || b.detail || b.error || fallback;
+    const parts = [];
+    if (head)
+        parts.push(String(head));
+    if (b.code && !String(head).includes(String(b.code)))
+        parts.push(`[${b.code}]`);
+    if (Array.isArray(b.errors) && b.errors.length) {
+        const fields = b.errors
+            .map((e) => e && e.field ? `${e.field}: ${e.message ?? 'invalid'}` : JSON.stringify(e))
+            .join('; ');
+        parts.push(`(${fields})`);
+    }
+    return parts.join(' ');
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/docs.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Product-docs access for the `search_docs` / `read_doc` tools.
+ *
+ * Reads the machine-readable exports of docs.anychat.ai:
+ *   - `/llms.txt`       — index: `- [Title](url): one-line summary` per page
+ *   - `/llms-full.txt`  — every page's markdown, each preceded by
+ *                         `<!-- page: <url> -->` and `# Title`
+ * (both generated at docs build time — see the docs repo).
+ *
+ * Search is a plain keyword scorer over title + summary + body: the corpus is
+ * ~30 pages, so anything fancier is overkill, and the model reads the page it
+ * picks with `read_doc` anyway.
+ */
+export declare const DEFAULT_DOCS_URL = "https://docs.anychat.ai";
+export interface DocPage {
+    title: string;
+    url: string;
+    summary: string;
+    /** Full markdown; present once llms-full.txt has loaded. */
+    body?: string;
+}
+export interface DocSearchHit {
+    title: string;
+    url: string;
+    summary: string;
+    score: number;
+    snippet?: string;
+}
+export declare class DocsIndex {
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private index?;
+    private full?;
+    constructor(opts?: {
+        baseUrl?: string;
+        fetchImpl?: typeof fetch;
+    });
+    /** The page index (llms.txt), cached for {@link CACHE_TTL_MS}. */
+    pages(): Promise<DocPage[]>;
+    /** url → markdown body from llms-full.txt, cached. */
+    private bodies;
+    search(query: string, limit?: number): Promise<DocSearchHit[]>;
+    /**
+     * Full markdown for a page, by exact url, by url path suffix, or by
+     * case-insensitive title match. Prefers the per-page markdown file the
+     * llms.txt entry links to; falls back to the llms-full.txt body.
+     */
+    read(ref: string): Promise<DocPage | undefined>;
+    private fetchText;
+}
+/** Parse `- [Title](url): summary` lines. Tolerates leading `*` and missing summaries. */
+export declare function parseLlmsTxt(text: string): DocPage[];
+/** Split llms-full.txt on `<!-- page: url -->` markers → url → body. */
+export declare function parseLlmsFull(text: string): Map<string, string>;
+/**
+ * `https://d/x/index.md`, `https://d/x/`, `https://d/x/index.html` and
+ * `https://d/x` all identify the same page — llms.txt links the markdown file
+ * while llms-full.txt markers carry the canonical HTML url.
+ */
+export declare function normalizeUrl(url: string): string;