mcpb/

Bitrix24 CRM: Desktop Extension (.mcpb)

Packages ../server.py as a one-click desktop extension so it can be shared with the team through Organization settings → Connectors → Add → Custom → Desktop, instead of hand-installing a .env on each machine.

Why this is the better distribution path:

• The webhook secret moves to the OS keychain. Each person enters their own webhook URL at install (user_config.webhook_url, sensitive: true); Claude Desktop stores it securely and injects it as BITRIX_WEBHOOK_URL. No plaintext .env to copy around or chmod 600.
• Central control. Owners upload the bundle to the org and gate installs with the Desktop extension allowlist (only allowlisted extensions can be installed). That's the "deny anyone outside the org" lever.
• One-click install for members, with a config UI for every setting.

Runtime model (uv): why this bundle is Python-agnostic

Since v1.15.0 this extension uses the MCPB uv runtime (server.type: "uv", manifest_version: 0.4). Dependencies are declared in pyproject.toml, not bundled as wheels. At install/first run, the host (Claude Desktop) runs the server via:

uv run --directory <ext-dir> src/server.py

uv resolves the dependencies (including native ones like pydantic-core) against a compatible Python it provisions itself, per platform and CPU. That means:

• No pinned Python. Works on Python >=3.10; there is no cp312-only ABI lock. uv fetches a matching interpreter if the machine doesn't have one.
• No dependence on the user's python being on PATH. This is what fixes the Windows "Server disconnected" failures (Microsoft Store python stub, wrong version, or ABI mismatch).
• One universal bundle for macOS, Windows, and Linux (Intel + ARM), ~100 KB. It can be built on any OS: no per-platform builds, no cross-fetching wheels.

Requirement: the member's Claude Desktop must support uv-type extensions (manifest 0.4). Current app builds do, and the host provides/manages uv. If a machine somehow can't run the extension, the manual install (venv + .env, see the top-level README) is the fallback, with the same server.

Build

cd mcpb
./build.sh        # → bitrix24-crm-<version>.mcpb  (universal)

build.sh copies ../server.py → src/server.py, then mcpb validate + mcpb pack. .mcpbignore keeps .venv/, caches, docs, and old artifacts out of the package. Only manifest.json, pyproject.toml, .mcpbignore, build.sh, and this README are committed; src/, .venv/, and *.mcpb are build/runtime artifacts (gitignored).

Versioning for org uploads

The org rejects an upload whose version is not greater than what's stored (dxt_version_not_greater). Bump version in both manifest.json and pyproject.toml, and keep them in step with the server's VERSION in ../server.py, for every upload.

Settings exposed at install (user_config)

Data (logs + schema snapshots) is written to BITRIX_DATA_DIR so it survives extension updates (the install dir is replaced on update).

Deploy to the org

1. Build the .mcpb (above).
2. As an Owner/Primary Owner: Organization settings → Connectors → Add → Custom → Desktop, upload the .mcpb.
3. Turn on Desktop extension allowlist and add this extension so the team can install it (and only what you allow).
4. Members install it from Claude Desktop and enter their own webhook URL.

Bump version in manifest.json and pyproject.toml (in step with the server) when you ship an update.