@besales/mcp 0.1.0

package/dist/types/api-contract.gen.js

@@ -0,0 +1,6 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+export {};
+//# sourceMappingURL=api-contract.gen.js.map

package/dist/types/api-contract.gen.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-contract.gen.js","sourceRoot":"","sources":["../../src/types/api-contract.gen.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/utils/logger.d.ts

@@ -0,0 +1,2 @@
+import pino from 'pino';
+export declare const logger: pino.Logger<never, boolean>;

package/dist/utils/logger.js

@@ -0,0 +1,13 @@
+import pino from 'pino';
+export const logger = pino({
+    level: process.env.LOG_LEVEL ?? (process.env.NODE_ENV === 'test' ? 'silent' : 'info'),
+    redact: [
+        'api_key',
+        '*.api_key',
+        '*.*.api_key',
+        'apiKey',
+        '*.apiKey',
+        '*.*.apiKey',
+    ],
+}, pino.destination(2));
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAC;AAExB,MAAM,CAAC,MAAM,MAAM,GAAG,IAAI,CACxB;IACE,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC;IACrF,MAAM,EAAE;QACN,SAAS;QACT,WAAW;QACX,aAAa;QACb,QAAQ;QACR,UAAU;QACV,YAAY;KACb;CACF,EACD,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CACpB,CAAC"}

package/dist/utils/mask.d.ts

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

package/dist/utils/mask.js

@@ -0,0 +1,7 @@
+export function maskApiKey(apiKey) {
+    if (apiKey.length < 12) {
+        return '***';
+    }
+    return `${apiKey.slice(0, 8)}...`;
+}
+//# sourceMappingURL=mask.js.map

package/dist/utils/mask.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mask.js","sourceRoot":"","sources":["../../src/utils/mask.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,UAAU,CAAC,MAAc;IACvC,IAAI,MAAM,CAAC,MAAM,GAAG,EAAE,EAAE,CAAC;QACvB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC;AACpC,CAAC"}

package/docs/host-setup.md

@@ -0,0 +1,256 @@
+# MCP Host Setup Runbook
+
+This runbook covers local development setup for `@besales/mcp` in the MCP hosts
+we support during v1.5 validation: MCP Inspector, Claude Desktop, Claude Code,
+and Codex CLI.
+
+## Scope
+
+`besales-mcp` is a thin MCP server for Animaly v1.5. It never calls
+`prompt-services` directly. Every tool call goes through `ai-aniomaly`
+`/api/v2/*`, and `ai-aniomaly` decides whether the operation is internal or
+external.
+
+External execution is host-neutral:
+
+1. The host calls a `*_get_instructions` tool.
+2. `ai-aniomaly` creates an operation request and returns stages.
+3. The host/model executes the stages locally.
+4. The host calls the matching `*_submit` tool.
+
+Claude Desktop, Claude Code, and Codex CLI all use this same two-step MCP flow.
+
+## Local Preconditions
+
+Run these from `/Users/peresvets/apps/animaly/besales-mcp`.
+
+```bash
+yarn install
+yarn build
+```
+
+For live local API testing, `ai-aniomaly` must be running on port `3000` and the
+v1.5 migrations must already be applied:
+
+```bash
+curl -fsS http://localhost:3000/health
+curl -fsS http://localhost:3000/.well-known/jwks.json
+```
+
+Use this base URL for local host configs:
+
+```bash
+export BESALES_API_BASE_URL=http://localhost:3000/api/v2
+```
+
+`prompt-services` is not a host precondition. Hosts talk only to `besales-mcp`,
+and `besales-mcp` talks only to `ai-aniomaly`.
+
+For production users, omit `BESALES_API_BASE_URL`. The package defaults to
+`https://app.besales.ai/api/v2`.
+
+## Credentials
+
+Live tool calls require an MCP API key stored in the local macOS keychain:
+
+```bash
+BESALES_API_BASE_URL=http://localhost:3000/api/v2 node bin/besales-mcp.js connect
+BESALES_API_BASE_URL=http://localhost:3000/api/v2 node bin/besales-mcp.js status
+```
+
+The `connect` command opens the browser and completes
+`/api/v2/auth/mcp-connect` through the loopback callback. Use `disconnect` to
+clear credentials:
+
+```bash
+BESALES_API_BASE_URL=http://localhost:3000/api/v2 node bin/besales-mcp.js disconnect
+```
+
+The connected workspace is stored alongside the API key. Workspace-level tools
+default to that workspace; users should not be asked to provide `workspace_id`.
+To switch workspaces, disconnect, switch or create the desired workspace in the
+web app, then connect again.
+
+For MCP protocol smoke without live auth, use the local mock API:
+
+```bash
+yarn dev:mock
+yarn dev:mock:seed
+BESALES_API_BASE_URL=http://127.0.0.1:3100/api/v2 node bin/besales-mcp.js
+```
+
+Clear mock credentials after the smoke:
+
+```bash
+yarn dev:mock:clear
+```
+
+## MCP Inspector
+
+Inspector is the first check because it verifies the MCP protocol without IDE
+state.
+
+```bash
+BESALES_API_BASE_URL=http://localhost:3000/api/v2 \
+  yarn dlx @modelcontextprotocol/inspector node bin/besales-mcp.js
+```
+
+Headless count checks:
+
+```bash
+BESALES_API_BASE_URL=http://localhost:3000/api/v2 \
+  yarn dlx @modelcontextprotocol/inspector --cli --method tools/list \
+  node bin/besales-mcp.js
+
+BESALES_API_BASE_URL=http://localhost:3000/api/v2 \
+  yarn dlx @modelcontextprotocol/inspector --cli --method resources/list \
+  node bin/besales-mcp.js
+```
+
+Expected:
+
+- 31 tools are listed.
+- 5 resources are listed.
+- `besales://concepts/external-execution` opens.
+- A direct tool, for example `besales_icp_create`, reaches `ai-aniomaly`.
+- An external pair returns instructions and accepts submit.
+
+For mock-only protocol checks, point Inspector at `http://127.0.0.1:3100/api/v2`
+after `yarn dev:mock` and `yarn dev:mock:seed`.
+
+## Claude Desktop
+
+Install the local server entry:
+
+```bash
+yarn install:claude-desktop
+```
+
+The installer writes this entry to
+`~/Library/Application Support/Claude/claude_desktop_config.json` and keeps a
+timestamped backup:
+
+```json
+{
+  "mcpServers": {
+    "besales": {
+      "command": "/absolute/path/to/node",
+      "args": ["/Users/peresvets/apps/animaly/besales-mcp/bin/besales-mcp.js"],
+      "env": {
+        "BESALES_API_BASE_URL": "http://localhost:3000/api/v2"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop after changing the config. Then open the MCP/server view
+and verify `besales` is connected.
+
+Smoke:
+
+1. Ask Claude Desktop to list available Besales tools.
+2. Call `besales_icp_create` against a test workspace.
+3. Call one external pair, for example
+   `besales_prompt_generate_get_instructions`, execute the returned stages
+   locally, and submit with `besales_prompt_generate_submit`.
+
+## Claude Code
+
+If `claude` is on `PATH`, add the server at user scope:
+
+```bash
+claude mcp add --scope user \
+  -e BESALES_API_BASE_URL=http://localhost:3000/api/v2 \
+  -- besales node /Users/peresvets/apps/animaly/besales-mcp/bin/besales-mcp.js
+```
+
+If the app-managed binary is not on `PATH`, use the absolute Claude Code binary
+or edit `~/.claude.json` with the same `mcpServers.besales` entry.
+
+Verify:
+
+```bash
+claude mcp list
+```
+
+Start a fresh Claude Code session from `/Users/peresvets/apps/animaly`, run
+`/mcp`, and check that `besales` is connected. Then run the same direct tool and
+external-pair smoke as Claude Desktop.
+
+## Codex CLI
+
+Codex CLI manages stdio MCP servers through `codex mcp`.
+
+```bash
+codex mcp add besales \
+  --env BESALES_API_BASE_URL=http://localhost:3000/api/v2 \
+  -- node /Users/peresvets/apps/animaly/besales-mcp/bin/besales-mcp.js
+```
+
+Equivalent `~/.codex/config.toml` shape:
+
+```toml
+[mcp_servers.besales]
+command = "node"
+args = ["/Users/peresvets/apps/animaly/besales-mcp/bin/besales-mcp.js"]
+
+[mcp_servers.besales.env]
+BESALES_API_BASE_URL = "http://localhost:3000/api/v2"
+```
+
+Verify:
+
+```bash
+codex mcp list
+codex mcp get besales
+```
+
+Start a new Codex CLI session after adding the server. Confirm `besales_*` tools
+are present, then run:
+
+1. One direct tool (`besales_icp_create`).
+2. One external pair (`*_get_instructions` then matching `*_submit`).
+
+For the ICP analysis pair, `besales_icp_analysis_submit` personas must include
+`segment_id`. Use either an existing ICP segment id or the `id` of a segment in
+the same submit payload.
+
+Codex App uses the same Codex MCP configuration, but an already-running desktop
+session may need an app/session restart before new tools appear.
+
+### Codex App Deferred Tool Discovery
+
+Codex App can defer MCP tool schemas until the model searches for them. This is
+host behavior, not a `besales-mcp` server problem: `codex mcp list/get besales`
+and MCP Inspector `tools/list` are still the source checks for whether the
+server is installed and exposing all 31 tools.
+
+User-facing prompts must stay natural. Users should ask for the business action,
+for example:
+
+```text
+Use besales MCP to create an ICP and run the ICP analysis external flow.
+```
+
+The assistant must not ask the user to mention `tool_search`. If a requested
+`besales_*` tool is not already visible in Codex App, the assistant should run
+tool discovery itself by searching for `besales`, the operation name, or the
+specific tool name, then call the discovered tool. Do not conclude that a
+`besales_*` tool is unavailable until deferred discovery has been attempted.
+
+## Smoke Matrix
+
+Use this matrix for local validation before staging/prod checks.
+
+| Host | Config check | Protocol check | Direct tool | External pair |
+|---|---|---|---|---|
+| MCP Inspector | command launches | 31 tools / 5 resources | `besales_icp_create` | instructions -> submit |
+| Claude Desktop | config JSON has `besales` | server connected | `besales_icp_create` | instructions -> submit |
+| Claude Code | `claude mcp list` has `besales` | `/mcp` connected | `besales_icp_create` | instructions -> submit |
+| Codex CLI | `codex mcp list` has `besales` | new session sees tools | `besales_icp_create` | instructions -> submit |
+
+Do not mark the ROADMAP manual E2E acceptance from mock-only checks. Mock mode
+only verifies host wiring and MCP protocol shape. ROADMAP acceptance requires a
+live `ai-aniomaly` backend, real stored MCP credentials, and successful direct
+plus external tool calls.

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@besales/mcp",
+  "version": "0.1.0",
+  "description": "Model Context Protocol server for Animaly / Besales",
+  "license": "MIT",
+  "homepage": "https://github.com/be-sales/mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/be-sales/mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/be-sales/mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "besales",
+    "animaly",
+    "claude",
+    "codex"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "bin",
+    "scripts",
+    "docs",
+    "README.md"
+  ],
+  "bin": {
+    "besales-mcp": "bin/besales-mcp.js"
+  },
+  "scripts": {
+    "build": "tsc && mkdir -p dist/schemas dist/resources/concepts && cp src/schemas/mcp-tools.json dist/schemas/mcp-tools.json && cp src/resources/concepts/*.md dist/resources/concepts/",
+    "start": "node bin/besales-mcp.js",
+    "dev:mock": "node scripts/mock-api-server.js",
+    "dev:mock:seed": "node scripts/mock-credentials.js seed",
+    "dev:mock:clear": "node scripts/mock-credentials.js clear",
+    "install:claude-desktop": "node scripts/install-claude-desktop.js",
+    "prepack": "yarn build",
+    "prepublishOnly": "yarn lint:errors && yarn test && yarn build",
+    "test": "vitest run",
+    "lint:fix": "eslint src bin scripts eslint.config.js --fix",
+    "lint:errors": "eslint src bin scripts eslint.config.js",
+    "types:gen:api": "mkdir -p src/types && openapi-typescript ../docs/specs/v2/contracts/openapi-besales-api.yaml -o src/types/api-contract.gen.ts",
+    "types:gen:mcp": "mkdir -p src/schemas && cp ../docs/specs/v2/contracts/mcp-tools.json src/schemas/mcp-tools.json"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "packageManager": "yarn@4.13.0",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "axios": "^1.16.0",
+    "keytar": "^7.9.0",
+    "open": "^11.0.0",
+    "pino": "^10.3.1",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.7.0",
+    "@typescript-eslint/eslint-plugin": "^8.59.3",
+    "@typescript-eslint/parser": "^8.59.3",
+    "eslint": "^10.3.0",
+    "openapi-typescript": "^7.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^4.1.6"
+  }
+}

package/scripts/install-claude-desktop.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+
+import { copyFile, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const CLAUDE_CONFIG_PATH = join(
+  homedir(),
+  'Library/Application Support/Claude/claude_desktop_config.json',
+);
+const LOCAL_API_BASE_URL = 'http://localhost:3000/api/v2';
+const packageRoot = dirname(fileURLToPath(new URL('../package.json', import.meta.url)));
+const binPath = join(packageRoot, 'bin/besales-mcp.js');
+
+function timestamp() {
+  return new Date().toISOString().replace(/[:.]/g, '-');
+}
+
+function ensureObject(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return {};
+  }
+
+  return value;
+}
+
+async function readConfig() {
+  if (!existsSync(CLAUDE_CONFIG_PATH)) {
+    return {};
+  }
+
+  const text = await readFile(CLAUDE_CONFIG_PATH, 'utf-8');
+
+  if (!text.trim()) {
+    return {};
+  }
+
+  return ensureObject(JSON.parse(text));
+}
+
+async function install() {
+  await mkdir(dirname(CLAUDE_CONFIG_PATH), { recursive: true });
+
+  if (existsSync(CLAUDE_CONFIG_PATH)) {
+    const backupPath = `${CLAUDE_CONFIG_PATH}.backup-${timestamp()}`;
+    await copyFile(CLAUDE_CONFIG_PATH, backupPath);
+    console.log(`Backed up Claude Desktop config to ${backupPath}`);
+  }
+
+  const config = await readConfig();
+  const mcpServers = ensureObject(config.mcpServers);
+
+  mcpServers.besales = {
+    command: process.execPath,
+    args: [binPath],
+    env: {
+      BESALES_API_BASE_URL: LOCAL_API_BASE_URL,
+    },
+  };
+  config.mcpServers = mcpServers;
+
+  const tempPath = `${CLAUDE_CONFIG_PATH}.tmp-${process.pid}`;
+  await writeFile(tempPath, `${JSON.stringify(config, null, 2)}\n`, 'utf-8');
+  await rename(tempPath, CLAUDE_CONFIG_PATH);
+
+  console.log(`Installed besales MCP config at ${CLAUDE_CONFIG_PATH}`);
+  console.log(`Node: ${process.execPath}`);
+  console.log(`Command args: ${binPath}`);
+}
+
+install().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`Failed to install Claude Desktop config: ${message}`);
+  process.exit(1);
+});

package/scripts/mock-api-server.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+import { createServer } from 'node:http';
+
+const port = Number(process.env.BESALES_MOCK_API_PORT ?? 3100);
+
+const server = createServer((request, response) => {
+  const url = new URL(request.url ?? '/', `http://127.0.0.1:${port}`);
+
+  if (!url.pathname.startsWith('/api/v2/')) {
+    response.writeHead(404, { 'Content-Type': 'application/json' });
+    response.end(JSON.stringify({ message: 'Mock endpoint not found' }));
+    return;
+  }
+
+  let body = '';
+  request.on('data', (chunk) => {
+    body += String(chunk);
+  });
+  request.on('end', () => {
+    let parsedBody;
+    try {
+      parsedBody = body ? JSON.parse(body) : undefined;
+    } catch {
+      response.writeHead(400, { 'Content-Type': 'application/json' });
+      response.end(JSON.stringify({ message: 'Malformed JSON body' }));
+      return;
+    }
+
+    const isInstructions = url.pathname.endsWith('/instructions');
+    const isSubmit = url.pathname.endsWith('/submit') || url.pathname.includes('/submit');
+
+    response.writeHead(isSubmit ? 201 : 200, { 'Content-Type': 'application/json' });
+    response.end(
+      JSON.stringify({
+        mock: true,
+        method: request.method,
+        path: url.pathname,
+        receivedBody: parsedBody,
+        operationId: '00000000-0000-4000-8000-000000000099',
+        stages: isInstructions
+          ? [
+              {
+                name: 'mock_stage',
+                systemPrompt: 'Mock system prompt',
+                schema: { type: 'object' },
+              },
+            ]
+          : undefined,
+      }),
+    );
+  });
+});
+
+server.listen(port, '127.0.0.1', () => {
+  console.log(`Mock Animaly API listening at http://127.0.0.1:${port}/api/v2`);
+});

package/scripts/mock-credentials.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import * as keytar from 'keytar';
+
+const SERVICE = '@besales/mcp';
+const API_KEY_ACCOUNT = 'api_key';
+const WORKSPACE_ID_ACCOUNT = 'workspace_id';
+const DEFAULT_MOCK_API_KEY = 'mcp_mock_key_for_local_inspector';
+const DEFAULT_MOCK_WORKSPACE_ID = '00000000-0000-4000-8000-000000000001';
+const WARNING_MESSAGE = [
+  'Warning: this command uses the same keytar entries as a real besales-mcp connection.',
+  'It can overwrite or clear local production credentials for this user.',
+].join(' ');
+
+const command = process.argv[2] ?? 'seed';
+const apiKey = process.env.BESALES_MOCK_API_KEY ?? DEFAULT_MOCK_API_KEY;
+const workspaceId = process.env.BESALES_MOCK_WORKSPACE_ID ?? DEFAULT_MOCK_WORKSPACE_ID;
+
+if (command === 'seed') {
+  console.warn(WARNING_MESSAGE);
+  await keytar.setPassword(SERVICE, WORKSPACE_ID_ACCOUNT, workspaceId);
+  await keytar.setPassword(SERVICE, API_KEY_ACCOUNT, apiKey);
+  console.log(`Seeded mock credentials for workspace ${workspaceId}`);
+} else if (command === 'clear') {
+  console.warn(WARNING_MESSAGE);
+  await Promise.all([
+    keytar.deletePassword(SERVICE, API_KEY_ACCOUNT),
+    keytar.deletePassword(SERVICE, WORKSPACE_ID_ACCOUNT),
+  ]);
+  console.log('Cleared mock credentials');
+} else {
+  console.error(`Unknown command: ${command}`);
+  console.error('Usage: node scripts/mock-credentials.js [seed|clear]');
+  process.exitCode = 1;
+}