server.py

"""Reference MCP transport for a cartridge.

A cartridge = a local MCP server exposing the slot contract as three tools. Any
MCP-capable host (Claude today; others as MCP spreads) consumes it through the tool
boundary, which hides the encoder for free -- satisfying the portability boundary rule.

Run standalone (stdio):  .venv/Scripts/python.exe server.py
"""

from __future__ import annotations

from mcp.server.fastmcp import FastMCP

from stub_cartridge import StubCartridge

mcp = FastMCP("aporia-engine")

# v1: one cartridge loaded at a time (local resource constraint). Swap this line to
# load a different cartridge; lifecycle = the process itself (start=load, stop=free).
CARTRIDGE = StubCartridge()


@mcp.tool()
def describe() -> dict:
    """Identity + routing descriptor for the loaded cartridge."""
    return dict(CARTRIDGE.describe())


@mcp.tool()
def assess(raw_input: str) -> dict:
    """(a) Calibration: energy = how well raw_input fits the cartridge's world.
    LOW energy = fits (in-domain). HIGH energy = out-of-domain / doesn't fit."""
    return dict(CARTRIDGE.assess(raw_input))


@mcp.tool()
def predict(raw_input: str, horizon: int = 1) -> dict:
    """(b) Reasoning: latent rollout. STUBBED in v1 (shape reserved)."""
    return dict(CARTRIDGE.predict(raw_input, horizon))


if __name__ == "__main__":
    mcp.run()