cisternal 0.1.0a1__tar.gz

cisternal-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marielle Russo
+
+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.

cisternal-0.1.0a1/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: cisternal
+Version: 0.1.0a1
+Summary: Shared telemetry substrate and agent-asset export toolkit for the Praxia tool family
+Author: Marielle Russo
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/maraxen/cisternal
+Project-URL: Repository, https://github.com/maraxen/cisternal
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cyclopts>=4.18.0
+Requires-Dist: fastmcp>=3.4.2
+Requires-Dist: opentelemetry-api>=1.42.1
+Provides-Extra: otlp
+Requires-Dist: opentelemetry-sdk>=1.42.1; extra == "otlp"
+Requires-Dist: opentelemetry-semantic-conventions>=0.63b1; extra == "otlp"
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.42.1; extra == "otlp"
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.42.1; extra == "otlp"
+Dynamic: license-file
+
+# cisternal
+
+**Status: alpha.** APIs may change without notice before `1.0`.
+
+Cisternal is a shared telemetry substrate and agent-asset export toolkit for the Praxia tool family. It has two parts:
+
+- **Telemetry** — a lightweight, non-blocking event pipeline (JSONL export, OTLP export, MCP-tool registration wrapper) for instrumenting Python tools and MCP servers.
+- **Agent-asset export** — a CLI that takes a registry of MCP tools/commands and emits native plugin/config bundles for downstream coding-agent surfaces: Claude Code, Cursor, GitHub Copilot, and Antigravity.
+
+## Install
+
+```bash
+pip install cisternal
+```
+
+For OTLP export support:
+
+```bash
+pip install "cisternal[otlp]"
+```
+
+## Telemetry quickstart
+
+```python
+import cisternal
+
+cisternal.init()  # log_dir defaults to ~/.cisternal/logs, or env-resolved
+
+with cisternal.span("my.operation", request_id="abc123"):
+    do_work()
+
+cisternal.emit_event("my.custom_event", tool="foo")
+print(cisternal.status())
+```
+
+Check your effective telemetry configuration from the shell:
+
+```bash
+cisternal telemetry doctor
+cisternal telemetry doctor --json --strict
+```
+
+### Registering MCP tools
+
+```python
+import cisternal
+
+@cisternal.tool
+def my_tool(x: int) -> int:
+    return x * 2
+
+registry = cisternal.wire(server, app, adapter=my_adapter)
+```
+
+`cisternal.tool` is a pure-metadata decorator — it returns the original function unchanged. `cisternal.wire()` snapshots the registry at call time and registers each tool on a FastMCP server (and optionally a Cyclopts CLI app), returning a `WiredRegistry` for introspection.
+
+## Agent-asset export
+
+```bash
+# Preview what would be written, without touching disk
+cisternal assets export --dry-run
+
+# Write bundles for specific surfaces
+cisternal assets export --out ./dist/agent-assets
+
+# Inspect or validate an existing bundle
+cisternal assets inspect
+cisternal assets validate
+```
+
+Supported export targets: **Claude Code**, **Cursor**, **GitHub Copilot**, **Antigravity**.
+
+The CLI is fastmcp-free by design — `cisternal.cli` imports and runs even in environments without `fastmcp` installed; asset-export logic never depends on the telemetry/registration surface.
+
+## Design notes
+
+- Telemetry emission never raises: if the pipeline isn't initialized, `emit_event`/`span` are no-ops.
+- Registry state is process-scoped — call `cisternal.clear_registry()` between tests to avoid cross-test contamination.
+- The M2 wire-time MCP callable is a pure passthrough: telemetry and shape adaptation are exclusively owned by the telemetry middleware, never by the registration wrapper itself.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

cisternal-0.1.0a1/README.md

@@ -0,0 +1,83 @@
+# cisternal
+
+**Status: alpha.** APIs may change without notice before `1.0`.
+
+Cisternal is a shared telemetry substrate and agent-asset export toolkit for the Praxia tool family. It has two parts:
+
+- **Telemetry** — a lightweight, non-blocking event pipeline (JSONL export, OTLP export, MCP-tool registration wrapper) for instrumenting Python tools and MCP servers.
+- **Agent-asset export** — a CLI that takes a registry of MCP tools/commands and emits native plugin/config bundles for downstream coding-agent surfaces: Claude Code, Cursor, GitHub Copilot, and Antigravity.
+
+## Install
+
+```bash
+pip install cisternal
+```
+
+For OTLP export support:
+
+```bash
+pip install "cisternal[otlp]"
+```
+
+## Telemetry quickstart
+
+```python
+import cisternal
+
+cisternal.init()  # log_dir defaults to ~/.cisternal/logs, or env-resolved
+
+with cisternal.span("my.operation", request_id="abc123"):
+    do_work()
+
+cisternal.emit_event("my.custom_event", tool="foo")
+print(cisternal.status())
+```
+
+Check your effective telemetry configuration from the shell:
+
+```bash
+cisternal telemetry doctor
+cisternal telemetry doctor --json --strict
+```
+
+### Registering MCP tools
+
+```python
+import cisternal
+
+@cisternal.tool
+def my_tool(x: int) -> int:
+    return x * 2
+
+registry = cisternal.wire(server, app, adapter=my_adapter)
+```
+
+`cisternal.tool` is a pure-metadata decorator — it returns the original function unchanged. `cisternal.wire()` snapshots the registry at call time and registers each tool on a FastMCP server (and optionally a Cyclopts CLI app), returning a `WiredRegistry` for introspection.
+
+## Agent-asset export
+
+```bash
+# Preview what would be written, without touching disk
+cisternal assets export --dry-run
+
+# Write bundles for specific surfaces
+cisternal assets export --out ./dist/agent-assets
+
+# Inspect or validate an existing bundle
+cisternal assets inspect
+cisternal assets validate
+```
+
+Supported export targets: **Claude Code**, **Cursor**, **GitHub Copilot**, **Antigravity**.
+
+The CLI is fastmcp-free by design — `cisternal.cli` imports and runs even in environments without `fastmcp` installed; asset-export logic never depends on the telemetry/registration surface.
+
+## Design notes
+
+- Telemetry emission never raises: if the pipeline isn't initialized, `emit_event`/`span` are no-ops.
+- Registry state is process-scoped — call `cisternal.clear_registry()` between tests to avoid cross-test contamination.
+- The M2 wire-time MCP callable is a pure passthrough: telemetry and shape adaptation are exclusively owned by the telemetry middleware, never by the registration wrapper itself.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

cisternal-0.1.0a1/pyproject.toml

@@ -0,0 +1,76 @@
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cisternal"
+version = "0.1.0a1"
+description = "Shared telemetry substrate and agent-asset export toolkit for the Praxia tool family"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Marielle Russo" },
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+requires-python = ">=3.13"
+dependencies = [
+    "cyclopts>=4.18.0",
+    "fastmcp>=3.4.2",
+    "opentelemetry-api>=1.42.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/maraxen/cisternal"
+Repository = "https://github.com/maraxen/cisternal"
+
+[project.optional-dependencies]
+otlp = [
+    "opentelemetry-sdk>=1.42.1",
+    "opentelemetry-semantic-conventions>=0.63b1",
+    "opentelemetry-exporter-otlp-proto-grpc>=1.42.1",
+    "opentelemetry-exporter-otlp-proto-http>=1.42.1",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+    "pytest-asyncio>=0.24.0",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.15.17",
+    "ty>=0.0.49",
+    "opentelemetry-sdk>=1.42.1",
+    "opentelemetry-semantic-conventions>=0.63b1",
+    "opentelemetry-exporter-otlp-proto-grpc>=1.42.1",
+    "opentelemetry-exporter-otlp-proto-http>=1.42.1",
+]
+
+[project.scripts]
+cisternal = "cisternal.cli:app"
+
+[project.entry-points."cisternal.emitters"]
+claude = "cisternal.export.registry:claude_factory"
+cursor = "cisternal.export.registry:cursor_factory"
+copilot = "cisternal.export.registry:copilot_factory"
+antigravity = "cisternal.export.registry:antigravity_factory"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"cisternal.assets" = ["data/*.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "integration: requires external services (e.g. otel-collector on localhost)",
+    "golden_matrix: export trust digest matrix (M11)",
+]

cisternal-0.1.0a1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cisternal-0.1.0a1/src/cisternal/__init__.py

@@ -0,0 +1,150 @@
+"""Cisternal: Shared telemetry substrate for praxia tool family.
+
+Public API (spec §3.2 — M1 telemetry + M2 registration surface):
+
+  M1 — Telemetry:
+    init(log_dir, max_bytes, backup_count, exporters): Initialize pipeline
+    emit_event(name, **fields): Emit a telemetry event
+    span(name, **fields): Sync timing context manager
+    aspan(name, **fields): Async timing context manager
+    status(): Get pipeline health status
+
+  M2 — Registration surface (B+G2 hybrid design, challenger-hardened):
+    tool: Pure-metadata decorator for registering MCP tools (A1, A2).
+          @cisternal.tool returns the original fn unchanged (decorated_fn is fn).
+    wire(server, app, *, adapter, registry, expected, validate):
+          Snapshot a registry at call time and register each tool on a FastMCP
+          server (and optionally a Cyclopts App). Returns a WiredRegistry.
+    WiredRegistry: Introspection object returned by wire().
+    CisternalWireError: Raised by wire() when expected tools are missing.
+    clear_registry(name): Test teardown helper; clears a named registry (A7).
+
+Design assumptions (spec §assumptions):
+  A1 — FastMCP v3 uses asyncio.iscoroutinefunction() to decide whether to await
+        the tool callable. The generated MCP callable is always async def.
+  A2 — FastMCP v3 reads inspect.signature(fn) for JSON schema generation.
+        Explicit __signature__ injection (H1) controls what FastMCP sees.
+  A3 — M1 CisternalMiddleware is installed on the FastMCP server before wire()
+        is called. Telemetry and shape adaptation are M1's exclusive responsibility.
+  A4 — Cyclopts 4.18.0+ calls asyncio.run() for async def command functions when
+        no event loop is running; inside a running loop, use app.run_async().
+  A5 — Global registry state is process-scoped; no cross-process sharing.
+  A6 — Python >= 3.11 (asyncio.get_running_loop() is the stable API).
+  A7 — Test environments call cisternal.clear_registry() in teardown to prevent
+        cross-test registry contamination.
+
+HARD INVARIANT (C5/AC-M2-6):
+  The M2 wire-time MCP callable is a PURE PASSTHROUGH — it MUST NOT call any
+  adapter.emit_* or adapter.shape_* methods, or emit ANY telemetry. All
+  telemetry and shaping is exclusively owned by M1 CisternalMiddleware.
+"""
+
+from pathlib import Path
+from typing import Any
+
+from cisternal.telemetry import (
+    init_pipeline,
+    get_pipeline,
+    span,
+    aspan,
+    job_span,
+    status,
+    ExporterBase,
+    _build_record,
+)
+from cisternal.registration.decorator import tool
+from cisternal.registration.errors import CisternalWireError
+from cisternal.registration.registry import clear_registry
+
+# M3 (assets export)
+from cisternal.assets.spec import AssetSpec
+from cisternal.assets.bundle import AssetBundle
+from cisternal.assets.source import registry_assets
+from cisternal.export.base import Emitter
+from cisternal.export.claude import ClaudeEmitter
+from cisternal.export.write import write_bundle
+
+
+def init(
+    log_dir: str | Path | None = None,
+    max_bytes: int = 10_485_760,
+    backup_count: int = 5,
+    exporters: list[ExporterBase] | None = None,
+    heartbeat_interval: float = 30.0,
+) -> None:
+    """Initialize the telemetry pipeline (idempotent).
+
+    Args:
+        log_dir: Directory for JSONL logs. If None, resolves via env vars or defaults to ~/.cisternal/logs.
+        max_bytes: Max file size before rotation (default 10 MB).
+        backup_count: Number of backup files to keep.
+        exporters: Custom exporters. If None, uses JsonlExporter with log_dir.
+        heartbeat_interval: Seconds between liveness heartbeat probes (default 30s).
+    """
+    init_pipeline(
+        log_dir=log_dir,
+        max_bytes=max_bytes,
+        backup_count=backup_count,
+        exporters=exporters,
+        heartbeat_interval=heartbeat_interval,
+    )
+
+
+def emit_event(name: str, **fields: Any) -> None:
+    """Emit a telemetry event.
+
+    Snapshots contextvars on this thread, builds a Record, and enqueues
+    it for non-blocking export. Never raises.
+
+    Args:
+        name: Event name (e.g. 'mcp.call_start').
+        **fields: Event fields (e.g. tool='foo', request_id='xyz').
+    """
+    import time
+
+    pipeline = get_pipeline()
+    if pipeline is None:
+        return
+
+    record = _build_record(name, ts=time.time(), **fields)
+    if record is not None:
+        pipeline.emit(record)
+
+
+def _lazy_import(name: str) -> object:
+    """Lazy re-export for wire and WiredRegistry to defer fastmcp import."""
+    if name == "wire":
+        from cisternal.registration.wired import wire as _wire
+        return _wire
+    if name == "WiredRegistry":
+        from cisternal.registration.wired import WiredRegistry as _WiredRegistry
+        return _WiredRegistry
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __getattr__(name: str) -> object:
+    return _lazy_import(name)
+
+
+__all__ = [
+    # M1 — Telemetry
+    "init",
+    "emit_event",
+    "span",
+    "aspan",
+    "job_span",
+    "status",
+    # M2 — Registration surface
+    "tool",
+    "wire",
+    "WiredRegistry",
+    "CisternalWireError",
+    "clear_registry",
+    # M3 (assets export)
+    "AssetSpec",
+    "AssetBundle",
+    "registry_assets",
+    "Emitter",
+    "ClaudeEmitter",
+    "write_bundle",
+]

cisternal-0.1.0a1/src/cisternal/adapters/__init__.py

@@ -0,0 +1 @@
+"""Consumer adapters: FastMCP v3 middleware, v2 decorator, CLI."""

cisternal-0.1.0a1/src/cisternal/adapters/base.py

@@ -0,0 +1,221 @@
+"""AdapterBase: Consumer-agnostic adapter protocol (spec §3.6, §5.4).
+
+Each adapter owns the event-name set (ALLOWED_NAMES) and the response shape
+for its consumer (shape_ok/shape_error). The MCP wrappers (CisternalMiddleware,
+traced_tool) instantiate an adapter, delegate telemetry emission + shaping to it,
+and never re-raise exceptions (CH-5).
+
+(CH-9) Runtime name guard: emit_start/end/error check that the emitted name is
+in self.ALLOWED_NAMES; on mismatch, calls _swallow_name_error (stderr warn + continue).
+Tests monkeypatch _swallow_name_error to raise AssertionError instead.
+"""
+
+from abc import ABC, abstractmethod
+import json
+import sys
+from typing import Any
+
+from cisternal import emit_event
+
+
+class AdapterBase(ABC):
+    """Abstract base for MCP tool adapters (v3 middleware, v2 decorator, etc.).
+
+    Each subclass defines:
+    - ALLOWED_NAMES: frozenset[str] of event names this adapter may emit.
+    - shape_ok(tool_name, result): Transform success response.
+    - shape_error(tool_name, exc): Transform error response.
+    """
+
+    ALLOWED_NAMES: frozenset[str]
+
+    def emit_start(self, tool_name: str, arg_keys: list[str], request_id: str) -> None:
+        """Emit mcp.call_start event.
+
+        Args:
+            tool_name: Name of the tool being called.
+            arg_keys: Sorted list of argument keys (spec §3.7, §3.8).
+            request_id: Unique request ID for this invocation.
+        """
+        name = "mcp.call_start"
+        if name not in self.ALLOWED_NAMES:
+            self._swallow_name_error(name)
+        emit_event(name, tool=tool_name, arg_keys=arg_keys, request_id=request_id)
+
+    def emit_end(self, tool_name: str, request_id: str, duration_ms: float) -> None:
+        """Emit mcp.call_end event.
+
+        Args:
+            tool_name: Name of the tool that executed.
+            request_id: The request ID from emit_start.
+            duration_ms: Duration of execution in milliseconds.
+        """
+        name = "mcp.call_end"
+        if name not in self.ALLOWED_NAMES:
+            self._swallow_name_error(name)
+        emit_event(name, tool=tool_name, request_id=request_id, duration_ms=duration_ms)
+
+    def emit_error(self, tool_name: str, request_id: str, exc: BaseException) -> None:
+        """Emit mcp.tool_error event.
+
+        Args:
+            tool_name: Name of the tool that raised.
+            request_id: The request ID from emit_start.
+            exc: The exception that was raised.
+        """
+        name = "mcp.tool_error"
+        if name not in self.ALLOWED_NAMES:
+            self._swallow_name_error(name)
+        emit_event(
+            name,
+            tool=tool_name,
+            request_id=request_id,
+            exc_type=type(exc).__name__,
+            exc_msg=str(exc),
+        )
+
+    @abstractmethod
+    def shape_ok(self, tool_name: str, result: Any) -> Any:
+        """Shape a successful tool result for the consumer.
+
+        Args:
+            tool_name: Name of the tool (for context).
+            result: The result returned by the tool.
+
+        Returns:
+            Consumer-specific shaped response (dict, str, or other).
+        """
+        pass
+
+    @abstractmethod
+    def shape_error(self, tool_name: str, exc: BaseException, **fields: Any) -> Any:
+        """Shape an error response for the consumer (never re-raises).
+
+        Args:
+            tool_name: Name of the tool (for context).
+            exc: The exception that was caught.
+            **fields: Optional extra fields for the error envelope.
+
+        Returns:
+            Consumer-specific error shape (dict, str, or other).
+        """
+        pass
+
+    def _swallow_name_error(self, name: str) -> None:
+        """Handle illegal event name: log to stderr and return (warn-and-continue).
+
+        Tests may monkeypatch this to raise AssertionError (AC-NAMEFREEZE-4).
+
+        Args:
+            name: The illegal event name.
+        """
+        print(f"[cisternal] ILLEGAL event name: {name!r}", file=sys.stderr)
+
+
+class BathosAdapter(AdapterBase):
+    """Adapter for bathos v3 middleware.
+
+    Event names (spec §4.2): mcp.call_start, mcp.call_end, mcp.tool_error.
+    Response shape: dict envelope with ok/error_code/error/resolution_hint.
+    """
+
+    ALLOWED_NAMES = frozenset({"mcp.call_start", "mcp.call_end", "mcp.tool_error"})
+
+    def shape_ok(self, tool_name: str, result: Any) -> Any:
+        """Shape success: merge dict results, add envelope fields.
+
+        If result is a dict, spread it and add envelope.
+        Otherwise, return minimal envelope.
+        """
+        if isinstance(result, dict):
+            return {
+                **result,
+                "ok": True,
+                "error_code": None,
+                "error": None,
+                "resolution_hint": None,
+            }
+        return {
+            "ok": True,
+            "error_code": None,
+            "error": None,
+            "resolution_hint": None,
+        }
+
+    def shape_error(self, tool_name: str, exc: BaseException, **fields: Any) -> Any:
+        """Shape error: error envelope with error_code and message."""
+        return {
+            "ok": False,
+            "error_code": "INTERNAL",
+            "error": str(exc),
+            "resolution_hint": "",
+        }
+
+
+class ContemplexAdapter(AdapterBase):
+    """Adapter for contemplex v2 decorator (sync).
+
+    Event names (spec §4.2): mcp.call_start, mcp.call_end, mcp.tool_error.
+    Response shape: passthrough for success; err_envelope for error.
+    """
+
+    ALLOWED_NAMES = frozenset({"mcp.call_start", "mcp.call_end", "mcp.tool_error"})
+
+    def shape_ok(self, tool_name: str, result: Any) -> Any:
+        """Shape success: passthrough result unchanged."""
+        return result
+
+    def shape_error(self, tool_name: str, exc: BaseException, **fields: Any) -> Any:
+        """Shape error: use contemplex err_envelope if available, else fallback.
+
+        Tries to import contemplex.errors; if unavailable, returns basic dict.
+        """
+        try:
+            from contemplex.errors import ErrorCode, err_envelope
+
+            return err_envelope(ErrorCode.INTERNAL, f"{type(exc).__name__}: {exc}")
+        except ImportError:
+            # Fallback if contemplex is not available
+            return {"ok": False, "error_code": "INTERNAL", "error": str(exc)}
+
+
+class XpeririAdapter(AdapterBase):
+    """Adapter for xperiri v2 decorator (sync, JSON-string MCP returns).
+
+    Event names (spec §4.2): mcp.call_start, mcp.call_end, mcp.tool_error.
+    Response shape: JSON string for success and error (xperiri MCP tools return str).
+    """
+
+    ALLOWED_NAMES = frozenset({"mcp.call_start", "mcp.call_end", "mcp.tool_error"})
+
+    def shape_ok(self, tool_name: str, result: Any) -> Any:
+        """Shape success: passthrough str; serialize dict/other to JSON."""
+        if isinstance(result, str):
+            return result
+        return json.dumps(result, sort_keys=True)
+
+    def shape_error(self, tool_name: str, exc: BaseException, **fields: Any) -> Any:
+        """Shape error: JSON string envelope matching xperiri error returns."""
+        payload: dict[str, Any] = {"ok": False, "error": str(exc)}
+        payload.update(fields)
+        return json.dumps(payload, sort_keys=True)
+
+
+class MyxcelAdapter(AdapterBase):
+    """Adapter for myxcel v2 decorator (async MCP tools, dict returns).
+
+    Event names (spec §4.2): mcp.call_start, mcp.call_end, mcp.tool_error.
+    Response shape: dict passthrough; errors use {error, message} per myxcel.mcp_server._tool_error.
+    """
+
+    ALLOWED_NAMES = frozenset({"mcp.call_start", "mcp.call_end", "mcp.tool_error"})
+
+    def shape_ok(self, tool_name: str, result: Any) -> Any:
+        """Shape success: passthrough dict/list results (myxcel in-band errors included)."""
+        if isinstance(result, (dict, list)):
+            return result
+        return {"result": result}
+
+    def shape_error(self, tool_name: str, exc: BaseException, **fields: Any) -> Any:
+        """Shape error: myxcel _tool_error envelope."""
+        return {"error": type(exc).__name__, "message": str(exc)}