chemenu/tools/chemenu/mcp/__main__.py

"""`python -m chemenu.mcp` - start the read server.

Deliberately argparse and not typer. This process is the one place that must
not pull the CLI head in: the whole point of the library boundary is that a
second consumer costs `yaml`, `jsonschema` and the MCP SDK, and nothing else.

    python -m chemenu.mcp                                  # stdio
    python -m chemenu.mcp --transport streamable-http      # behind the proxy
    CHEMENU_ROOT=/srv/wiki python -m chemenu.mcp --transport streamable-http \
        --host 0.0.0.0 --port 8000

`--host`/`--port` apply to `streamable-http` only. They are here because the
default binds loopback, and a server in a container with a reverse proxy in
front of it has to bind an interface the proxy can reach - that is a property
of the software, not of one installation. *Which* host and port a given
deployment picks is infrastructure and stays out of this repository.
"""
from __future__ import annotations

import argparse
import sys

from chemenu.mcp.server import TRANSPORTS, TraceWouldWriteIntoCorpus, serve


def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(
        prog="python -m chemenu.mcp",
        description="Serve a Chemenu wiki read-only over MCP.",
    )
    parser.add_argument(
        "--transport",
        choices=TRANSPORTS,
        default="stdio",
        help="stdio for local use and testing; streamable-http for a deployed "
        "instance behind the Traefik middleware (default: stdio)",
    )
    parser.add_argument(
        "--root",
        default=None,
        help="The corpus to serve. Defaults to $CHEMENU_ROOT, then the checkout "
        "this package lives in.",
    )
    parser.add_argument(
        "--host",
        default="127.0.0.1",
        help="Interface to bind, streamable-http only. The loopback default is "
        "deliberate; a container behind a reverse proxy needs 0.0.0.0.",
    )
    parser.add_argument(
        "--port",
        type=int,
        default=8000,
        help="Port to bind, streamable-http only (default: 8000)",
    )
    args = parser.parse_args(argv)

    # Passed only for the transport they mean anything to: `run_stdio_async`
    # takes no host or port, and handing it one is a TypeError rather than a
    # harmless no-op.
    bind = (
        {"host": args.host, "port": args.port}
        if args.transport == "streamable-http"
        else {}
    )

    try:
        serve(transport=args.transport, root=args.root, **bind)
    except TraceWouldWriteIntoCorpus as exc:
        # Refused before binding anything: the message names both fixes, and a
        # server that silently relocated the operator's telemetry instead would
        # be a surprise buried in a log.
        print(f"ERROR {exc}", file=sys.stderr)
        return 1
    return 0


if __name__ == "__main__":  # pragma: no cover - process entry point
    raise SystemExit(main())