manage-bx24-template-mcp

bx24-template-mcp — Agent Skill

Last reviewed: 2026-06-14

You are working on a Bitrix24 MCP server built on Nuxt + @nuxtjs/mcp-toolkit. Read this before making changes.

Project context

• Repo: https://github.com/bitrix24/templates-mcp
• Prod: <YOUR_PROD_URL>/mcp — replace with your deployed instance URL
• Stack: Nuxt 4 (Nitro node-server), @nuxtjs/mcp-toolkit, @bitrix24/b24jssdk-nuxt
• Auth to Bitrix24: incoming webhook (default), or OAuth 2.0 multi-tenant (opt-in, landed — NUXT_BITRIX24_OAUTH_ENABLED)
• Auth from Claude to us: Bearer token via middleware
• Deployment: Docker behind nginx-proxy + acme-companion on shared proxy-net network. CI builds and pushes the image to GHCR on v* tag; the operator deploys via Watchtower in monitor-only mode by default (it notifies on a new :latest but does NOT restart — opt into auto-apply by removing WATCHTOWER_MONITOR_ONLY) or via make redeploy on the host (manual)
• Dependency updates: npm & GitHub Actions — Renovate Bot (see renovate.json); Dockerfile base images — Dependabot; docker-compose infra images — Renovate's docker-compose manager (see renovate.json). Transitive-dependency security advisories are patched manually via overrides in pnpm-workspace.yaml (pnpm v11 location) — Dependabot/Renovate don't open PRs for nested deps. A blocking pnpm audit --audit-level=moderate CI job guards against regressions.
• License: MIT

Ground rules

1. One tool per file in server/mcp/tools/<group>/<name>.ts. Discovery is automatic.
2. Never call Bitrix24 directly. Always go through useBitrix24Tenant() (the OAuth-aware dispatcher in ~/server/utils/bitrix24-tenant — see ../../docs/OAUTH-DESIGN.md §6). With NUXT_BITRIX24_OAUTH_ENABLED=false (the production default) it falls back to the webhook singleton, so behaviour is byte-identical to a direct useBitrix24() call. When the flag is on, the same call resolves to a per-tenant B24OAuth from the request-scoped ALS. Never call useBitrix24() directly from a tool handler — it bypasses the dispatcher and pins the tool to webhook forever. From the dispatcher result go through the typed helpers in server/utils/sdk-helpers.ts: callV2<T>(b24, method, params, errorContext) — the default for classic methods (tasks.task.add/list/update/ + the seven lifecycle verbs, user.*, task.commentitem.*, …), callV3<T>(…) — only for methods that are v3-only (currently tasks.task.get, tasks.task.result.*), and batchV2<T> / batchV3<T>(b24, calls, errorContext) for bulk operations. See the transport-convention block at the top of sdk-helpers.ts for how to pick v2 vs v3. The helpers own the isSuccess / getErrorMessages / transport-error funnel — tool handlers stay short and uniform. Calling b24.actions.*.{call,batch}.make directly from a tool handler is forbidden (it duplicates that funnel and drifts over time); the deprecated b24.callMethod is doubly forbidden — it disappears in SDK 2.0. See adding-tools.md for the canonical template.
3. Every tool must have a unit test in tests/unit/tools/<group>/<name>.test.ts with the Bitrix24 client mocked.
4. Every Zod field must have .describe() — the LLM reads it at runtime.
5. No secrets in code or tests. Use useRuntimeConfig() and .env. When you add/rename/remove a NUXT_* / NITRO_* variable, change the default port or /mcp endpoint, change the connector auth header name/format, alter required webhook scopes, or add a tool needing upfront-seeded portal data, also update the manual-QA scaffold at ../run-manual-qa/references/issue-scaffold.md in the same PR — it mirrors these structural facts. A CI gate enforces the .env.example ↔ scaffold pairing.
6. Operators talk in names, not ids. When a tool needs a responsibleId / userId / similar, resolve from a name first via b24_user_find. The decision tree:
   1. Run b24_user_find { query: "<name from the operator>" }.
   2. 0 matches → tell the operator nobody matched and ask for a fuller name or last name.
   3. 1 match → use that user's id. No further questions.
   4. N > 1 matches → ask the operator to disambiguate by last name (and position / department if last names also collide). Only ask for a numeric id as the last resort if natural-language disambiguation fails.
7. Default to REST API v2; reach for v3 only where the method is v3-only. Bitrix24's migration to rest-v3 is gradual and will take a long time, so classic methods (tasks.task.add/list/update/ + the seven lifecycle verbs, user.*, task.commentitem.*, task.checklistitem.*, task.elapseditem.*, task.dependence.* — modify only) all go through callV2/batchV2. The two transports are NOT interchangeable: a classic method on v3 fails with UNKNOWNDTOPROPERTYEXCEPTION (wrong field casing) or "restApi:v3 not support method". Use v3 (callV3; apidocs URLs containing rest-v3/ or /rest/api/, camelCase DTOs) ONLY for methods that have no working v2 form — currently tasks.task.get and tasks.task.result.*. Dependency read-back is unavailable: task.item.getdependson is documented as deprecated upstream and the live-portal smoke (issue #33, 2026-05) confirmed it no longer returns predecessors; tasks.task.get does not expose a dependsOn field via any documented select. No tool ships for this — operators inspect dependencies via the Bitrix24 UI until upstream restores a read path. Bitrix24's v3 tasks.template.checklist.* is for task templates only; it does NOT replace task.checklistitem.* for actual tasks. When unsure which transport a method needs, check apidocs (a /rest/api/ URL + camelCase fields = v3) and default to v2 otherwise.
8. Read the SDK before reinventing it. Before adding rate limiting, retry, logging, request inspection, or any other cross-cutting concern around Bitrix24 calls — read @bitrix24/b24jssdk's dist/esm/index.d.ts for first-class extension points. The SDK already ships a leaky-bucket RestrictionManager (configured via setRestrictionManagerParams + ParamsFactory), retry with adaptive delay, structured logging (setLogger), and getStats(). Monkey-patching is forbidden (see "Things you must NOT do" below). When in doubt, search the .d.ts for set* / add* / on* / *Manager / *Factory — that's where the hooks live.
9. Every destructive tool requires an explicit confirmDelete: true from the agent (UNIVERSAL gate). Deletion is irreversible from the MCP's side — Bitrix24 does not surface a "trash" or "undo" for the entities we expose. The rule applies to ANY tool whose primary effect is to wipe an existing record — whether the trailing action is _delete (most common), _remove (removes a link / relationship without deleting either endpoint, e.g. b24_task_dependency_remove), or any future synonym. To prevent LLM mis-interpretation ("посмотри запись 5" → tool ending in _delete instead of _list), every such tool MUST add a confirmDelete: boolean field to its Zod schema and refuse with Bitrix24ToolError code DELETE_NEEDS_CONFIRM unless the agent set it to true. The error message MUST name the target(s) so the agent shows the operator what they're agreeing to. Applies to BOTH single and batch — the confirm is per-call, not per-id, and the agent MUST receive explicit operator agreement (the operator says "да, удали"; "посмотри" is not consent) before setting the flag — even in batch. Auto-confirming defeats the gate and counts as a Rule #9 violation. The shared schema fragment lives at server/utils/define-action-tool.ts (confirmDeleteSchema()); use it directly to keep wording uniform across delete tools. The shared gate assertConfirmedDelete(toolName, targetDescription, confirmed) lives in the same file (closes #32) — call it from every *_delete / *_remove tool handler instead of re-implementing the refusal; each callsite formats its own targetDescription so the LLM sees a domain-specific message. Compliant tools: b24_task_elapsed_time_delete (PR #28), b24_task_result_delete (PR #31), b24_task_checklist_item_delete (PR #31; stacks with Rule #10 below), b24_task_dependency_remove (PR-C).