@besales/mcp 0.1.0

package/dist/http/api-client.js

@@ -0,0 +1,115 @@
+import axios from 'axios';
+import { normalizeApiBaseUrl } from '../auth/oauth-client.js';
+import { TokenStorage } from '../auth/token-storage.js';
+import { logger } from '../utils/logger.js';
+export const API_REQUEST_TIMEOUT_MS = 60_000;
+export class ApiClientError extends Error {
+    status;
+    responseMessage;
+    constructor(message, status, responseMessage) {
+        super(message);
+        this.status = status;
+        this.responseMessage = responseMessage;
+        this.name = 'ApiClientError';
+    }
+}
+export class ApiClientNetworkError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ApiClientNetworkError';
+    }
+}
+export class ApiClient {
+    apiBaseUrl;
+    tokenStorage;
+    transport;
+    timeoutMs;
+    constructor(options = {}) {
+        this.apiBaseUrl = normalizeApiBaseUrl(options.apiBaseUrl);
+        this.tokenStorage = options.tokenStorage ?? new TokenStorage();
+        this.transport =
+            options.transport ??
+                axios.create({
+                    timeout: options.timeoutMs ?? API_REQUEST_TIMEOUT_MS,
+                });
+        this.timeoutMs = options.timeoutMs ?? API_REQUEST_TIMEOUT_MS;
+    }
+    async post(path, body) {
+        return this.request('POST', path, body);
+    }
+    async patch(path, body) {
+        return this.request('PATCH', path, body);
+    }
+    async getStoredWorkspaceId() {
+        return this.tokenStorage.get('workspace_id');
+    }
+    async request(method, path, body) {
+        const apiKey = await this.tokenStorage.get('api_key');
+        if (!apiKey) {
+            throw new ApiClientError('Not connected to Animaly');
+        }
+        const url = buildApiUrl(this.apiBaseUrl, path);
+        try {
+            const response = await this.transport.request({
+                method,
+                url,
+                data: body,
+                headers: {
+                    Authorization: `Bearer ${apiKey}`,
+                },
+                timeout: this.timeoutMs,
+            });
+            logger.debug({ method, path, status: response.status }, 'Animaly API call completed');
+            return response.data;
+        }
+        catch (error) {
+            if (axios.isAxiosError(error)) {
+                const status = error.response?.status;
+                const responseMessage = getSafeResponseMessage(error.response?.data);
+                if (status) {
+                    throw new ApiClientError(`Animaly API request failed with status ${status}`, status, responseMessage);
+                }
+                throw new ApiClientNetworkError(error.message);
+            }
+            if (error instanceof ApiClientError || error instanceof ApiClientNetworkError) {
+                throw error;
+            }
+            if (error instanceof Error) {
+                throw new ApiClientNetworkError(error.message);
+            }
+            throw new ApiClientNetworkError('Unknown Animaly API transport error');
+        }
+    }
+}
+export function buildApiUrl(apiBaseUrl, path) {
+    const normalizedBaseUrl = normalizeApiBaseUrl(apiBaseUrl);
+    const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+    if (normalizedPath.startsWith('/api/v2/')) {
+        throw new ApiClientError('ApiClient paths must be relative to /api/v2');
+    }
+    return `${normalizedBaseUrl}${normalizedPath}`;
+}
+function getSafeResponseMessage(data) {
+    if (!data || typeof data !== 'object') {
+        return undefined;
+    }
+    const maybeMessage = data.message;
+    if (typeof maybeMessage === 'string') {
+        return maybeMessage;
+    }
+    if (Array.isArray(maybeMessage)) {
+        return maybeMessage.filter((item) => typeof item === 'string').join('; ');
+    }
+    const maybeError = data.error;
+    if (typeof maybeError === 'string') {
+        return maybeError;
+    }
+    if (maybeError && typeof maybeError === 'object') {
+        const nestedMessage = maybeError.message;
+        if (typeof nestedMessage === 'string') {
+            return nestedMessage;
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=api-client.js.map

package/dist/http/api-client.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export { createAuthorizationUrl, createCodeChallenge, DEFAULT_API_BASE_URL, generateCodeVerifier, generateState, normalizeApiBaseUrl, OauthClient, } from './auth/oauth-client.js';
+export type { OAuthConnectResult, OauthClientOptions } from './auth/oauth-client.js';
+export { TOKEN_STORAGE_SERVICE, TokenStorage, } from './auth/token-storage.js';
+export type { TokenStorageAccount } from './auth/token-storage.js';
+export { getHelpText, runCli } from './cli.js';
+export type { CliDeps, CliIo, CredentialStorage, OAuthConnector } from './cli.js';
+export { API_REQUEST_TIMEOUT_MS, ApiClient, ApiClientError, ApiClientNetworkError, buildApiUrl, } from './http/api-client.js';
+export type { ApiClientOptions, ApiMethod, ApiTransport, ApiTransportRequest, ApiTransportResponse, CredentialReader, ToolApiClient, } from './http/api-client.js';
+export { readPackageVersion } from './package-metadata.js';
+export { resources } from './resources/registry.js';
+export type { RegisteredResource } from './resources/registry.js';
+export { callRegisteredTool, createMcpServer, listRegisteredResources, listRegisteredTools, readRegisteredResource, startMcpServer, } from './server.js';
+export type { StartedMcpServer, StartMcpServerOptions } from './server.js';
+export { createTools, tools } from './tools/registry.js';
+export type { RegisteredTool, ToolFactoryOptions } from './tools/registry.js';
+export { maskApiKey } from './utils/mask.js';

package/dist/index.js

@@ -0,0 +1,10 @@
+export { createAuthorizationUrl, createCodeChallenge, DEFAULT_API_BASE_URL, generateCodeVerifier, generateState, normalizeApiBaseUrl, OauthClient, } from './auth/oauth-client.js';
+export { TOKEN_STORAGE_SERVICE, TokenStorage, } from './auth/token-storage.js';
+export { getHelpText, runCli } from './cli.js';
+export { API_REQUEST_TIMEOUT_MS, ApiClient, ApiClientError, ApiClientNetworkError, buildApiUrl, } from './http/api-client.js';
+export { readPackageVersion } from './package-metadata.js';
+export { resources } from './resources/registry.js';
+export { callRegisteredTool, createMcpServer, listRegisteredResources, listRegisteredTools, readRegisteredResource, startMcpServer, } from './server.js';
+export { createTools, tools } from './tools/registry.js';
+export { maskApiKey } from './utils/mask.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,aAAa,EACb,mBAAmB,EACnB,WAAW,GACZ,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,qBAAqB,EACrB,YAAY,GACb,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAE/C,OAAO,EACL,sBAAsB,EACtB,SAAS,EACT,cAAc,EACd,qBAAqB,EACrB,WAAW,GACZ,MAAM,sBAAsB,CAAC;AAU9B,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEpD,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,uBAAuB,EACvB,mBAAmB,EACnB,sBAAsB,EACtB,cAAc,GACf,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/package-metadata.d.ts

@@ -0,0 +1 @@
+export declare function readPackageVersion(): string;

package/dist/package-metadata.js

@@ -0,0 +1,6 @@
+import { readFileSync } from 'node:fs';
+export function readPackageVersion() {
+    const packageJson = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+    return packageJson.version ?? '0.0.0';
+}
+//# sourceMappingURL=package-metadata.js.map

package/dist/package-metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-metadata.js","sourceRoot":"","sources":["../src/package-metadata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAMvC,MAAM,UAAU,kBAAkB;IAChC,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAC5B,YAAY,CAAC,IAAI,GAAG,CAAC,iBAAiB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAC/C,CAAC;IAErB,OAAO,WAAW,CAAC,OAAO,IAAI,OAAO,CAAC;AACxC,CAAC"}

package/dist/resources/concepts/external-execution.md

@@ -0,0 +1,22 @@
+# External Execution Pattern
+
+External execution — это двухшаговый паттерн для LLM-heavy операций, когда backend создаёт operation request и возвращает Claude инструкции, а Claude локально выполняет stages и отправляет результат обратно. Это позволяет использовать сильную локальную модель для сложной генерации, анализа или классификации, не делая prompt-services единственным местом исполнения LLM.
+
+Паттерн всегда состоит из пары tools:
+
+1. `*_get_instructions` — получить `operationId`, stages, schemas, ограничения, expiry и human-readable instructions.
+2. `*_submit` — отправить structured result, compiled prompt, findings или generated QA обратно в `ai-aniomaly`.
+
+Execution mode выбирается на backend по auth context. JWT scope `mcp:*` означает external default: backend не выполняет LLM-операцию сам, а ждёт результат от Claude. JWT scope `ui:*` означает internal default: UI может проксировать операцию в prompt-services. Старые tokens без scopes должны оставаться совместимыми и вести себя как internal.
+
+Claude должен соблюдать invariants:
+
+- Не менять `operationId` между get и submit.
+- Выполнять все stages в заданном порядке.
+- Возвращать JSON в форме, которую запросил backend.
+- При 410 expired начинать заново с matching `*_get_instructions`.
+- Не отправлять raw secrets, API keys или Authorization headers в submit body.
+
+Связанные external pairs включают prompt generation, prompt iterate, prompt analyze, ICP analysis, sandbox findings, simulation findings и Q&A generation.
+
+Практическое правило: если tool name заканчивается на `_get_instructions`, Claude должен сначала прочитать instructions, выполнить локальную работу, затем вызвать соответствующий `_submit` tool. Direct tools вроде `besales_icp_create` или `besales_sandbox_run_start` не требуют этого двухшагового режима.

package/dist/resources/concepts/handoff.md

@@ -0,0 +1,16 @@
+# Multi-agent Routing & Handoffs
+
+Handoff — это управляемая передача диалога между агентами или от AI к человеку. Он отличается от обычного routing тем, что происходит внутри уже начавшегося conversation и должен сохранять контекст: intent, summary, extracted slots, важные ограничения, историю решений и причину передачи.
+
+Routing отвечает на вопрос "какой агент должен принять входящий запрос сейчас". Handoff отвечает на вопрос "когда текущий агент понял, что другой агент или оператор лучше продолжит диалог". В v2-модели это не свободная LLM-команда, а набор правил и переходов с проверкой условий, прав и audit trail.
+
+Claude должен учитывать несколько принципов:
+
+- Handoff не должен терять память диалога: новый агент получает краткий structured summary.
+- Передача человеку должна быть явной, особенно при юридических, финансовых, конфликтных или sales-closing сценариях.
+- Multi-agent маршруты должны быть детерминированными там, где это возможно, и LLM-assisted только для классификации intent или ambiguity resolution.
+- Sandbox должен проверять handoff behavior без реального перевода клиента в production queue.
+
+В рамках Track D нет отдельного MCP tool для универсального handoff. Этот resource нужен как контекст для prompt generation, analysis и sandbox findings. Если пользователь просит улучшить routing/handoff, Claude должен формулировать требования к агенту и подсвечивать, какие проверки нужно прогнать в sandbox, а не вызывать несуществующий hidden action.
+
+Практическое правило: handoff считается хорошим, если пользователь понимает, почему его переводят, следующий обработчик получает достаточный контекст, а audit trail объясняет причину решения.

package/dist/resources/concepts/icp.md

@@ -0,0 +1,16 @@
+# ICP Concept Reference
+
+ICP (Ideal Customer Profile) в Besales описывает не абстрактную аудиторию для рассылок, а рабочую модель покупателя, по которой строятся промпты, сценарии проверки и sandbox-симуляции. ICP объединяет сегменты, personas, реальные или импортированные dialogue samples и test scenarios. Он помогает агенту отвечать не "для всех", а под конкретные боли, критерии выбора, возражения и стиль коммуникации целевого клиента.
+
+В v1.5 ICP хранится в новых таблицах `icp_profiles`, `icp_segments`, `icp_dialogue_samples`, `personas`, `test_scenarios` и связывается с агентами через `agent_icp_links`. Эти таблицы создаются сразу в v2-shape, поэтому MCP tools работают с будущей моделью данных без прямого доступа к существующим v1 сущностям.
+
+Когда Claude создаёт ICP через MCP, он должен сначала определить workspace context и выбрать источник: ручное описание, CRM dialogues или AI-generated draft. Для CRM-источника используется импорт samples с анонимизацией и подтверждением GDPR. После накопления samples Claude может запросить analysis instructions, локально выполнить stage-пайплайн сегментации/persona generation и отправить результат через submit tool.
+
+Связанные tools:
+
+- `besales_icp_create` — создать ICP-профиль.
+- `besales_icp_import_dialogues` — импортировать и анонимизировать CRM-диалоги.
+- `besales_icp_analysis_get_instructions` — получить stages для анализа ICP.
+- `besales_icp_analysis_submit` — сохранить сегменты, personas и сценарии после external execution.
+
+Практическое правило: если пользователь просит "создай ICP для SaaS B2B", Claude должен создать профиль, затем уточнить или импортировать samples, после чего выполнить analysis pair. ICP не заменяет prompt generation, а даёт ей качественный контекст.

package/dist/resources/concepts/sandbox.md

@@ -0,0 +1,17 @@
+# Sandbox Reference
+
+Sandbox в Besales — это контролируемый прогон агента по ICP personas и test scenarios до выката изменений в production. Цель sandbox не в том, чтобы отправить реальные сообщения клиентам, а в том, чтобы проверить промпт, routing, ответы на возражения, handoff-поведение и качество реакции на разные сегменты.
+
+В v1.5 sandbox реализуется как отдельный домен с `sandbox_runs` и `sandbox_run_feedbacks`. Запуск создаёт run для агента и набора сценариев, а дальнейший анализ findings может выполняться через external execution pair. Production runtime остаётся authoritative через `AgentChat.baseSystemPrompt`, но sandbox позволяет безопасно оценить draft или updated prompt до approve/finalize.
+
+Для Claude важна последовательность:
+
+1. Запустить sandbox run через `besales_sandbox_run_start`.
+2. Получить или дождаться результатов run в backend/UI.
+3. Вызвать `besales_sandbox_findings_get_instructions`, если нужно проанализировать findings.
+4. Локально выполнить stages: сгруппировать проблемы, оценить severity, предложить улучшения.
+5. Отправить результат через `besales_sandbox_findings_submit`.
+
+Sandbox не должен обращаться к реальным channel adapters и не должен создавать внешние side effects. Если сценарий требует проверки CRM или отправки сообщений, backend должен использовать sandbox adapters/ports или mock behavior.
+
+Практическое правило: sandbox — это безопасная проверка качества агента. Claude должен использовать его перед финализацией рискованных prompt changes, особенно если ICP содержит несколько сегментов или есть новые handoff/routing правила.

package/dist/resources/concepts/triggers.md

@@ -0,0 +1,16 @@
+# Actions & Triggers Reference
+
+Actions и triggers описывают управляемые действия агента: что можно сделать, при каких условиях и через какой безопасный runtime path. В v2-подходе LLM не должен галлюцинировать UUID триггеров или напрямую выбирать произвольные side effects. Вместо этого агент получает ограниченный набор action keys, а серверная оркестрация проверяет условия, права, governance и порядок выполнения.
+
+Trigger — это событие или условие, которое запускает действие: intent в диалоге, значение переменной, изменение pipeline/status, ручной запуск или системный workflow. Action — декларативная конфигурация шага: отправить сообщение, установить переменную, вызвать CRM-операцию, передать диалог оператору, инициировать routing или другой безопасный side effect.
+
+Для Claude Desktop это reference resource, а не action surface. MCP tools из Track D не дают прямой универсальный `run_trigger` tool: пользовательские side effects должны идти через конкретные `/api/v2/*` endpoints и backend governance. Если пользователь просит "добавь триггер", Claude должен использовать это описание как терминологический контекст и перейти к соответствующим UI/API задачам, а не пытаться вызвать скрытый trigger напрямую.
+
+Связанные идеи:
+
+- LLM-visible actions должны иметь стабильные semantic keys, а не database IDs.
+- Runtime должен фильтровать доступные actions по агенту, workspace и mode.
+- Sandbox проверяет effects через sandbox ports, не через production side effects.
+- Handoff и routing являются отдельными управляемыми flows, а не свободным текстовым "переключи агента".
+
+Практическое правило: Claude может объяснять и проектировать triggers/actions, но исполнять должен только конкретные MCP tools или backend endpoints, которые явно есть в contract.

package/dist/resources/registry.d.ts

@@ -0,0 +1,5 @@
+import type { Resource, TextResourceContents } from '@modelcontextprotocol/sdk/types.js';
+export interface RegisteredResource extends Resource {
+    read(): Promise<TextResourceContents>;
+}
+export declare const resources: RegisteredResource[];

package/dist/resources/registry.js

@@ -0,0 +1,33 @@
+import { readFile } from 'node:fs/promises';
+import { getResourceContracts } from '../tools/contracts.js';
+const conceptFilesByUri = {
+    'besales://concepts/icp': 'icp.md',
+    'besales://concepts/triggers': 'triggers.md',
+    'besales://concepts/sandbox': 'sandbox.md',
+    'besales://concepts/handoff': 'handoff.md',
+    'besales://concepts/external-execution': 'external-execution.md',
+};
+function conceptUrl(fileName) {
+    return new URL(`./concepts/${fileName}`, import.meta.url);
+}
+function createResource(contract) {
+    const fileName = conceptFilesByUri[contract.uri];
+    if (!fileName) {
+        throw new Error(`Concept resource file mapping not found: ${contract.uri}`);
+    }
+    return {
+        uri: contract.uri,
+        name: contract.name,
+        description: contract.description,
+        mimeType: contract.mimeType,
+        async read() {
+            return {
+                uri: contract.uri,
+                mimeType: contract.mimeType,
+                text: await readFile(conceptUrl(fileName), 'utf-8'),
+            };
+        },
+    };
+}
+export const resources = getResourceContracts().map(createResource);
+//# sourceMappingURL=registry.js.map

package/dist/resources/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/resources/registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAI5C,OAAO,EAAE,oBAAoB,EAAyB,MAAM,uBAAuB,CAAC;AAMpF,MAAM,iBAAiB,GAAqC;IAC1D,wBAAwB,EAAE,QAAQ;IAClC,6BAA6B,EAAE,aAAa;IAC5C,4BAA4B,EAAE,YAAY;IAC1C,4BAA4B,EAAE,YAAY;IAC1C,uCAAuC,EAAE,uBAAuB;CACjE,CAAC;AAEF,SAAS,UAAU,CAAC,QAAgB;IAClC,OAAO,IAAI,GAAG,CAAC,cAAc,QAAQ,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC5D,CAAC;AAED,SAAS,cAAc,CAAC,QAA0B;IAChD,MAAM,QAAQ,GAAG,iBAAiB,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;IAEjD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,4CAA4C,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC;IAC9E,CAAC;IAED,OAAO;QACL,GAAG,EAAE,QAAQ,CAAC,GAAG;QACjB,IAAI,EAAE,QAAQ,CAAC,IAAI;QACnB,WAAW,EAAE,QAAQ,CAAC,WAAW;QACjC,QAAQ,EAAE,QAAQ,CAAC,QAAQ;QAC3B,KAAK,CAAC,IAAI;YACR,OAAO;gBACL,GAAG,EAAE,QAAQ,CAAC,GAAG;gBACjB,QAAQ,EAAE,QAAQ,CAAC,QAAQ;gBAC3B,IAAI,EAAE,MAAM,QAAQ,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;aACpD,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,SAAS,GAAyB,oBAAoB,EAAE,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC"}