mcbp 0.2.4__tar.gz

mcbp-0.2.4/.gitignore

@@ -0,0 +1,27 @@
+# Secrets — NEVER commit
+.env
+.env.*
+*.key
+*.pem
+*.crt
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+.venv-*/
+*.egg-info/
+dist/
+build/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# IDE / OS
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db

mcbp-0.2.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MCBP.PLUS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcbp-0.2.4/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.5
+Name: mcbp
+Version: 0.2.4
+Summary: Standalone MCP server exposing BAS MCBP_AI (mcbp.plus)
+Project-URL: Homepage, https://mcbp.plus
+Project-URL: Repository, https://github.com/kzavrazhnyi/mcbp-mcp-server
+Author: MCBP.PLUS
+License-Expression: MIT
+License-File: LICENSE
+Keywords: 1c,bas,erp,mcbp,mcp
+Requires-Python: >=3.11
+Requires-Dist: anyio>=4.0
+Requires-Dist: mcbp-core<0.2,>=0.1.1
+Requires-Dist: mcp>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.7; extra == 'dev'
+Requires-Dist: starlette>=0.40; extra == 'dev'
+Provides-Extra: http
+Requires-Dist: starlette>=0.40; extra == 'http'
+Requires-Dist: uvicorn>=0.30; extra == 'http'
+Description-Content-Type: text/markdown
+
+<!-- mcp-name: io.github.kzavrazhnyi/mcbp-ai -->
+
+# mcbp-ai — MCP server for BAS / 1C (MCBP+)
+
+Read your BAS (1C) database from any MCP client. Catalogs, documents, register balances and records,
+and the full configuration metadata tree — exposed as MCP tools over the `MCBP_AI` HTTP service.
+
+**Read-only by default.** None of the tools available out of the box modifies your data.
+
+**Model-agnostic.** MCP is a vendor-neutral standard, so this server works with **Claude Desktop /
+Code, ChatGPT desktop, Gemini, Microsoft and GitHub Copilot, Cursor, Windsurf, VS Code and Zed** —
+it serves `tools/list` and executes `tools/call` without knowing which model is asking. The
+transport is **stdio**, so the client launches the process locally; browser-based clients would
+need a remote HTTP server, which this one does not expose.
+
+> ### ⚠ This server needs a server-side component that is not in this repository
+>
+> `mcbp-ai` is a client for the **`MCBP_AI` HTTP service** — a BSL module (a common module plus an
+> HTTP service definition) that must be installed into your BAS/1C configuration through
+> Конфігуратор. **That module is licensed separately and is not part of this repository.**
+>
+> Without it this server starts, connects, and every route answers `404`. If you want to run it
+> against your own base, contact MCBP.PLUS to obtain the `MCBP_AI` module.
+>
+> The Python code here — the MCP adapter and the shared BAS client — is open source and complete.
+
+The MCBP+ configuration and the `MCBP_AI` service module are proprietary works of
+**[MCBP.PLUS](https://mcbp.plus)** and are distributed separately from this repository. This MIT
+licence covers the Python packages only.
+
+## Why this exists
+
+BAS/1C holds the data, but it is not reachable from an LLM: the platform speaks its own query
+language, metadata names are inherited Russian identifiers while synonyms are Ukrainian, and a raw
+OData feed is both heavy and hostile to a model (opaque errors, no self-correction path).
+
+`MCBP_AI` solves that on the BAS side — canonical English field names in list rows, compact
+responses, and errors that name the offending field verbatim so a model can fix its own call. This
+server is the thin MCP adapter in front of it.
+
+## Tools
+
+10 read tools are always registered. Three write tools appear only when `MCP_ALLOW_WRITE` is on.
+
+| Tool | What it does |
+|---|---|
+| `list_metadata` | Every object of a metadata kind (names + synonyms) — start here |
+| `describe_metadata` | Full attribute tree of one object, incl. tabular sections |
+| `search_catalog` | Substring search over a catalog by name |
+| `filter_catalog` | Filter/sort/aggregate a catalog by any field (`agg`, `groupby`) |
+| `get_documents` | Documents over a period, with filters, sorting and aggregation |
+| `get_schema` | Data structure of one document type |
+| `get_object` | **All** attribute values of one record + its tabular sections |
+| `get_register_balance` | Accumulation-register balance (native query) |
+| `get_register_records` | Raw rows of an information or accumulation register |
+| `health` | Service ping — reports whether the infobase key matches |
+| `write_object` *(gated)* | Create/update an object through MCBP Plus conversion rules |
+| `patch_object` *(gated)* | Update header attributes of an existing object natively |
+| `save_context` *(gated)* | Push a conversation turn upstream (skeleton) |
+
+The model is expected to walk `list_metadata → describe_metadata → search/filter → get_object`.
+Errors are deliberately not swallowed: an unknown field comes back as `BAD_PARAMETER` naming that
+field, which is how the model corrects itself.
+
+## Install
+
+Requires **Python 3.11+**.
+
+```bash
+pip install mcbp
+```
+
+## Configure
+
+### Claude Desktop
+
+`%APPDATA%\Claude\claude_desktop_config.json` (Windows) or
+`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
+
+```json
+{
+  "mcpServers": {
+    "mcbp-ai": {
+      "command": "python",
+      "args": ["-m", "mcbp_mcp_server"],
+      "env": {
+        "ONEC_BASE_URL": "http://host/base/hs/mcbp_ai",
+        "ONEC_USER": "ai_service",
+        "ONEC_PASSWORD": "***"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add mcbp-ai --env ONEC_BASE_URL=http://host/base/hs/mcbp_ai \
+                       --env ONEC_USER=ai_service \
+                       --env ONEC_PASSWORD=*** \
+                       -- python -m mcbp_mcp_server
+```
+
+## Environment
+
+| Variable | Required | Default | Purpose |
+|---|---|---|---|
+| `ONEC_BASE_URL` | yes | — | `http(s)://<host>/<base>/hs/mcbp_ai` — see the note below |
+| `ONEC_USER` | yes | — | HTTP Basic user of the BAS publication |
+| `ONEC_PASSWORD` | yes | — | Password. **May be empty**, but the variable must be present |
+| `ONEC_TIMEOUT` | no | `30` | Request timeout, seconds |
+| `ONEC_POOL_MAX` | no | `10` | Connection pool size |
+| `ONEC_VERIFY_SSL` | no | `1` | `0` for self-signed intranet publications |
+| `MCP_ALLOW_WRITE` | no | `0` | `1` enables the three write tools |
+
+### `ONEC_BASE_URL` — leave off the `/ai/v1`
+
+The client appends `/ai/v1/...` itself, so the base URL stops at the service name:
+
+```
+http://localhost/mybase/hs/mcbp_ai          ← correct
+http://localhost/mybase/hs/mcbp_ai/ai/v1/   ← also accepted (normalized away)
+```
+
+Note that the published path genuinely repeats the segment: `rootUrl` is `mcbp_ai` in `default.vrd`,
+and the service's own URL templates start with `ai/v1`.
+
+## Security
+
+- Read-only unless you deliberately set `MCP_ALLOW_WRITE=1`. The write tools are not merely hidden
+  — they are never registered, so they cannot be invoked.
+- Credentials live only in the MCP client's env block; nothing is written to disk by this server.
+- The BAS side adds its own checks: the publication's user rights, plus an infobase-key check. If
+  the key does not match, `health` reports `key: false` and every other route answers
+  `403 KEY_MISMATCH`.
+- `write_object` additionally requires the MCBP Plus extension and a configured conversion rule;
+  without one it returns `422 CONVERSION_NOT_CONFIGURED` and writes nothing.
+
+## Troubleshooting
+
+| Symptom | Cause |
+|---|---|
+| Every route `404`, `health` also fails | `ONEC_BASE_URL` wrong, or the `MCBP_AI` module is not installed in the base |
+| Every route `403 KEY_MISMATCH` | Infobase key mismatch — check `health`, fix the publication key |
+| `ONEC_PASSWORD is required` | The variable is absent. An empty value is fine; an absent one is not |
+| `501 PLUS_REQUIRED` | Only `write_object` raises it — that base has no MCBP Plus |
+| Model says a register is unreadable | Information registers have no `Ref`; use `get_register_records` |
+
+## License
+
+See `LICENSE`.

mcbp-0.2.4/README.md

@@ -0,0 +1,152 @@
+<!-- mcp-name: io.github.kzavrazhnyi/mcbp-ai -->
+
+# mcbp-ai — MCP server for BAS / 1C (MCBP+)
+
+Read your BAS (1C) database from any MCP client. Catalogs, documents, register balances and records,
+and the full configuration metadata tree — exposed as MCP tools over the `MCBP_AI` HTTP service.
+
+**Read-only by default.** None of the tools available out of the box modifies your data.
+
+**Model-agnostic.** MCP is a vendor-neutral standard, so this server works with **Claude Desktop /
+Code, ChatGPT desktop, Gemini, Microsoft and GitHub Copilot, Cursor, Windsurf, VS Code and Zed** —
+it serves `tools/list` and executes `tools/call` without knowing which model is asking. The
+transport is **stdio**, so the client launches the process locally; browser-based clients would
+need a remote HTTP server, which this one does not expose.
+
+> ### ⚠ This server needs a server-side component that is not in this repository
+>
+> `mcbp-ai` is a client for the **`MCBP_AI` HTTP service** — a BSL module (a common module plus an
+> HTTP service definition) that must be installed into your BAS/1C configuration through
+> Конфігуратор. **That module is licensed separately and is not part of this repository.**
+>
+> Without it this server starts, connects, and every route answers `404`. If you want to run it
+> against your own base, contact MCBP.PLUS to obtain the `MCBP_AI` module.
+>
+> The Python code here — the MCP adapter and the shared BAS client — is open source and complete.
+
+The MCBP+ configuration and the `MCBP_AI` service module are proprietary works of
+**[MCBP.PLUS](https://mcbp.plus)** and are distributed separately from this repository. This MIT
+licence covers the Python packages only.
+
+## Why this exists
+
+BAS/1C holds the data, but it is not reachable from an LLM: the platform speaks its own query
+language, metadata names are inherited Russian identifiers while synonyms are Ukrainian, and a raw
+OData feed is both heavy and hostile to a model (opaque errors, no self-correction path).
+
+`MCBP_AI` solves that on the BAS side — canonical English field names in list rows, compact
+responses, and errors that name the offending field verbatim so a model can fix its own call. This
+server is the thin MCP adapter in front of it.
+
+## Tools
+
+10 read tools are always registered. Three write tools appear only when `MCP_ALLOW_WRITE` is on.
+
+| Tool | What it does |
+|---|---|
+| `list_metadata` | Every object of a metadata kind (names + synonyms) — start here |
+| `describe_metadata` | Full attribute tree of one object, incl. tabular sections |
+| `search_catalog` | Substring search over a catalog by name |
+| `filter_catalog` | Filter/sort/aggregate a catalog by any field (`agg`, `groupby`) |
+| `get_documents` | Documents over a period, with filters, sorting and aggregation |
+| `get_schema` | Data structure of one document type |
+| `get_object` | **All** attribute values of one record + its tabular sections |
+| `get_register_balance` | Accumulation-register balance (native query) |
+| `get_register_records` | Raw rows of an information or accumulation register |
+| `health` | Service ping — reports whether the infobase key matches |
+| `write_object` *(gated)* | Create/update an object through MCBP Plus conversion rules |
+| `patch_object` *(gated)* | Update header attributes of an existing object natively |
+| `save_context` *(gated)* | Push a conversation turn upstream (skeleton) |
+
+The model is expected to walk `list_metadata → describe_metadata → search/filter → get_object`.
+Errors are deliberately not swallowed: an unknown field comes back as `BAD_PARAMETER` naming that
+field, which is how the model corrects itself.
+
+## Install
+
+Requires **Python 3.11+**.
+
+```bash
+pip install mcbp
+```
+
+## Configure
+
+### Claude Desktop
+
+`%APPDATA%\Claude\claude_desktop_config.json` (Windows) or
+`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
+
+```json
+{
+  "mcpServers": {
+    "mcbp-ai": {
+      "command": "python",
+      "args": ["-m", "mcbp_mcp_server"],
+      "env": {
+        "ONEC_BASE_URL": "http://host/base/hs/mcbp_ai",
+        "ONEC_USER": "ai_service",
+        "ONEC_PASSWORD": "***"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add mcbp-ai --env ONEC_BASE_URL=http://host/base/hs/mcbp_ai \
+                       --env ONEC_USER=ai_service \
+                       --env ONEC_PASSWORD=*** \
+                       -- python -m mcbp_mcp_server
+```
+
+## Environment
+
+| Variable | Required | Default | Purpose |
+|---|---|---|---|
+| `ONEC_BASE_URL` | yes | — | `http(s)://<host>/<base>/hs/mcbp_ai` — see the note below |
+| `ONEC_USER` | yes | — | HTTP Basic user of the BAS publication |
+| `ONEC_PASSWORD` | yes | — | Password. **May be empty**, but the variable must be present |
+| `ONEC_TIMEOUT` | no | `30` | Request timeout, seconds |
+| `ONEC_POOL_MAX` | no | `10` | Connection pool size |
+| `ONEC_VERIFY_SSL` | no | `1` | `0` for self-signed intranet publications |
+| `MCP_ALLOW_WRITE` | no | `0` | `1` enables the three write tools |
+
+### `ONEC_BASE_URL` — leave off the `/ai/v1`
+
+The client appends `/ai/v1/...` itself, so the base URL stops at the service name:
+
+```
+http://localhost/mybase/hs/mcbp_ai          ← correct
+http://localhost/mybase/hs/mcbp_ai/ai/v1/   ← also accepted (normalized away)
+```
+
+Note that the published path genuinely repeats the segment: `rootUrl` is `mcbp_ai` in `default.vrd`,
+and the service's own URL templates start with `ai/v1`.
+
+## Security
+
+- Read-only unless you deliberately set `MCP_ALLOW_WRITE=1`. The write tools are not merely hidden
+  — they are never registered, so they cannot be invoked.
+- Credentials live only in the MCP client's env block; nothing is written to disk by this server.
+- The BAS side adds its own checks: the publication's user rights, plus an infobase-key check. If
+  the key does not match, `health` reports `key: false` and every other route answers
+  `403 KEY_MISMATCH`.
+- `write_object` additionally requires the MCBP Plus extension and a configured conversion rule;
+  without one it returns `422 CONVERSION_NOT_CONFIGURED` and writes nothing.
+
+## Troubleshooting
+
+| Symptom | Cause |
+|---|---|
+| Every route `404`, `health` also fails | `ONEC_BASE_URL` wrong, or the `MCBP_AI` module is not installed in the base |
+| Every route `403 KEY_MISMATCH` | Infobase key mismatch — check `health`, fix the publication key |
+| `ONEC_PASSWORD is required` | The variable is absent. An empty value is fine; an absent one is not |
+| `501 PLUS_REQUIRED` | Only `write_object` raises it — that base has no MCBP Plus |
+| Model says a register is unreadable | Information registers have no `Ref`; use `get_register_records` |
+
+## License
+
+See `LICENSE`.

mcbp-0.2.4/deploy/README.md

@@ -0,0 +1,236 @@
+# Deploying `mcbp-ai` as a remote MCP server
+
+Runs the same server the stdio entry point runs, over Streamable HTTP. One process per BAS base.
+
+Two stages, and only the first is being done now:
+
+| | Stage 1 — internal network | Stage 2 — external server, public IP |
+|---|---|---|
+| Client reaches | the process, `http://`, directly | nginx, `https://` |
+| Process listens on | the LAN interface | `127.0.0.1` |
+| Access control | the network boundary, nothing else | TLS + token or IP allow-list in nginx |
+| Files used | `mcbp-mcp@.service`, `mcbp-mcp.env.example` | the same two + `nginx-mcp.conf` |
+
+Stage 2 is a config delta on top of stage 1, not a redeployment: same venv, same unit, same env
+files with three values changed. It is written out in section 6.
+
+## 0. Which clients can reach an internal endpoint
+
+The rule is **where the MCP client process runs**, not which model is behind it.
+
+- **Runs on a machine inside the network → works in stage 1.** Claude Code is the case at hand;
+  so is any in-house application that speaks MCP itself, whatever model it drives (OpenAI
+  included).
+- **Hosted connector surfaces → cannot work in stage 1.** claude.ai, Claude Desktop and ChatGPT
+  connectors do not connect from the user's machine: the provider's infrastructure does, from the
+  public internet (Anthropic's egress is `160.79.104.0/21`). Such a client cannot see an internal
+  host at all. That is architecture, not configuration — it changes only in stage 2.
+
+---
+
+# Stage 1: internal network
+
+## 1. Install
+
+```bash
+sudo useradd --system --home /opt/mcbp-mcp --shell /usr/sbin/nologin mcbp
+sudo mkdir -p /opt/mcbp-mcp && sudo chown mcbp:mcbp /opt/mcbp-mcp
+sudo -u mcbp python3.11 -m venv /opt/mcbp-mcp/.venv
+```
+
+The distribution is named `mcbp` and is published on **TestPyPI**. Release `0.2.0` must be
+uploaded there before this command can work — `mcbp-core` first, then `mcbp`; a published version
+is immutable, which is why the HTTP transport ships as a new version rather than a re-upload.
+
+```bash
+sudo -u mcbp /opt/mcbp-mcp/.venv/bin/pip install \
+  --index-url https://test.pypi.org/simple/ \
+  --extra-index-url https://pypi.org/simple/ \
+  "mcbp[http]==0.2.0"
+```
+
+- **`--extra-index-url https://pypi.org/simple/` is mandatory.** The runtime dependencies —
+  httpx, mcp, starlette, uvicorn — are not on TestPyPI, so resolution fails without it. That is
+  a property of TestPyPI, not a defect of the package.
+- **Pin the version.** A bare `mcbp[http]` resolves to whatever is newest on TestPyPI, which is
+  not always what was tested. `0.2.0` is the first release carrying the `mcbp-http` entry point
+  and the `http` extra; 0.1.0 predates the HTTP transport and gives a stdio-only server.
+- **TestPyPI is a sandbox.** It promises no durability and its packages can be pruned. Fine for
+  the internal stage; publishing to the production PyPI is a stage-2 item, before the endpoint
+  faces a public IP.
+
+**Fallback — install from the checkout.** For a machine with no access to TestPyPI, or to test a
+change that is not released yet:
+
+```bash
+sudo -u mcbp /opt/mcbp-mcp/.venv/bin/pip install -e /srv/mcbp-mcp-server/mcbp-core
+sudo -u mcbp /opt/mcbp-mcp/.venv/bin/pip install -e "/srv/mcbp-mcp-server/mcp-server[http]"
+```
+
+Here — and only here — `mcbp-core` must go **first and editable (`-e`)**. A plain `pip install`
+leaves a snapshot copy in `site-packages`, and later edits to the checkout then silently do
+nothing. That failure has already happened on this box, in the backend's venv (19.08).
+
+**Keep this venv separate from the backend's** at `/opt/mcbp-ai/backend/.venv`. The two install
+the same packages at different versions and share a machine, nothing else.
+
+One venv serves every base: updating is one `pip install` plus
+`sudo systemctl restart 'mcbp-mcp@*'`.
+
+## 2. One env file per base
+
+```bash
+sudo mkdir -p /etc/mcbp-mcp
+sudo cp mcbp-mcp.env.example /etc/mcbp-mcp/prod.env
+sudo chmod 600 /etc/mcbp-mcp/prod.env && sudo chown root:root /etc/mcbp-mcp/prod.env
+sudo -e /etc/mcbp-mcp/prod.env
+```
+
+The file name is the systemd instance name: `/etc/mcbp-mcp/prod.env` → `mcbp-mcp@prod`. Repeat
+per base, changing `ONEC_BASE_URL`, the credentials and — mandatory — `MCP_HTTP_PORT`.
+
+For stage 1 set `MCP_HTTP_HOST` to the LAN address (or `0.0.0.0`) and leave
+`MCP_HTTP_ALLOWED_HOSTS` **empty**.
+
+Read the comments in that file. Three of them mark mistakes that have already cost a live
+round-trip each: the `/ai/v1` suffix, the absent `ONEC_PASSWORD`, the empty host allow-list.
+
+## 3. Run
+
+```bash
+sudo cp mcbp-mcp@.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable --now mcbp-mcp@prod mcbp-mcp@demo
+```
+
+One unit file, any number of bases — the instance name after `@` picks the env file.
+
+```bash
+systemctl status 'mcbp-mcp@*'
+journalctl -u mcbp-mcp@prod -n 30    # startup logs the BAS base_url and the write flag
+```
+
+Bring the first base up alone and verify it end to end before adding the rest.
+
+## 4. Verify
+
+Two checks that answer different questions.
+
+**a) The process is alive.** Says nothing about BAS — it is a static string:
+
+```bash
+curl -s 127.0.0.1:8011/healthz     # -> ok
+```
+
+**b) The transport really speaks MCP.** A bare `GET /mcp` is expected to fail (400, no session),
+so the check is an `initialize` round-trip. In stage 1 there is no TLS and no allow-list, so this
+runs unchanged from the server or from a workstation — swap the host:
+
+```bash
+curl -sS http://<server-lan-address>:8011/mcp \
+  -H 'content-type: application/json' \
+  -H 'accept: application/json, text/event-stream' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'
+```
+
+A `serverInfo` with a non-empty `version` means the transport is live. It still says nothing
+about BAS: the connection to the base is made lazily, on the first tool call.
+
+**c) BAS is actually reachable.** Only a real tool call proves that. Register the server with a
+client and confirm `tools/list` returns 10 tools (13 if `MCP_ALLOW_WRITE=1`), then call `health`.
+
+## 5. Connect a client
+
+Claude Code, from a machine on the same network, connecting as the user's OWN BAS account:
+
+```bash
+claude mcp add --transport http mcbp-prod http://<server-lan-address>:8011/mcp   --header "Authorization: Basic $(printf '%s' 'user:password' | base64)"
+```
+
+Each base is a separate entry with its own port.
+
+**What the header does.** Every tool call from that client runs under the named BAS account: BAS
+rights decide what it may read or write, and the BAS registration log names that person rather
+than the service account. One process still serves one base — the header carries credentials
+only, never a base selector.
+
+**Without the header** the client falls back to the process's `ONEC_USER` (section 2). That is
+still supported, and it is what stdio always does — but it puts every action under the one
+service identity.
+
+**A malformed header is rejected, never downgraded.** A non-Basic scheme, undecodable base64, or
+a value that is not `user:password` answers `400 BAD_AUTHORIZATION`. A silent fallback to the
+service account is exactly the failure this feature removes. A *wrong* password is not this case:
+it reaches BAS and comes back as the normal BAS authentication failure.
+
+**Where the password ends up.** In the client's own MCP config file, in clear text (base64 is not
+encryption) — `~/.claude.json` for Claude Code. This differs from the web backend, where the
+password is typed into a login form and lives only in that session's memory. Treat the config
+file accordingly, and prefer a per-person BAS account over a shared one.
+
+## Security property of stage 1 — read this before opening the port
+
+**The endpoint itself authenticates nobody.** It accepts every connection; what it does NOT do
+is grant every connection the same power.
+
+- **With an `Authorization` header** (section 5) the caller acts as their own BAS account. BAS
+  rights are then the access control, and the registration log names the person. The header is
+  passed through to BAS and verified there — this server never checks a password itself, so it
+  cannot be tricked into accepting one.
+- **Without a header** the caller acts as the process's `ONEC_USER`, and every such action looks
+  identical in the BAS log. Keep that account low-privilege for exactly this reason.
+
+`MCP_ALLOW_WRITE` remains a property of the PROCESS, not of the caller: a read-only instance
+exposes the 10 read tools to everyone who reaches it, whatever account they present. Write
+permission is therefore decided twice — by the instance, then by BAS rights.
+
+What is still missing: **nothing stops an unauthorized person from reaching the port** and
+falling back to the service account. Handing out "only the bases you are allowed" is a
+convenience, not a control: ports are predictable, and someone inside the network who learns a
+neighbouring base's URL simply adds it. So **the network boundary is still the control over WHO
+connects** — the header changes what they can do once connected, not whether they may connect.
+Both must be replaced before the endpoint gets a public IP.
+
+---
+
+# Stage 2: external server with a public IP
+
+What changes. Nothing is rebuilt.
+
+1. **nginx in front, terminating TLS.** Take the `location` blocks from `nginx-mcp.conf` — one
+   per instance, mapping a public path to that instance's port — into the TLS `server { }` block,
+   then reload. Do not drop `proxy_buffering off` or the 310 s timeouts: the first breaks SSE
+   streaming, the second lets nginx cut a long tool call.
+2. **`MCP_HTTP_HOST=127.0.0.1`** in every env file, then restart. The process must be reachable
+   only through the proxy; leaving it on the LAN interface would publish an unauthenticated
+   endpoint next to the guarded one.
+3. **`MCP_HTTP_ALLOWED_HOSTS=<public hostname>`** in every env file. This turns on DNS-rebinding
+   protection. It must agree with what nginx forwards, which is why the config keeps
+   `proxy_set_header Host $host`.
+4. **Access control, chosen deliberately** — the header of `nginx-mcp.conf` lists the options
+   (per-base token in a custom header via an nginx `map`, source-IP allow-list, OAuth) and what
+   each one is and is not good for. Whatever is chosen there decides WHO may connect; the BAS
+   account in the caller's `Authorization` header decides what they may then do. That header is
+   taken: nginx must forward it untouched and must not run `auth_basic` on these locations.
+5. **A publicly valid certificate** if hosted connector surfaces are to be clients (section 0).
+6. **Publish `mcbp` to the production PyPI** and reinstall from it. TestPyPI makes no durability
+   promise; a public deployment must not depend on a sandbox index.
+
+## Troubleshooting
+
+| Symptom | Cause |
+|---|---|
+| Connection refused from a workstation, fine from the server | `MCP_HTTP_HOST` is still `127.0.0.1`. |
+| `421 Invalid Host header` | `MCP_HTTP_ALLOWED_HOSTS` is set and disagrees with the Host the client sends. In stage 1 it should be empty; behind nginx, keep `proxy_set_header Host $host`. |
+| `307` to `/mcp/` | Not from this server — the route matches `/mcp` exactly. Look for a proxy rewriting the path. |
+| `400` on POST | Missing `mcp-session-id`, or `accept` without `text/event-stream`. |
+| `400 BAD_AUTHORIZATION` | The `Authorization` header is not `Basic <base64 user:password>`. Rebuild it; the server deliberately does not fall back to the service account. |
+| Tools answer with a BAS auth error | The credentials in the header are wrong for this base. The header reached BAS — that is the base rejecting them, not the transport. |
+| Actions show as the service account in the BAS log | The client sends no `Authorization` header. |
+| Response hangs, then arrives all at once | `proxy_buffering` is still on (stage 2 only). |
+| Two instances, one won't start | Same `MCP_HTTP_PORT` in both env files. `journalctl` shows the bind error. |
+| Every tool 403 `KEY_MISMATCH` while `health` works | Infobase key does not match the publication — a BAS-side issue; startup logs a warning for it. |
+| `404` on every tool, `health` fine | `ONEC_BASE_URL` still carries the `/ai/v1` suffix. |
+| `No matching distribution found for httpx` (or mcp/starlette/uvicorn) | The TestPyPI install is missing `--extra-index-url https://pypi.org/simple/`. |
+| `mcbp-http: command not found` | Version 0.1.0 got installed — it predates the HTTP transport. Pin `==0.2.0`. |
+| Edits to the checkout have no effect | Fallback install only: `mcbp-core` went in without `-e`. |

mcbp-0.2.4/deploy/client-kit/README.md

@@ -0,0 +1,62 @@
+# Підключення до MCP-сервера mcbp-ai (Windows)
+
+Комплект для машини **клієнта**. Сервер уже піднятий кимось іншим — тут лише три кроки.
+
+Що вам мають видати:
+
+| Що | Приклад | Звідки |
+|---|---|---|
+| Адреса сервера | `https://<адреса сервера>:8443/mcp` | адміністратор сервера |
+| Токен доступу | довгий випадковий рядок | адміністратор (`new-token.cmd` на сервері) |
+| Файл сертифіката | `mcbp-mcp.cer` | адміністратор — лише якщо адреса на `https` |
+
+Токен — це ваш пароль до BAS: він зіставлений з конкретною обліковкою, і всі дії
+в журналі реєстрації бази підуть від вашого імені. Не пересилайте його далі.
+
+## Крок 1. Довіра до сертифіката (лише для `https`)
+
+Покладіть `mcbp-mcp.cer` поруч із `trust-cert.cmd`, натисніть на скрипті правою
+кнопкою → **Запуск від імені адміністратора**. Без прав адміністратора скрипт
+одразу скаже про це і нічого не змінить.
+
+Скрипт вносить сертифікат у сховище «Довірені кореневі центри сертифікації».
+Якщо адреса сервера на `http://` — цей крок пропускається.
+
+## Крок 2. Реєстрація сервера в Codex
+
+Запустіть `setup-codex.cmd`. Він спитає адресу та токен (або візьміть їх
+аргументами: `setup-codex.cmd https://<адреса сервера>:8443/mcp <токен>`).
+
+Скрипт:
+
+1. знаходить `codex.exe` у `PATH`, а якщо там немає — у
+   `%LOCALAPPDATA%\OpenAI\Codex\bin\`;
+2. зберігає токен у змінній оточення користувача `MCBP_TOKEN` (`setx`);
+3. виконує `codex mcp add mcbp --url <адреса> --bearer-token-env-var MCBP_TOKEN`.
+
+**Після цього закрийте вікно і відкрийте нове** — `setx` діє лише на нові процеси.
+
+## Крок 3. Перевірка
+
+```
+codex mcp list
+```
+
+Сервер `mcbp` має бути у списку. Далі в Codex попросіть, наприклад, показати
+перелік довідників — має відповісти база, а не помилка авторизації.
+
+## Якщо не працює
+
+| Симптом | Причина |
+|---|---|
+| `400 BAD_AUTHORIZATION` | токен не той або застарів — запитайте новий |
+| помилка сертифіката / TLS | не виконано крок 1, або сертифікат виданий на іншу адресу |
+| `codex.exe not found` | не встановлено Codex CLI |
+| працювало, перестало після зміни токена | не перевідкрито термінал після `setx` |
+| з'єднання не встановлюється | сервер вимкнено або закрито порт — до адміністратора |
+
+## Claude Code замість Codex
+
+Claude Code вміє довільні заголовки, тож токен передається так само —
+заголовком `Authorization: Bearer <токен>`. Схема `Basic` з обліковкою BAS
+теж і далі приймається.