answer42 0.2.0__py3-none-any.whl

mcp_1c/assets/skills/answer42/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: "answer42"
+description: "Работа с MCP Answer42 для 1С UI automation"
+---
+
+# Answer42
+
+Используй этот скилл, когда задача связана с управлением интерфейсом 1С **через MCP `Answer42`**: запуск менеджера тестирования, подключение тест-клиента, навигация по формам, выбор ссылочных полей, работа с таблицами/табличными частями, динамическими списками, скриншоты и диагностика 1С.
+
+## Scope
+
+Этот skill — про **использование MCP** для UI automation.
+
+Не смешивай с задачами разработки самого bridge:
+
+- Репозиторий Answer42 — код MCP/проекта.
+- Доработка `Answer42` — отдельная engineering-тема: правка Python/BSL, сборка CF/EPF, тесты bridge, публикация изменений.
+- Обычная UI-задача должна пользоваться готовыми MCP tools, а не менять bridge.
+- Историю разработки bridge не надо держать в `MEMORY.md`; durable правила живут в этом skill и workspace skill `skills/answer42`.
+
+## Когда применять
+
+- Нужно выполнить действие в 1С UI на живом стенде.
+- Нужно получить реальные данные через управляемый интерфейс 1С.
+- Нужно сделать скриншот формы/документа/списка/PDF evidence.
+- Нужно диагностировать запуск `/TESTMANAGER`, `/TESTCLIENT`, `ibsrv` или автономный сервер.
+- Нужно добавлять/настраивать поля динамического списка, включая вложенные поля ссылочных объектов.
+
+## Базовый порядок
+
+1. Проверь, что MCP-сервер `Answer42` установлен и доступен.
+2. Посмотри активные/восстановимые сессии через `sessions_list`; не плодить сессии с тем же стендом без причины.
+3. Запусти сессию через `start_session` (one-shot). Low-level `launch_manager` использовать только для диагностики/разработки bridge.
+4. Для подключения укажи только target в `base_url`; режим запуска клиента тестирования автоопределяется:
+   - `https://...` / `http://...` → web/ws;
+   - `server/infobase` → серверная база `/S`;
+   - каталог с `1Cv8.1CD` → файловая база через `ibsrv`, а если `ibsrv` недоступен — внутренний `file-direct` (`/F`).
+5. Передавай логин/пароль из защищённого источника, а не из репозитория. Предпочтительно один раз сохранить их через `credentials_save(url, username, password)`, затем вызывать `start_session` без `username`/`password`; окно тест-клиента максимизируется автоматически внутри tool-call.
+6. Работай только через tools Answer42; не кликай X11/WinAPI руками.
+7. Скриншоты допускаются системно через `screenshot`/`recording_*`.
+8. При ошибках 1С выгружай журнал через `export_eventlog`; для сетевых ошибок серверной базы отдельно проверяй DNS/доступность портов кластера 1С.
+9. В финальном ответе укажи реальные результаты: скриншоты/PDF, данные, ошибки, формы/фильтры.
+10. Заверши сессию через `stop_session`.
+
+## Важные правила
+
+- `/TESTMANAGER` обязателен: не заменяй его обычным запуском 1С без явного указания пользователя.
+- 1С-клиенты запускай с русской локалью: `/Lru /VLru_RU`.
+- Linux: X11/Xvfb использовать только для скриншотов и окна 1С, не для ввода/кликов/автоматизации.
+- Windows: Answer42 должен запускаться в интерактивной desktop-сессии пользователя; Windows service/headless/заблокированный RDP-сеанс для UI automation и screenshot ненадёжен.
+- Для ссылочных полей предпочитай стандартную форму выбора 1С (`choose_field_from_list`, `choose_field_first_row`, `choose_current_row`), а не ввод строки.
+- `execute_window_command` — только для явных навигационных ссылок `e1cib/...`. Не передавай туда псевдокоманды/команды формы вроде `ФормаНайти`, `СледующаяСтрока`, `СписокВывестиСписок`; для них нужны отдельные first-class MCP tools.
+- После каждого действия проверяй диагностику результата: `client_diagnostics.user_messages`, `error_info`, `modal_title`, `modal_buttons`, `modal_text`, `modal_texts`, `modal_is_error_window`.
+- Не закрывай автоматически сложные диалоги с несколькими кнопками (`OK`, `Restart`, `Finish`, `Yes/No/Cancel`). Допустимо автозакрытие только простых предупреждений/ошибок с одной кнопкой закрытия.
+- Для динамических списков предпочитай `table_move_row`, `table_current_row`, `table_selected_rows`, `table_cell_text`; `table_rows` использует навигационный fallback, но на больших списках может быть дорогим.
+- Не заявляй выполнение UI-задачи без реального состояния/скриншота/PDF evidence.
+- `base_url` — единый target подключения. `http(s)` трактуется как web/ws URL, строки вида `server/infobase` — как серверные базы (`/S`), каталоги с `1Cv8.1CD` — как файловые базы (`/F` или через `ibsrv`). Не передавай явные параметры режима запуска клиента тестирования.
+- Если ошибка авторизации возникла при пароле из одних звёздочек (`***`, `********`), явно сообщи пользователю, что был передан плейсхолдер вместо реального пароля; попроси указать настоящий пароль или сохранить корректные креды через `credentials_save()`.
+- Если кластер 1С возвращает короткое имя рабочего сервера (`server_addr=...`), оно должно резолвиться и быть доступным по TCP с хоста Answer42; это не проблема ws/http.
+
+## Типовой запуск
+
+Web/ws база:
+
+```text
+sessions_list()
+start_session(
+  base_url="https://example.com/ib",
+  username="<USERNAME>",
+  password="<PASSWORD>",
+  version="8.5.1.1150"
+)
+active_window()
+```
+
+Серверная база кластера 1С:
+
+```text
+start_session(
+  base_url="server/infobase",
+  username="<USERNAME>",
+  password="<PASSWORD>",
+  version="8.5.1.1150"
+)
+```
+
+Файловая база:
+
+```text
+start_session(
+  base_url="/path/to/file-infobase",
+  username="<USERNAME>",
+  password="<PASSWORD>",
+  version="8.5.1.1150"
+)
+```
+
+Режим клиента тестирования выбирается автоматически по `base_url`: `http(s)` → `ws`, каталог/`1Cv8.1CD` → `file`, прочее непустое `server/infobase` → `server`.
+
+## Навигация
+
+- Открывай формы/списки через `execute_window_command` с `e1cib/list/...` или `e1cib/app/...`, когда доступно.
+- Для поиска объектов используй `find_object`, `activate_object`, `ui_tree`. `ui_tree` по умолчанию показывает только видимые/активные для пользователя элементы и всегда добавляет `visible/available/enabled/read_only`; для полной диагностики скрытых страниц/элементов передавай `include_hidden=true`.
+- Для команд формы используй специализированные MCP tools (`table_move_row`, `dynamic_list_*`, `click_button`, `activate_object` и т.п.). `command_bar` можно использовать для диагностики доступных команд, но не прокидывай имена команд в `execute_window_command`.
+- `dynamic_list_output`, `dynamic_list_open_settings`, `dynamic_list_clear_settings`, `dynamic_list_open_form_settings` нажимают кнопки формы через test-client API (`НайтиКнопку` + `Нажать()`), а не выполняют имена команд через `ВыполнитьКоманду()`. Если авто-кандидат не подходит, передавай `button` — техническое имя или заголовок кнопки.
+
+## Динамические списки: добавление вложенных полей через «Изменить форму»
+
+⚠️ **Текущее ограничение**: форма пользовательской настройки **«Изменить форму»** частично недоступна для надёжной автоматизации через API клиента тестирования. Команда **«Добавить поля»** (кнопка с плюсом в верхней панели формы настройки) может быть видна на скриншоте и в диагностическом тексте, но не нажиматься как обычная `ТестируемаяКнопкаФормы`: `click_button` может не находить её, а `activate_object` может вернуть `activated=true` без открытия диалога добавления полей. Не используйте X11-клики как обходной путь.
+
+Для проверяемых сценариев фильтрации динамических списков используйте **«Настроить список...»** и доступные поля компоновщика; для вывода вложенной колонки через **«Изменить форму»** текущая архитектура не гарантирует выполнение.
+
+Когда нужно вывести в динамический список поле связанного объекта (например телефон пользователя, дата приглашения регистрации, реквизит контрагента/номенклатуры/абонента):
+
+1. Сначала проверь метаданные и типы полей через RAG MCP (`rag_lookup_object`, `rag_query`) или локальный metadata index. Нужно понять, какие поля динамического списка имеют ссылочный тип и к какому объекту они ведут.
+2. Если RAG не умеет вычислять поля динамического списка и их типы, доработай RAG/indexer, чтобы он извлекал поля динамических списков из форм/запросов/основной таблицы и сопоставлял ссылочные поля с объектами метаданных. Не угадывай цепочки ссылок без проверки.
+3. Открой форму списка и нажми `dynamic_list_open_form_settings(button="Изменить форму...")`.
+4. В форме **«Изменить форму»** выбери поле динамического списка ссылочного типа. Примеры: `Ссылка` для текущего объекта списка, `Контрагент`, `Номенклатура`, `Абонент`, `Пользователь` и т.п.
+5. После выбора ссылочного поля нажми кнопку **«Добавь поля»** (это кнопка с плюсом). Не путай с `ДобавитьСтроку()`/Insert: нужна именно команда добавления полей формы.
+6. В появившейся структуре добавляемых полей нужно **поставить флажки** возле нужных полей связанного объекта метаданных. Простого выделения строки недостаточно.
+7. Подтверди выбор и заверши редактирование формы. Выбранное вложенное поле появится в динамическом списке и станет доступно для просмотра/проверки.
+8. Операцию можно повторять цепочкой: например сначала из `Пользователь` вывести ссылку на `Приглашение регистрации`, затем вторым проходом из `Приглашение регистрации` вывести `Дата`.
+9. Для фильтрации используй `dynamic_list_open_settings(button="Настроить список...")` и добавляй отбор по уже известному/доступному полю; для вывода колонки именно в список используй **«Изменить форму»**, а не только настройку отбора.
+
+## Таблицы и табличные части
+
+- `table_current_row(table_name)` — получить текущую строку как `{available, pairs:[{key,value}]}`.
+- `table_selected_rows(table_name)` — получить выделенные строки в том же JSON-safe формате.
+- `table_cell_text(table_name, cell)` — вызвать `ПолучитьТекстЯчейки(<Ячейка>)`; пустой `cell` возвращает текущую ячейку. Для 1С обычно нужны технические имена полей (`РазмерФайла`), а не видимые заголовки (`Размер файла`).
+- `table_move_row(table_name, direction, steps)` — штатная навигация по строкам: `first`, `last`, `next`, `previous`; для иерархических таблиц также `expand`, `collapse`, `level_down`, `level_up`.
+- `table_rows(table_name)` — получить строки, если объект поддерживает чтение; для динамических списков использует навигацию.
+- `table_find_row(table_name, substring)` — найти строку.
+- `table_goto_row(table_name, index)` — перейти к строке.
+- `table_set_field(table_name, field, value)` — установить значение ячейки.
+- `table_edit_info(table_name)` — понять доступные поля редактирования.
+
+## Диагностика
+
+При сбоях запуска или непонятных ошибках:
+
+```text
+session_status(session_id="...")
+sessions_list()
+export_eventlog(...)
+```
+
+Журнал автономного сервера — основной источник диагностики 1С runtime ошибок.
+
+Для серверной базы 1С (`/S server/infobase`) проверяй отдельно:
+
+- DNS/FQDN/короткое имя рабочего сервера, которое возвращает кластер;
+- доступность портов агента/рабочих процессов (`1540+`, `1560+` и фактический `server_addr=tcp://...` из лога клиента);
+- соответствие версии платформы клиента версии кластера;
+- если в логе/окне есть `Различаются версии клиента и сервера ( 8.3.27.1234 - 8.3.27.7890)`, `Несоответствие версий клиента и сервера 1С:Предприятие 8` или `Требуется установка новой версии 1С:Предприятия`, останови текущую сессию и перезапусти `start_session` с `version` версии сервера 1С;
+- фактическую ошибку в `/tmp/mcp_test_client/test_client_*.log`.
+
+## Evidence recording
+
+- Включай `recording_start` перед демонстрационным workflow и завершай `recording_stop`.
+- Ожидаемые артефакты: `manifest.json` и `recording.pdf` при наличии Chrome/Chromium/Edge или ImageMagick.
+- MP4/GIF/HTML evidence больше не поддерживаются как публичные артефакты; не обещай и не прикладывай их.
+
+## Разработка bridge
+
+Если задача именно про доработку репозитория `Answer42`:
+
+- CF собирать кроссплатформенно: `python scripts/build_cf.py src/cf build/MCPTestManager.cf` и аналогично для `src/client_cf`. Приоритетный способ — `ibcmd config import` (не требует Конфигуратора); если `ibcmd` отсутствует, скрипт автоматически переключается на Конфигуратор/DESIGNER через `1cv8`. Скрипт сам добавляет `src` в `sys.path`; Bash-синтаксис `PYTHONPATH=src python ...` в PowerShell не работает.
+- Не использовать удалённые `.sh`-скрипты (`build_cf.sh`, `export_eventlog.sh`).
+- Для E2E использовать `scripts/e2e_stable.py`; долгий `dynamic` сценарий разделён на `dynamic-tables`, `dynamic-lists`, `dynamic-reports`.
+- `start_session` автоматически пересобирает `build/MCPTestManager.cf`, если он отсутствует или XML-исходники новее; demo-клиент аналогично пересобирает `build/MCPTestClient.cf`. В PyPI wheel при отсутствии XML/скрипта используются packaged `mcp_1c.assets/*.cf`, поэтому перед релизом обязательно пересобрать и обновить `src/mcp_1c/assets/MCPTestManager.cf` и `src/mcp_1c/assets/MCPTestClient.cf`. После изменения Python/BSL прогонять минимум `py_compile`, unit tests и сборку CF; для UI-изменений — smoke E2E с PDF evidence.

mcp_1c/assets/skills/answer42-rag/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: "answer42-rag"
+description: "RAG-индекс 1С metadata через Answer42"
+---
+
+# Answer42 RAG
+
+Используй этот скилл, когда нужно искать по исходникам 1С через RAG/index MCP `Answer42`: EDT-исходники, XML-выгрузка Конфигуратора, base + extensions, регистры, формы, СКД отчётов.
+
+## Что индексируется
+
+- Объекты метаданных: справочники, документы, обработки, отчёты, перечисления, общие модули, регистры сведений/накопления/бухгалтерии/расчёта.
+- Реквизиты объектов.
+- Регистры: роли полей `dimension`, `resource`, `attribute`, `standard_attribute`.
+- Табличные части и колонки.
+- Формы и элементы форм, где доступны XML-исходники.
+- СКД отчётов: поля наборов данных, вычисляемые поля, итоговые поля (`dataPath`, `field`, `title`, `expression`).
+- Навигационные ссылки `e1cib/list/...` и `e1cib/app/...`.
+
+## Типовой workflow
+
+```text
+rag_source_detect(path)
+rag_source_add(name="MS", path="/path/to/MS/src", kind="base", format="auto")
+rag_source_add(name="Platform42", path="/path/to/Platform42/src", kind="extension", format="auto")
+rag_snapshot_create(name="MS+Platform42", base="MS", extensions=["Platform42"])
+rag_index_build(snapshot="MS+Platform42")
+rag_lookup_object(object="РегистрСведений.РезервныеКопииОбластейДанных", snapshot="MS+Platform42")
+rag_query(query="резервные копии длительность", snapshot="MS+Platform42", limit=10)
+```
+
+## CLI-эквивалент
+
+```bash
+python3 scripts/rag_cli.py add-source MS /path/to/MS/src --kind base
+python3 scripts/rag_cli.py add-source Platform42 /path/to/Platform42/src --kind extension
+python3 scripts/rag_cli.py snapshot MS+Platform42 --base MS --extension Platform42
+python3 scripts/rag_cli.py build --snapshot MS+Platform42
+python3 scripts/rag_cli.py lookup РегистрСведений.РезервныеКопииОбластейДанных --snapshot MS+Platform42
+python3 scripts/rag_cli.py query "резервные копии" --snapshot MS+Platform42
+```
+
+## Как читать результаты
+
+- `matches[].source_name` показывает слой (`MS`, `Platform42`, и т.п.).
+- `attributes[].role`:
+  - `dimension` — измерение регистра;
+  - `resource` — ресурс регистра;
+  - `attribute` — реквизит;
+  - `standard_attribute` — стандартное поле платформы.
+- `data_composition_fields[]` содержит поля СКД отчётов; для вычисляемых/итоговых смотри `expression`.
+- Если объект не найден в extension-слое, обязательно проверь base-слой перед выводом «не найдено».
+
+## Ограничения
+
+- RAG — это индекс исходников, не live runtime; для фактических данных базы используй UI/test-client или отдельный контролируемый запрос.
+- СКД индексируется минимум по полям и выражениям; тело запроса СКД может потребовать ручного чтения `Template.dcs`.
+- SQLite/FTS — слой поиска. Источником истины остаются файлы `.mdo`, `.xml`, `.dcs`.

mcp_1c/bridge.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import uuid
+from dataclasses import dataclass, field
+from typing import Any
+
+import websockets
+from websockets.exceptions import ConnectionClosed
+from websockets.server import WebSocketServer, WebSocketServerProtocol
+
+from .protocol import BridgeRequest, BridgeResponse
+
+LOGGER = logging.getLogger(__name__)
+
+
+class BridgeError(RuntimeError):
+    """Raised when the 1C bridge is not connected or returns an error."""
+
+
+@dataclass(slots=True)
+class ConnectedBridge:
+    websocket: WebSocketServerProtocol
+    peer: str
+    pending: dict[str, asyncio.Future[BridgeResponse]] = field(default_factory=dict)
+
+
+class OneCBridgeServer:
+    """JSON-RPC-like WebSocket server for the embedded 1C manager processor."""
+
+    def __init__(self, host: str = "127.0.0.1", port: int = 8765, request_timeout: float = 60.0):
+        self.host = host
+        self.port = port
+        self.request_timeout = request_timeout
+        self._server: WebSocketServer | None = None
+        self._bridge: ConnectedBridge | None = None
+        self._lock = asyncio.Lock()
+
+    @property
+    def url(self) -> str:
+        return f"ws://{self.host}:{self.port}/bridge"
+
+    async def start(self) -> None:
+        if self._server is not None:
+            return
+        self._server = await websockets.serve(self._handler, self.host, self.port)
+        LOGGER.info("1C WebSocket bridge is listening on %s", self.url)
+
+    async def stop(self) -> None:
+        if self._server is not None:
+            self._server.close()
+            await self._server.wait_closed()
+            self._server = None
+
+    def status(self) -> dict[str, Any]:
+        bridge = self._bridge
+        return {
+            "websocket_url": self.url,
+            "connected": bridge is not None,
+            "peer": bridge.peer if bridge else None,
+            "pending": len(bridge.pending) if bridge else 0,
+        }
+
+    async def call(self, method: str, params: dict[str, Any] | None = None) -> Any:
+        bridge = self._bridge
+        if bridge is None:
+            raise BridgeError("1C bridge is not connected. Start the 1C manager first.")
+
+        request_id = str(uuid.uuid4())
+        future: asyncio.Future[BridgeResponse] = asyncio.get_running_loop().create_future()
+        bridge.pending[request_id] = future
+        request = BridgeRequest(id=request_id, method=method, params=params or {})
+
+        try:
+            await bridge.websocket.send(json.dumps(request.to_json(), ensure_ascii=False))
+            response = await asyncio.wait_for(future, timeout=self.request_timeout)
+        finally:
+            bridge.pending.pop(request_id, None)
+
+        if not response.ok:
+            raise BridgeError(response.error or f"1C bridge command {method!r} failed")
+        return response.result
+
+    async def _handler(self, websocket: WebSocketServerProtocol) -> None:
+        peer = f"{websocket.remote_address}"
+        connected = ConnectedBridge(websocket=websocket, peer=peer)
+
+        async with self._lock:
+            if self._bridge is not None:
+                await websocket.close(code=1013, reason="Only one 1C bridge connection is supported")
+                return
+            self._bridge = connected
+
+        try:
+            async for raw_message in websocket:
+                await self._process_message(connected, raw_message)
+        except ConnectionClosed:
+            # Normal during session teardown: 1C process may disappear before the
+            # websocket close frame is exchanged.  Pending callers still get a
+            # BridgeError in finally below.
+            pass
+        finally:
+            async with self._lock:
+                if self._bridge is connected:
+                    self._bridge = None
+            for future in connected.pending.values():
+                if not future.done():
+                    future.set_exception(BridgeError("1C bridge disconnected"))
+            LOGGER.info("WebSocket bridge %s disconnected", peer)
+
+    async def _process_message(self, bridge: ConnectedBridge, raw_message: str | bytes) -> None:
+        if isinstance(raw_message, bytes):
+            raw_message = raw_message.decode("utf-8")
+        try:
+            data = json.loads(raw_message)
+        except json.JSONDecodeError:
+            LOGGER.warning("Ignoring non-JSON bridge message: %r", raw_message)
+            return
+
+        message_type = data.get("type")
+        if message_type in {"hello", "event"}:
+            LOGGER.info("1C bridge %s: %s", message_type, data)
+            return
+        if message_type != "response":
+            LOGGER.warning("Ignoring unknown bridge message: %s", data)
+            return
+
+        response = BridgeResponse.from_json(data)
+        future = bridge.pending.get(response.id)
+        if future is None:
+            LOGGER.warning("Response for unknown request id %s: %s", response.id, data)
+            return
+        if not future.done():
+            future.set_result(response)

mcp_1c/credentials.py

@@ -0,0 +1,147 @@
+"""Secure credential store for 1C infobase URLs.
+
+Reads a JSON file mapping base URLs (exact or wildcard) to
+{username, password}.  The file is never committed to git;
+a sample ``credentials.example.json`` is provided for reference.
+
+Environment variable ``ONEC_MCP_CREDENTIALS_FILE`` overrides the
+default path (``~/.onec-mcp-credentials.json``).
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import json
+import logging
+import os
+from pathlib import Path
+LOGGER = logging.getLogger(__name__)
+
+DEFAULT_CREDENTIALS_PATH = Path(
+    os.getenv("ONEC_MCP_CREDENTIALS_FILE",
+              str(Path.home() / ".onec-mcp-credentials.json"))
+)
+
+
+class CredentialsStore:
+    """Look up 1C credentials by base URL.
+
+    File format (JSON)::
+
+        {
+          "entries": [
+            {
+              "url": "https://example.invalid/infobase",
+              "username": "user",
+              "password": "secret"
+            },
+            {
+              "url": "https://*.example.invalid/*",
+              "username": "wildcard-user",
+              "password": "wildcard-secret"
+            }
+          ]
+        }
+
+    Matching rules (first match wins):
+      * exact ``url`` match
+      * ``fnmatch`` wildcard match (``*``, ``?``, ``[seq]``)
+    """
+
+    def __init__(self, path: Path | str | None = None) -> None:
+        self._path = Path(path or DEFAULT_CREDENTIALS_PATH)
+        self._entries: list[dict[str, str]] = []
+        self._load()
+
+    # ------------------------------------------------------------------
+    # public API
+    # ------------------------------------------------------------------
+
+    def lookup(self, base_url: str) -> dict[str, str] | None:
+        """Return {username, password} for *base_url*, or None."""
+        url = base_url.rstrip("/")
+        for entry in self._entries:
+            pattern = entry["url"].rstrip("/")
+            if url == pattern:
+                return {"username": entry["username"], "password": entry["password"]}
+        for entry in self._entries:
+            pattern = entry["url"].rstrip("/")
+            if fnmatch.fnmatch(url, pattern):
+                return {"username": entry["username"], "password": entry["password"]}
+        return None
+
+    def list_entries(self) -> list[dict[str, str]]:
+        """Return credential URL patterns without usernames or passwords."""
+        return [{"url": e["url"]} for e in self._entries]
+
+    def upsert(self, url: str, username: str, password: str) -> bool:
+        """Add or update a credential entry for *url*.
+
+        Returns True when an existing entry was updated, False when a new entry
+        was created.  Usernames and passwords are intentionally not returned.
+        """
+        url = url.rstrip("/")
+        updated = False
+        for entry in self._entries:
+            if entry["url"].rstrip("/") == url:
+                entry["username"] = username
+                entry["password"] = password
+                updated = True
+                break
+        else:
+            self._entries.append({"url": url, "username": username, "password": password})
+        self._save()
+        return updated
+
+    def remove(self, url: str) -> bool:
+        """Remove the credential entry for *url* (exact match)."""
+        url = url.rstrip("/")
+        for i, entry in enumerate(self._entries):
+            if entry["url"].rstrip("/") == url:
+                del self._entries[i]
+                self._save()
+                return True
+        return False
+
+    def reload(self) -> None:
+        """Re-read the credentials file (useful after external edits)."""
+        self._load()
+
+    # ------------------------------------------------------------------
+    # internal
+    # ------------------------------------------------------------------
+
+    def _save(self) -> None:
+        """Persist entries to the JSON file atomically."""
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = self._path.with_suffix(self._path.suffix + ".tmp")
+        tmp.write_text(json.dumps({"entries": self._entries}, indent=2, ensure_ascii=False),
+                       encoding="utf-8")
+        tmp.replace(self._path)
+        LOGGER.info("Saved %d credential entries to %s", len(self._entries), self._path)
+
+    def _load(self) -> None:
+        if not self._path.exists():
+            LOGGER.debug("Credentials file not found: %s", self._path)
+            self._entries = []
+            return
+        try:
+            data = json.loads(self._path.read_text(encoding="utf-8"))
+            self._entries = data.get("entries", [])
+            LOGGER.info("Loaded %d credential entries from %s",
+                        len(self._entries), self._path)
+        except Exception as exc:
+            LOGGER.warning("Failed to load credentials from %s: %s",
+                           self._path, exc)
+            self._entries = []
+
+
+# Singleton for the MCP server process
+_store: CredentialsStore | None = None
+
+
+def get_store(path: Path | str | None = None) -> CredentialsStore:
+    global _store
+    if _store is None:
+        _store = CredentialsStore(path)
+    return _store