mcbp 0.2.4__py3-none-any.whl

mcbp-0.2.4.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,12 @@
+mcbp_mcp_server/__init__.py,sha256=sK7mdXJQ1IQhpmWM88h_J62_d5MA0Ir6YhF16SL-j1k,902
+mcbp_mcp_server/__main__.py,sha256=KoNgTTd3m9kq6CSN_cIYkkib4slJNIyUQyTG16_3dLM,84
+mcbp_mcp_server/credentials.py,sha256=cqmeQMCEnsiz7MGvcfmzKceyT5OLfO_c8lwWCTF0ih4,12505
+mcbp_mcp_server/errors.py,sha256=a0HVKp4kJFwHOV9pf6d5ljRADZgyS3Gl3LbonrZmkB4,2996
+mcbp_mcp_server/http.py,sha256=L2264kJQONeq6SPsk_EGNZwwTAaMuk39HNPgyBJaABk,13841
+mcbp_mcp_server/registry.py,sha256=Dxgy4Oh1RteKGOX4L2gGmU8M1RXMq7D4wE-53fOhkZ0,4818
+mcbp_mcp_server/server.py,sha256=TV8c_SYUTMs-4I52ufl_HcRvarX20biSRg9sNf27mOc,8204
+mcbp-0.2.4.dist-info/METADATA,sha256=a6thIlQALsUwXLB00Aj8R_ga3os-LAt1xNBFYrtegDo,7555
+mcbp-0.2.4.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+mcbp-0.2.4.dist-info/entry_points.txt,sha256=htifNeITOg2oK_HYKeUGQxEKywceEu0HVgXG8ElEJyc,91
+mcbp-0.2.4.dist-info/licenses/LICENSE,sha256=85cNfzM7nd42WOo4lnmqJjxfpHM3oflTLSIlpo-7IHU,1066
+mcbp-0.2.4.dist-info/RECORD,,

mcbp-0.2.4.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mcbp-0.2.4.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+mcbp = mcbp_mcp_server.server:main
+mcbp-http = mcbp_mcp_server.http:main

mcbp-0.2.4.dist-info/licenses/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_mcp_server/__init__.py

@@ -0,0 +1,19 @@
+"""Standalone MCP server exposing BAS MCBP_AI (/ai/v1) to MCP clients.
+
+A thin stdio adapter over `mcbp_core` — see `.claude/skills/mcbp-mcp-server/SKILL.md` for the
+build blueprint. This package holds no knowledge of BAS routes, fields, or response shapes.
+"""
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version as _distribution_version
+
+# The distribution is named `mcbp`, the import package `mcbp_mcp_server` — read the version from
+# installed metadata rather than restating it here, so `pyproject.toml` stays the single source.
+# MCP clients show this string in their connected-servers UI; an empty one makes releases
+# indistinguishable there.
+try:
+    __version__ = _distribution_version("mcbp")
+except PackageNotFoundError:  # source tree that was never installed (e.g. a bare checkout)
+    __version__ = "0+unknown"
+
+__all__ = ["__version__"]

mcbp_mcp_server/__main__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from mcbp_mcp_server.server import main
+
+main()

mcbp_mcp_server/credentials.py

@@ -0,0 +1,298 @@
+"""Per-request BAS credentials for the HTTP transport.
+
+The stdio server has exactly one identity — the `ONEC_*` env block — and that stays true. Over
+HTTP the process serves many people, and a single service account would make every action in the
+BAS registration log look identical. So an HTTP caller may present its OWN BAS account in an
+`Authorization: Basic` header, and BAS rights become the access control.
+
+Three pieces live here:
+
+  * `Credentials` + `parse_authorization()` — the header, validated, never echoed back.
+  * a `ContextVar` carrying this request's credentials from the ASGI layer to the tool executor.
+  * `ClientPool` — one `MCBPClient` (and therefore one httpx pool AND one metadata cache) per
+    distinct credential set, reused across that caller's requests.
+
+WHY A CONTEXTVAR, AND WHY IT IS SAFE HERE. `ServerRequestContext` (what `on_call_tool` receives
+on `mcp==2.0.0`) has NO `transport` field at all, so the SDK's `TransportContext.headers` never
+reaches a handler; and `StreamableHTTPSessionManager` only populates that field on the modern
+(2026-07-28) path anyway. Capturing the headers in our own ASGI wrapper is therefore the only
+route. That the value survives into the handler's task was verified empirically against
+`mcp==2.0.0` on a live uvicorn run — stateful sessions, stateless mode, and the modern path, and
+under four concurrent overlapping tool calls each seeing its own header. It is a per-REQUEST
+value, not a per-session one: a session whose `initialize` carried header A and whose `tools/call`
+carried header B executes as B.
+"""
+from __future__ import annotations
+
+import base64
+import binascii
+import hashlib
+import logging
+import secrets
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from contextvars import ContextVar, Token
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+import anyio
+from mcbp_core.client import ConnectionConfig, MCBPClient
+
+if TYPE_CHECKING:
+    from mcbp_mcp_server.server import AppContext, Settings
+
+log = logging.getLogger("mcbp_mcp_server")
+
+# A long-lived process must not accumulate one httpx pool per person who ever connected. Both
+# limits are deliberately generous: eviction closes a client, which throws away its warmed
+# metadata cache, so it should happen on abandonment, not on ordinary idleness between turns.
+MAX_CLIENTS = 32
+IDLE_TTL_S = 1800.0
+
+
+class CredentialsError(Exception):
+    """A present but unusable `Authorization` header.
+
+    Never carries the header value: the message goes into an HTTP response and a log line, and
+    the header is a password. Absent header is NOT this error — that is the env fallback.
+    """
+
+
+@dataclass(frozen=True)
+class Credentials:
+    user: str
+    password: str = field(repr=False)
+
+    @property
+    def cache_key(self) -> str:
+        """Identifies the credential set without carrying it. The password never appears in a
+        dict key, a log line, or an eviction message — only this digest does."""
+        raw = f"{self.user}\0{self.password}".encode()
+        return hashlib.sha256(raw).hexdigest()
+
+    def __repr__(self) -> str:  # pragma: no cover - defensive, exercised only by a stray log
+        return f"Credentials(user={self.user!r})"
+
+
+@dataclass(frozen=True)
+class TokenEntry:
+    """One line of the token registry: an opaque bearer token standing in for a BAS account.
+
+    `label` exists so a log line can name WHO acted without naming the token or the password.
+    """
+
+    token: str = field(repr=False)
+    credentials: Credentials
+    label: str = ""
+
+    @property
+    def display_name(self) -> str:
+        return self.label or self.credentials.user
+
+
+class TokenRegistry:
+    """The `Bearer` half of the auth story: token -> BAS account.
+
+    Deliberately a linear scan compared with `secrets.compare_digest`, not a dict lookup. A dict
+    compares hashes and then the strings themselves with an early-exit `==`; the scan keeps the
+    comparison constant-time per entry, which is what stops a caller from probing the token a
+    byte at a time. The registries here are a handful of people, so the cost is irrelevant.
+    """
+
+    def __init__(self, entries: list[TokenEntry] | None = None) -> None:
+        self._entries: list[TokenEntry] = list(entries or ())
+
+    def __len__(self) -> int:
+        return len(self._entries)
+
+    @property
+    def labels(self) -> list[str]:
+        """Safe to log: names only, never tokens."""
+        return [e.display_name for e in self._entries]
+
+    def lookup(self, token: str) -> TokenEntry | None:
+        """Compares BYTES, not strings: `compare_digest` on `str` raises `TypeError` on any
+        non-ASCII character, and a token arrives from a header, so a stray byte would turn a
+        rejection into a 500. Encoded, a non-ASCII token simply matches nothing and takes the
+        ordinary "not recognised" path — no separate error telling a caller its token was
+        merely malformed rather than unknown."""
+        probe = token.encode("utf-8")
+        found: TokenEntry | None = None
+        for entry in self._entries:
+            if secrets.compare_digest(entry.token.encode("utf-8"), probe):
+                found = entry
+        return found
+
+
+def parse_authorization(value: str, tokens: TokenRegistry | None = None) -> Credentials:
+    """`Basic <base64 user:password>` or `Bearer <token>` -> `Credentials`. Raises
+    `CredentialsError` on anything else — a malformed header must never fall back to the env
+    account, which would mean a user with a bad config quietly acting as the service identity.
+
+    The `Bearer` form exists because some MCP clients (Codex) can send a token from an env var
+    but cannot send an arbitrary header. The token itself never appears in the raised message:
+    the message reaches an HTTP response body and a log line, and the token IS the password.
+    """
+    scheme, _, payload = value.partition(" ")
+    if scheme.lower() == "bearer":
+        return _resolve_bearer(payload.strip(), tokens)
+    if scheme.lower() != "basic":
+        raise CredentialsError(
+            "Authorization must use the Basic or Bearer scheme: "
+            "'Basic <base64 of user:password>' or 'Bearer <token>'"
+        )
+    payload = payload.strip()
+    if not payload:
+        raise CredentialsError("Authorization: Basic is missing its base64 credentials")
+    try:
+        decoded = base64.b64decode(payload, validate=True).decode("utf-8")
+    except (binascii.Error, ValueError, UnicodeDecodeError) as e:
+        raise CredentialsError(
+            "Authorization: Basic value is not valid base64 of a UTF-8 'user:password'"
+        ) from e
+    user, sep, password = decoded.partition(":")
+    if not sep:
+        raise CredentialsError("Authorization: Basic credentials must be 'user:password'")
+    if not user:
+        raise CredentialsError("Authorization: Basic credentials have an empty user name")
+    return Credentials(user=user, password=password)
+
+
+def _resolve_bearer(token: str, tokens: TokenRegistry | None) -> Credentials:
+    if not token:
+        raise CredentialsError("Authorization: Bearer is missing its token")
+    if tokens is None or not len(tokens):
+        raise CredentialsError(
+            "Authorization: Bearer is not accepted — no token registry is configured "
+            "(set MCP_TOKENS_FILE)"
+        )
+    entry = tokens.lookup(token)
+    if entry is None:
+        raise CredentialsError("Authorization: Bearer token is not recognised")
+    log.info("authorized bearer request for %s", entry.display_name)
+    return entry.credentials
+
+
+_request_credentials: ContextVar[Credentials | None] = ContextVar(
+    "mcbp_request_credentials", default=None,
+)
+
+
+def set_request_credentials(creds: Credentials | None) -> Token[Credentials | None]:
+    return _request_credentials.set(creds)
+
+
+def reset_request_credentials(token: Token[Credentials | None]) -> None:
+    _request_credentials.reset(token)
+
+
+def current_credentials() -> Credentials | None:
+    """`None` on stdio (no headers exist) and for an HTTP request with no `Authorization` — both
+    mean "use the env identity"."""
+    return _request_credentials.get()
+
+
+@dataclass
+class _Entry:
+    client: MCBPClient
+    last_used: float
+    inflight: int = 0
+
+
+class ClientPool:
+    """One live `MCBPClient` per credential set, reused across that caller's requests.
+
+    A fresh client per tool call would mean a fresh httpx pool and a cold metadata cache on every
+    model turn. Conversely the cache MUST NOT be shared: it is per client instance, which is
+    exactly what keeps one user's metadata (and connection) out of another's requests.
+    """
+
+    def __init__(self, settings: Settings, *, max_clients: int = MAX_CLIENTS,
+                 idle_ttl_s: float = IDLE_TTL_S) -> None:
+        self._settings = settings
+        self._max_clients = max_clients
+        self._idle_ttl_s = idle_ttl_s
+        self._entries: dict[str, _Entry] = {}
+        self._lock = anyio.Lock()
+
+    @property
+    def size(self) -> int:
+        return len(self._entries)
+
+    def _build(self, creds: Credentials) -> MCBPClient:
+        s = self._settings
+        return MCBPClient(ConnectionConfig(
+            base_url=s.base_url,
+            user=creds.user,
+            password=creds.password,
+            timeout_s=s.timeout,
+            pool_max=s.pool_max,
+            mock=False,
+            verify=s.verify_ssl,
+        ))
+
+    @asynccontextmanager
+    async def lease(self, creds: Credentials) -> AsyncIterator[MCBPClient]:
+        """Hands out the client for `creds`, held against eviction for the duration."""
+        key = creds.cache_key
+        async with self._lock:
+            entry = self._entries.get(key)
+            if entry is None:
+                client = self._build(creds)
+                await client.startup()
+                entry = _Entry(client=client, last_used=anyio.current_time())
+                self._entries[key] = entry
+                log.info("BAS client opened for user %s (pool size %d)", creds.user, self.size)
+            entry.inflight += 1
+            entry.last_used = anyio.current_time()
+            await self._evict_locked()
+        try:
+            yield entry.client
+        finally:
+            async with self._lock:
+                entry.inflight -= 1
+                entry.last_used = anyio.current_time()
+
+    async def _evict_locked(self) -> None:
+        """Closes idle clients: anything unused past the TTL, then the least recently used while
+        over the size cap. An entry with a call in flight is never closed — `aclose()` on a live
+        httpx pool would abort that caller's request."""
+        now = anyio.current_time()
+        stale = [
+            key for key, e in self._entries.items()
+            if e.inflight == 0 and now - e.last_used > self._idle_ttl_s
+        ]
+        for key in stale:
+            await self._close(key, "idle")
+        if len(self._entries) <= self._max_clients:
+            return
+        by_age = sorted(
+            (k for k, e in self._entries.items() if e.inflight == 0),
+            key=lambda k: self._entries[k].last_used,
+        )
+        for key in by_age[: len(self._entries) - self._max_clients]:
+            await self._close(key, "pool full")
+
+    async def _close(self, key: str, reason: str) -> None:
+        entry = self._entries.pop(key, None)
+        if entry is None:  # pragma: no cover - only reachable on a concurrent pop
+            return
+        log.info("closing BAS client %s (%s)", key[:8], reason)
+        await entry.client.shutdown()
+
+    async def aclose(self) -> None:
+        async with self._lock:
+            for key in list(self._entries):
+                await self._close(key, "shutdown")
+
+
+@asynccontextmanager
+async def client_for(app: AppContext) -> AsyncIterator[MCBPClient]:
+    """The client this request must run as: the caller's own when an `Authorization` header was
+    presented, otherwise the process's env identity (always the case on stdio)."""
+    creds = current_credentials()
+    if creds is None or app.pool is None:
+        yield app.client
+        return
+    async with app.pool.lease(creds) as client:
+        yield client

mcbp_mcp_server/errors.py

@@ -0,0 +1,52 @@
+"""Maps `mcbp_core.errors.MCBPError` subclasses to the two channels a tool call on the
+low-level `Server` can take.
+
+EMPIRICALLY VERIFIED against the installed `mcp==2.0.0` (probe: raise a plain exception from
+`on_call_tool`, call through the SDK's in-memory `Client`) — the low-level `Server` has NO
+wrapper around `on_call_tool` the way `MCPServer`'s `@tool()` decorator did. An exception that
+escapes the handler is NOT turned into `CallToolResult(is_error=True, ...)` automatically: it
+propagates through the JSON-RPC dispatcher, which recognizes only `MCPError` and pydantic
+`ValidationError` and maps everything else to a GENERIC `MCPError(code=INTERNAL_ERROR,
+message="Internal server error")` — the original message is DISCARDED. So:
+
+- `KeyMismatchError` / `AuthError` (fatal configuration, the model cannot fix it): build our own
+  `MCPError` here and `raise` it from `on_call_tool` — that is the one exception type the
+  dispatcher passes through with its message intact, so this is the only way to get a
+  *meaningful* protocol-level error to the host instead of the generic swallowed one.
+- Every other `MCBPError` (`ParameterError`, `NotFoundError`, `PlusRequiredError`,
+  `UpstreamError`, …): must NOT be allowed to escape `on_call_tool` — `registry.py` catches it and
+  calls `to_tool_error()` to build a `CallToolResult(is_error=True, ...)` explicitly, which is the
+  only way the model sees the message (e.g. `BAD_PARAMETER` naming the unknown field verbatim)
+  instead of a swallowed "Internal server error".
+"""
+from __future__ import annotations
+
+from mcbp_core.errors import AuthError, KeyMismatchError, LicenseRequiredError, MCBPError
+from mcp import MCPError, types
+
+_FATAL: tuple[type[MCBPError], ...] = (KeyMismatchError, AuthError, LicenseRequiredError)
+
+
+def is_fatal(exc: MCBPError) -> bool:
+    """True for the error types that are a fatal configuration issue, not a recoverable tool-call
+    failure — the model cannot self-correct a key mismatch, bad credentials or a missing licence.
+
+    A licence covers the whole service: every remaining tool would fail identically, so surfacing
+    it as an ordinary tool error would have the model walk the registry one call at a time."""
+    return isinstance(exc, _FATAL)
+
+
+def to_mcp_error(exc: MCBPError) -> MCPError:
+    """`KeyMismatchError`/`AuthError` only. `code`/`message` are carried verbatim, not reworded —
+    the host surfaces this as a JSON-RPC error, never a normal tool result."""
+    return MCPError(code=types.INTERNAL_ERROR, message=f"{exc.code}: {exc.message}")
+
+
+def to_tool_error(exc: MCBPError) -> types.CallToolResult:
+    """Every other `MCBPError`. `code`/`message` are carried verbatim (never wrapped or
+    reworded) — `BAD_PARAMETER` naming the unknown field is exactly what lets the model recover
+    via `describe_metadata`."""
+    return types.CallToolResult(
+        is_error=True,
+        content=[types.TextContent(type="text", text=f"{exc.code}: {exc.message}")],
+    )

mcbp_mcp_server/http.py

@@ -0,0 +1,317 @@
+"""Streamable HTTP transport for the `mcbp-ai` MCP server.
+
+A second entry point NEXT TO stdio, not a replacement: `create_server()`, the tool registry and
+the `lifespan` that owns `MCBPClient` are reused untouched. `StreamableHTTPSessionManager` takes
+the low-level `Server` directly, so this module only wires ASGI — it holds no knowledge of BAS
+routes or of the tool set.
+
+Deployment notes that are NOT obvious from the code:
+  * `Route`, not `Mount`. Starlette compiles `Mount("/mcp")` to `^/mcp/(?P<path>.*)$`, so an exact
+    POST to `/mcp` misses the mount and gets a 307 to `/mcp/` — and that bare form is exactly what
+    a user types into a connector URL field.
+  * DNS-rebinding protection is opt-in here: the SDK's own default when no settings are passed is
+    "disabled", and enabling it with an empty allow-list would answer every request with 421.
+    Set MCP_HTTP_ALLOWED_HOSTS once the public hostname is known.
+  * nginx in front needs `proxy_buffering off` (SSE) and a read timeout above the client's own
+    300 s tool-call limit.
+"""
+from __future__ import annotations
+
+import logging
+import os
+import sys
+import tomllib
+from collections.abc import AsyncIterator, Mapping
+from contextlib import asynccontextmanager
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
+from mcp.server.transport_security import TransportSecuritySettings
+from starlette.applications import Starlette
+from starlette.datastructures import Headers
+from starlette.requests import Request
+from starlette.responses import JSONResponse, PlainTextResponse
+from starlette.routing import Route
+from starlette.types import Receive, Scope, Send
+
+from mcbp_mcp_server.credentials import (
+    Credentials,
+    CredentialsError,
+    TokenEntry,
+    TokenRegistry,
+    parse_authorization,
+    reset_request_credentials,
+    set_request_credentials,
+)
+from mcbp_mcp_server.server import (
+    Settings,
+    SettingsError,
+    _optional_float,
+    _optional_int,
+    _truthy,
+    create_server,
+    load_settings,
+)
+
+log = logging.getLogger("mcbp_mcp_server")
+
+
+@dataclass(frozen=True)
+class HttpSettings:
+    host: str = "127.0.0.1"
+    port: int = 8010
+    path: str = "/mcp"
+    allowed_hosts: list[str] = field(default_factory=list)
+    allowed_origins: list[str] = field(default_factory=list)
+    session_idle_timeout: float = 1800.0
+    stateless: bool = False
+    require_auth: bool = False
+
+
+def _csv(env: Mapping[str, str], name: str) -> list[str]:
+    return [item.strip() for item in env.get(name, "").split(",") if item.strip()]
+
+
+def load_http_settings(env: Mapping[str, str] | None = None) -> HttpSettings:
+    """Reads `MCP_HTTP_*` from `env` (defaults to `os.environ`). Pure, like `load_settings()`:
+    raises `SettingsError`, never prints or exits. Binds to loopback by default — the process is
+    meant to sit behind nginx, and a default of 0.0.0.0 would publish an unauthenticated endpoint
+    the moment someone forgets the reverse proxy."""
+    e = os.environ if env is None else env
+    path = e.get("MCP_HTTP_PATH", "/mcp").rstrip("/") or "/"
+    if not path.startswith("/"):
+        raise SettingsError(f"MCP_HTTP_PATH must start with '/', got {path!r}")
+    return HttpSettings(
+        host=e.get("MCP_HTTP_HOST", "127.0.0.1"),
+        port=_optional_int(e, "MCP_HTTP_PORT", 8010),
+        path=path,
+        allowed_hosts=_csv(e, "MCP_HTTP_ALLOWED_HOSTS"),
+        allowed_origins=_csv(e, "MCP_HTTP_ALLOWED_ORIGINS"),
+        session_idle_timeout=_optional_float(e, "MCP_HTTP_SESSION_IDLE_TIMEOUT", 1800.0),
+        stateless=_truthy(e.get("MCP_HTTP_STATELESS")),
+        require_auth=_truthy(e.get("MCP_REQUIRE_AUTH")),
+    )
+
+
+def load_token_registry(env: Mapping[str, str] | None = None) -> TokenRegistry:
+    """Reads the `MCP_TOKENS_FILE` TOML registry. Pure, like `load_http_settings()`.
+
+    An unset variable yields an EMPTY registry, not an error — Bearer is then simply not
+    accepted, which is the stdio/Basic-only deployment. A variable that IS set and points at a
+    missing or malformed file is a startup error: silently serving with Bearer disabled would
+    look exactly like a working server until someone's token is rejected.
+
+    Expected shape (one table per person)::
+
+        [[users]]
+        token = "<random string>"
+        onec_user = "Директор-Корнієнко"
+        onec_password = ""
+        label = "Директор"
+
+    Error messages name the file and the entry number, never a token, a password, or any other
+    file content.
+    """
+    e = os.environ if env is None else env
+    raw_path = (e.get("MCP_TOKENS_FILE") or "").strip()
+    if not raw_path:
+        return TokenRegistry()
+    path = Path(raw_path)
+    try:
+        data = tomllib.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError as exc:
+        raise SettingsError(f"MCP_TOKENS_FILE points at a file that does not exist: {path}") from exc
+    except OSError as exc:
+        raise SettingsError(f"MCP_TOKENS_FILE {path} cannot be read: {exc.strerror}") from exc
+    except UnicodeDecodeError as exc:
+        raise SettingsError(f"MCP_TOKENS_FILE {path} is not valid UTF-8") from exc
+    except tomllib.TOMLDecodeError as exc:
+        raise SettingsError(f"MCP_TOKENS_FILE {path} is not valid TOML: {exc}") from exc
+    return _registry_from(data, path)
+
+
+def _registry_from(data: dict[str, object], path: Path) -> TokenRegistry:
+    users = data.get("users", [])
+    if not isinstance(users, list):
+        raise SettingsError(f"MCP_TOKENS_FILE {path} must define an array of tables '[[users]]'")
+    entries: list[TokenEntry] = []
+    seen: set[str] = set()
+    for index, item in enumerate(users, start=1):
+        where = f"MCP_TOKENS_FILE {path}, [[users]] entry #{index}"
+        if not isinstance(item, dict):
+            raise SettingsError(f"{where} must be a table")
+        token = _entry_str(item, "token", where, required=True)
+        user = _entry_str(item, "onec_user", where, required=True)
+        # Empty is legal and common (basmbdemo has no password) — only a missing key fails.
+        password = _entry_str(item, "onec_password", where, required=False, allow_empty=True)
+        if "onec_password" not in item:
+            raise SettingsError(f"{where} is missing 'onec_password' (use \"\" for none)")
+        label = _entry_str(item, "label", where, required=False, allow_empty=True)
+        if token in seen:
+            raise SettingsError(f"{where} repeats a token already used by an earlier entry")
+        seen.add(token)
+        entries.append(TokenEntry(
+            token=token,
+            credentials=Credentials(user=user, password=password),
+            label=label,
+        ))
+    return TokenRegistry(entries)
+
+
+def _entry_str(item: dict[str, object], key: str, where: str, *, required: bool,
+               allow_empty: bool = False) -> str:
+    value = item.get(key)
+    if value is None:
+        if required:
+            raise SettingsError(f"{where} is missing '{key}'")
+        return ""
+    if not isinstance(value, str):
+        raise SettingsError(f"{where} has a non-string '{key}'")
+    if not value and not allow_empty:
+        raise SettingsError(f"{where} has an empty '{key}'")
+    return value
+
+
+def _security(settings: HttpSettings) -> TransportSecuritySettings | None:
+    """`None` leaves the SDK middleware at its own permissive default. Protection is enabled only
+    once a host allow-list exists, because the middleware rejects EVERY request (421) when
+    enabled with an empty list."""
+    if not settings.allowed_hosts:
+        return None
+    return TransportSecuritySettings(
+        enable_dns_rebinding_protection=True,
+        allowed_hosts=settings.allowed_hosts,
+        allowed_origins=settings.allowed_origins,
+    )
+
+
+class _ManagerEndpoint:
+    """Raw ASGI adapter so `Route` treats this as an ASGI app rather than a `func(request)`
+    endpoint — Starlette makes that decision with `inspect.isfunction/ismethod`, and
+    `manager.handle_request` is a bound method, which would be misread as the latter.
+
+    It is also where the caller's BAS credentials are picked up. This has to happen HERE: the
+    SDK hands `on_call_tool` a `ServerRequestContext`, which carries no transport metadata at
+    all, and the manager attaches `TransportContext.headers` only on the modern protocol path.
+    Our own ASGI layer sees the headers whatever the protocol version — see `credentials.py`
+    for the propagation evidence."""
+
+    def __init__(self, manager: StreamableHTTPSessionManager,
+                 tokens: TokenRegistry | None = None, *, require_auth: bool = False) -> None:
+        self._manager = manager
+        self._tokens = tokens
+        self._require_auth = require_auth
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        raw = Headers(scope=scope).get("authorization")
+        try:
+            if raw is None:
+                # With MCP_REQUIRE_AUTH the env account stops being a fallback: on a port that is
+                # reachable by anyone, an unauthenticated request would otherwise act as the
+                # service identity.
+                if self._require_auth:
+                    raise CredentialsError(
+                        "Authorization is required: send 'Bearer <token>' or "
+                        "'Basic <base64 of user:password>'"
+                    )
+                creds = None
+            else:
+                creds = parse_authorization(raw, self._tokens)
+        except CredentialsError as e:
+            # 400, deliberately NOT 401: MCP clients read a 401 as "begin OAuth discovery" and
+            # would chase an authorization server that does not exist instead of showing the
+            # reason. Falling through to the env account is not an option either — that is the
+            # silent-service-account failure this whole feature exists to remove.
+            log.warning("rejected request with an unusable Authorization header: %s", e)
+            await JSONResponse({"error": {"code": "BAD_AUTHORIZATION", "message": str(e)}},
+                               status_code=400)(scope, receive, send)
+            return
+        token = set_request_credentials(creds)
+        try:
+            await self._manager.handle_request(scope, receive, send)
+        finally:
+            reset_request_credentials(token)
+
+
+async def _healthz(request: Request) -> PlainTextResponse:
+    """Liveness only — says the process is up, NOT that BAS is reachable. The MCP endpoint itself
+    cannot serve as a probe: it answers 400 without a negotiated session."""
+    return PlainTextResponse("ok")
+
+
+def create_app(settings: HttpSettings | None = None,
+               tokens: TokenRegistry | None = None) -> Starlette:
+    """Builds the ASGI app without touching the network. `create_server()` is called once; the
+    `MCBPClient` behind it is still built lazily by the server's own `lifespan`."""
+    http_settings = load_http_settings() if settings is None else settings
+    registry = load_token_registry() if tokens is None else tokens
+    manager = StreamableHTTPSessionManager(
+        create_server(),
+        json_response=False,
+        stateless=http_settings.stateless,
+        security_settings=_security(http_settings),
+        session_idle_timeout=http_settings.session_idle_timeout,
+    )
+
+    @asynccontextmanager
+    async def app_lifespan(app: Starlette) -> AsyncIterator[None]:
+        async with manager.run():
+            log.info("MCP Streamable HTTP ready on %s", http_settings.path)
+            yield
+
+    return Starlette(
+        routes=[
+            # Route, not Mount — see the module docstring.
+            Route(
+                http_settings.path,
+                endpoint=_ManagerEndpoint(
+                    manager, registry, require_auth=http_settings.require_auth,
+                ),
+                methods=["GET", "POST", "DELETE"],
+            ),
+            Route("/healthz", endpoint=_healthz, methods=["GET"]),
+        ],
+        lifespan=app_lifespan,
+    )
+
+
+def main() -> None:
+    """Entry point for the `mcbp-http` console script."""
+    logging.basicConfig(
+        level=logging.INFO, stream=sys.stderr,
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    )
+    try:
+        onec: Settings = load_settings()
+        http_settings = load_http_settings()
+        tokens = load_token_registry()
+    except SettingsError as e:
+        log.error(str(e))
+        sys.exit(1)
+
+    import uvicorn
+
+    if not http_settings.allowed_hosts:
+        log.warning(
+            "MCP_HTTP_ALLOWED_HOSTS is unset — DNS-rebinding protection is off. Set it to the "
+            "public hostname before exposing this endpoint."
+        )
+    if http_settings.require_auth and not len(tokens):
+        log.warning(
+            "MCP_REQUIRE_AUTH is on with an empty token registry — only Basic callers can "
+            "connect. Set MCP_TOKENS_FILE to accept Bearer tokens."
+        )
+    log.info(
+        "starting mcbp-ai MCP over HTTP on %s:%s%s (BAS %s, write=%s, require_auth=%s, "
+        "bearer users: %s)",
+        http_settings.host, http_settings.port, http_settings.path,
+        onec.base_url, onec.allow_write, http_settings.require_auth,
+        ", ".join(tokens.labels) or "none",
+    )
+    uvicorn.run(
+        create_app(http_settings, tokens),
+        host=http_settings.host,
+        port=http_settings.port,
+        log_level="info",
+    )

mcbp_mcp_server/registry.py

@@ -0,0 +1,112 @@
+"""`ToolSpec` -> MCP tool registration for the low-level `Server`.
+
+One loop over `mcbp_core.tools.tool_specs(surface="mcp", ...)`, no per-tool `async def` and no
+hardcoded tool list — a spec added to the shared registry is exposed here with zero edits.
+`spec.parameters` is passed through as `input_schema` UNCHANGED (that is the whole reason the
+skeleton is built on the low-level `Server` rather than `MCPServer` — see
+`.claude/skills/mcbp-mcp-server/SKILL.md`).
+"""
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Awaitable, Callable
+from typing import TYPE_CHECKING, Any
+
+from mcbp_core.errors import MCBPError
+from mcbp_core.tools import ToolSpec, tool_specs
+from mcp import types
+from mcp.server.context import ServerRequestContext
+
+from mcbp_mcp_server.credentials import client_for
+from mcbp_mcp_server.errors import is_fatal, to_mcp_error, to_tool_error
+
+if TYPE_CHECKING:
+    from mcbp_mcp_server.server import AppContext
+
+log = logging.getLogger("mcbp_mcp_server")
+
+_OnListTools = Callable[
+    ["ServerRequestContext[AppContext, Any]", "types.PaginatedRequestParams | None"],
+    Awaitable[types.ListToolsResult],
+]
+_OnCallTool = Callable[
+    ["ServerRequestContext[AppContext, Any]", types.CallToolRequestParams],
+    Awaitable[types.CallToolResult],
+]
+
+
+def _annotations(spec: ToolSpec) -> types.ToolAnnotations:
+    return types.ToolAnnotations(
+        read_only_hint=spec.read_only,
+        destructive_hint=True if not spec.read_only else None,
+    )
+
+
+def _to_tool(spec: ToolSpec) -> types.Tool:
+    return types.Tool(
+        name=spec.name,
+        description=spec.description_en or spec.description,
+        input_schema=spec.parameters,  # already JSON Schema — passed through untouched
+        annotations=_annotations(spec),
+    )
+
+
+def make_on_list_tools(allow_write: bool) -> _OnListTools:
+    # Built once at registration time so `tools/list` is deterministic and cheap — the registry
+    # order from `tool_specs()` is preserved, never sorted.
+    tools = [_to_tool(spec) for spec in tool_specs(surface="mcp", include_write=allow_write)]
+
+    async def on_list_tools(
+        ctx: ServerRequestContext[AppContext, Any], params: types.PaginatedRequestParams | None,
+    ) -> types.ListToolsResult:
+        return types.ListToolsResult(tools=tools)
+
+    return on_list_tools
+
+
+def make_on_call_tool(allow_write: bool) -> _OnCallTool:
+    specs: dict[str, ToolSpec] = {
+        spec.name: spec for spec in tool_specs(surface="mcp", include_write=allow_write)
+    }
+
+    async def on_call_tool(
+        ctx: ServerRequestContext[AppContext, Any], params: types.CallToolRequestParams,
+    ) -> types.CallToolResult:
+        spec = specs.get(params.name)
+        if spec is None:
+            return types.CallToolResult(
+                is_error=True,
+                content=[types.TextContent(type="text", text=f"Unknown tool: {params.name}")],
+            )
+        arguments = params.arguments or {}
+        try:
+            # Before the executor, not inside it: executors index required arguments directly, so
+            # a misspelled name would otherwise surface as a bare KeyError the model cannot act on.
+            spec.validate_arguments(arguments)
+            # The client is chosen per REQUEST, not per process: an HTTP caller presenting its
+            # own BAS account runs as that account (see `credentials.py`), stdio always runs as
+            # the env identity.
+            async with client_for(ctx.lifespan_context) as client:
+                result = await spec.executor(client, arguments)
+        except MCBPError as exc:
+            if is_fatal(exc):
+                raise to_mcp_error(exc) from exc
+            log.warning("%s -> %s: %s", spec.name, exc.code, exc.message)
+            return to_tool_error(exc)
+        except Exception as exc:  # noqa: BLE001
+            # An untyped error would reach the JSON-RPC dispatcher, which discards its message and
+            # answers a generic "Internal server error". A tool result keeps the text.
+            log.exception("%s raised an untyped error", spec.name)
+            return types.CallToolResult(
+                is_error=True,
+                content=[
+                    types.TextContent(type="text", text=f"TOOL_FAILED: {type(exc).__name__}: {exc}"),
+                ],
+            )
+        # Cyrillic is the overwhelming majority of BAS field values — ensure_ascii=False keeps
+        # the response readable and avoids bloating the token count with \uXXXX escapes.
+        text = json.dumps(result, ensure_ascii=False)
+        return types.CallToolResult(content=[types.TextContent(type="text", text=text)])
+
+    return on_call_tool

mcbp_mcp_server/server.py

@@ -0,0 +1,206 @@
+"""Settings, lifespan, and the `Server` factory for the `mcbp-ai` MCP server.
+
+This module is a thin stdio adapter over `mcbp_core` — it holds no knowledge of BAS routes,
+fields, or response shapes. Tool registration itself lives in `registry.py`; this module owns
+the process lifecycle: read env -> build a live `MCBPClient` -> serve stdio -> close the client.
+
+Built on the LOW-LEVEL `mcp.server.Server`, not `MCPServer` — `MCPServer.add_tool` derives its
+JSON Schema from a Python function's type hints and has no way to take a ready-made schema, while
+our tool schemas already live in `mcbp_core.tools.ToolSpec.parameters`. See
+`.claude/skills/mcbp-mcp-server/SKILL.md` for the full rationale. The low-level `Server.run()`
+wants ready anyio streams instead of raising stdio itself, so `main()` is async under the hood.
+"""
+from __future__ import annotations
+
+import logging
+import os
+import re
+import sys
+from collections.abc import AsyncIterator, Mapping
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+
+import anyio
+from mcbp_core.client import ConnectionConfig, MCBPClient
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+
+from mcbp_mcp_server import __version__
+from mcbp_mcp_server.credentials import ClientPool
+from mcbp_mcp_server.registry import make_on_call_tool, make_on_list_tools
+
+log = logging.getLogger("mcbp_mcp_server")
+
+
+class SettingsError(Exception):
+    """Raised by `load_settings()` for a missing or malformed required env var."""
+
+
+@dataclass(frozen=True)
+class Settings:
+    base_url: str
+    user: str
+    password: str
+    timeout: float = 30.0
+    pool_max: int = 10
+    allow_write: bool = False
+    verify_ssl: bool = True
+
+
+# Strips a trailing '/ai/v1' (any case, optional trailing slash) off ONEC_BASE_URL. Anchored to
+# the END of the string, so a URL that merely CONTAINS 'ai/v1' mid-path is left untouched.
+_AI_V1_SUFFIX_RE = re.compile(r"/ai/v1/?$", re.IGNORECASE)
+
+
+def _normalize_base_url(url: str) -> str:
+    """`MCBPClient` appends `/ai/v1/...` itself inside every method, so `ConnectionConfig.base_url`
+    must stop at the service name. Existing docs and `.mcp.json` show the suffixed form (written
+    for a from-scratch client that never existed) — accept both: strip the suffix if present.
+    A config that still carries it hits /ai/v1/ai/v1/... and every route (except the
+    coincidentally-shaped /health) 404s, with no error pointing at the cause."""
+    return _AI_V1_SUFFIX_RE.sub("", url.rstrip("/"))
+
+
+def _require(env: Mapping[str, str], name: str) -> str:
+    value = env.get(name)
+    if not value:
+        raise SettingsError(f"{name} is required — set it in the MCP client's env block")
+    return value
+
+
+def _require_present(env: Mapping[str, str], name: str) -> str:
+    """Like `_require`, but accepts an explicit empty string — some BAS publications
+    (e.g. basmbdemo) genuinely have no password, and `.mcp.json`'s `${VAR:-}` substitution
+    collapses "unset" and "set to empty" into the same wire value anyway, so an empty
+    `ONEC_PASSWORD` cannot be told apart from a deliberate one. Only a fully absent key fails."""
+    if name not in env:
+        raise SettingsError(f"{name} is required — set it in the MCP client's env block")
+    return env[name]
+
+
+def _optional_float(env: Mapping[str, str], name: str, default: float) -> float:
+    raw = env.get(name)
+    if not raw:
+        return default
+    try:
+        return float(raw)
+    except ValueError as e:
+        raise SettingsError(f"{name} must be a number, got {raw!r}") from e
+
+
+def _optional_int(env: Mapping[str, str], name: str, default: int) -> int:
+    raw = env.get(name)
+    if not raw:
+        return default
+    try:
+        return int(raw)
+    except ValueError as e:
+        raise SettingsError(f"{name} must be an integer, got {raw!r}") from e
+
+
+def _truthy(raw: str | None) -> bool:
+    return (raw or "").strip().lower() in {"1", "true", "yes"}
+
+
+def load_settings(env: Mapping[str, str] | None = None) -> Settings:
+    """Reads `ONEC_*` / `MCP_ALLOW_WRITE` from `env` (defaults to `os.environ`). Pure: raises
+    `SettingsError` on a missing/malformed required var, never prints or exits — `main()` is the
+    only place that turns that into a stderr message and a non-zero exit. Safe to call more than
+    once (`create_server()` and the lifespan each call it independently)."""
+    e = os.environ if env is None else env
+    return Settings(
+        base_url=_normalize_base_url(_require(e, "ONEC_BASE_URL")),
+        user=_require(e, "ONEC_USER"),
+        password=_require_present(e, "ONEC_PASSWORD"),
+        timeout=_optional_float(e, "ONEC_TIMEOUT", 30.0),
+        pool_max=_optional_int(e, "ONEC_POOL_MAX", 10),
+        allow_write=_truthy(e.get("MCP_ALLOW_WRITE")),
+        verify_ssl=_truthy(e.get("ONEC_VERIFY_SSL", "1")),
+    )
+
+
+@dataclass
+class AppContext:
+    """`client` is the process identity from the `ONEC_*` env block — the only identity on stdio,
+    and the fallback for an HTTP request that presents no `Authorization` header. `pool` holds the
+    per-caller clients built from such a header; it stays empty on stdio, which has no headers at
+    all, so nothing there can ever populate it."""
+
+    client: MCBPClient
+    allow_write: bool
+    pool: ClientPool | None = None
+
+
+async def _probe_health(client: MCBPClient) -> None:
+    """Advisory only — never raises, never blocks startup. A server that refuses to start is
+    worse than one that warns."""
+    try:
+        result = await client.health()
+    except Exception as e:  # noqa: BLE001 - advisory probe must never block startup
+        log.warning(
+            "MCBP_AI health probe failed (%s) — every route may be unreachable until this "
+            "clears", e,
+        )
+        return
+    if result.get("key") is False:
+        log.warning(
+            "MCBP_AI health probe returned key:false — the infobase key does not match the "
+            "publication; every route except /health will answer 403 KEY_MISMATCH until fixed."
+        )
+
+
+@asynccontextmanager
+async def lifespan(server: Server[AppContext]) -> AsyncIterator[AppContext]:
+    settings = load_settings()
+    client = MCBPClient(ConnectionConfig(
+        base_url=settings.base_url,
+        user=settings.user,
+        password=settings.password,
+        timeout_s=settings.timeout,
+        pool_max=settings.pool_max,
+        mock=False,
+        verify=settings.verify_ssl,
+    ))
+    await client.startup()
+    pool = ClientPool(settings)
+    try:
+        await _probe_health(client)
+        yield AppContext(client=client, allow_write=settings.allow_write, pool=pool)
+    finally:
+        await pool.aclose()
+        await client.shutdown()
+
+
+def create_server() -> Server[AppContext]:
+    """Constructs the low-level `Server` without touching the network — the client is built
+    lazily by `lifespan` only once a client actually connects. Reads only `MCP_ALLOW_WRITE` (via
+    the same `_truthy()` helper `load_settings()` uses — one decision, two read sites, never a
+    second parsing rule) so the tool SET is decidable without live `ONEC_*` credentials; the
+    per-request `AppContext.allow_write` set up by `lifespan` carries the identical value."""
+    allow_write = _truthy(os.environ.get("MCP_ALLOW_WRITE"))
+    return Server(
+        "mcbp-ai",
+        version=__version__,
+        lifespan=lifespan,
+        on_list_tools=make_on_list_tools(allow_write),
+        on_call_tool=make_on_call_tool(allow_write),
+    )
+
+
+async def _serve() -> None:
+    server = create_server()
+    async with stdio_server() as (read, write):
+        await server.run(read, write, server.create_initialization_options())
+
+
+def main() -> None:
+    logging.basicConfig(
+        level=logging.INFO, stream=sys.stderr,
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    )
+    try:
+        load_settings()
+    except SettingsError as e:
+        log.error(str(e))
+        sys.exit(1)
+    anyio.run(_serve)