README.md

mcpb/README.md

1. # Bitrix24 CRM: Desktop Extension (`.mcpb`)
3. Packages `../server.py` as a one-click **desktop extension** so it can be shared
4. with the team through **Organization settings → Connectors → Add → Custom →
5. Desktop**, instead of hand-installing a `.env` on each machine.
7. Why this is the better distribution path:
8. - **The webhook secret moves to the OS keychain.** Each person enters their own
9. webhook URL at install (`user_config.webhook_url`, `sensitive: true`); Claude
10. Desktop stores it securely and injects it as `BITRIX_WEBHOOK_URL`. No plaintext
11. `.env` to copy around or `chmod 600`.
12. - **Central control.** Owners upload the bundle to the org and gate installs with
13. the **Desktop extension allowlist** (only allowlisted extensions can be
14. installed). That's the "deny anyone outside the org" lever.
15. - **One-click install** for members, with a config UI for every setting.
17. ## Runtime model (uv): why this bundle is Python-agnostic
19. Since **v1.15.0** this extension uses the MCPB **`uv` runtime** (`server.type:
20. "uv"`, `manifest_version: 0.4`). Dependencies are declared in
21. [`pyproject.toml`](pyproject.toml), **not** bundled as wheels. At install/first
22. run, the host (Claude Desktop) runs the server via:
24. ```
25. uv run --directory <ext-dir> src/server.py
26. ```
28. `uv` resolves the dependencies (including native ones like `pydantic-core`)
29. against a **compatible Python it provisions itself**, per platform and CPU. That
30. means:
32. - **No pinned Python.** Works on Python `>=3.10`; there is no `cp312`-only ABI
33. lock. uv fetches a matching interpreter if the machine doesn't have one.
34. - **No dependence on the user's `python` being on PATH.** This is what fixes the
35. Windows *"Server disconnected"* failures (Microsoft Store `python` stub, wrong
36. version, or ABI mismatch).
37. - **One universal bundle** for macOS, Windows, and Linux (Intel + ARM), ~100 KB.
38. It can be built on any OS: no per-platform builds, no cross-fetching wheels.
40. **Requirement:** the member's Claude Desktop must support uv-type extensions
41. (manifest 0.4). Current app builds do, and the host provides/manages `uv`. If a
42. machine somehow can't run the extension, the **manual install** (venv + `.env`,
43. see the top-level README) is the fallback, with the same server.
45. ## Build
47. ```bash
48. cd mcpb
49. ./build.sh # → bitrix24-crm-<version>.mcpb (universal)
50. ```
52. `build.sh` copies `../server.py` → `src/server.py`, then `mcpb validate` +
53. `mcpb pack`. [`.mcpbignore`](.mcpbignore) keeps `.venv/`, caches, docs, and old
54. artifacts out of the package. Only `manifest.json`, `pyproject.toml`,
55. `.mcpbignore`, `build.sh`, and this README are committed; `src/`, `.venv/`, and
56. `*.mcpb` are build/runtime artifacts (gitignored).
58. ### Versioning for org uploads
59. The org rejects an upload whose `version` is not greater than what's stored
60. (`dxt_version_not_greater`). Bump `version` in **both** `manifest.json` and
61. `pyproject.toml`, and keep them in step with the server's `VERSION` in
62. `../server.py`, for every upload.
64. ## Settings exposed at install (`user_config`)
66. | Config | Env var | Default |
67. | ------ | ------- | ------- |
68. | Bitrix24 Webhook URL (sensitive) | `BITRIX_WEBHOOK_URL` | – (required) |
69. | Local timezone | `BITRIX_LOCAL_TZ` | America/Chicago |
70. | Enable writes | `BITRIX_WRITES` | on |
71. | Write-enabled deal funnels | `BITRIX_WRITE_FUNNELS` | `24,26,36` (categoryIds: 24 Partner Tier Upgrade, 26 Winback, 36 Quarterly Check-In Flow; names also accepted but break on rename) |
72. | Enable contact/company writes | `BITRIX_WRITE_PARTIES` | on |
73. | Call-log redaction mode | `BITRIX_LOG_ARGS` | redact |
74. | Enable local transcription | `BITRIX_TRANSCRIBE` | off |
75. | Data folder (logs + schema) | `BITRIX_DATA_DIR` | `~/.bitrix24-mcp` |
77. Data (logs + schema snapshots) is written to `BITRIX_DATA_DIR` so it survives
78. extension updates (the install dir is replaced on update).
80. ## Deploy to the org
82. 1. Build the `.mcpb` (above).
83. 2. As an Owner/Primary Owner: **Organization settings → Connectors → Add →
84. Custom → Desktop**, upload the `.mcpb`.
85. 3. Turn on **Desktop extension allowlist** and add this extension so the team can
86. install it (and only what you allow).
87. 4. Members install it from Claude Desktop and enter **their own** webhook URL.
89. Bump `version` in `manifest.json` and `pyproject.toml` (in step with the server)
90. when you ship an update.