sie-mcp 0.8.0__py3-none-any.whl

sie_mcp/app.py

@@ -0,0 +1,37 @@
+"""ASGI app for the SIE MCP edge: MCP streamable-HTTP transport + auth + health."""
+
+import logging
+
+from starlette.applications import Starlette
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+from starlette.routing import Route
+
+from sie_mcp.auth import ConnectorSecretAuthMiddleware
+from sie_mcp.config import MCPConfig
+from sie_mcp.oauth import build_oauth_routes
+from sie_mcp.server import build_server
+
+logger = logging.getLogger(__name__)
+
+
+async def _healthz(_request: Request) -> JSONResponse:
+    return JSONResponse({"status": "ok"})
+
+
+def build_app() -> Starlette:
+    """Construct the ASGI app (uvicorn factory target)."""
+    config = MCPConfig.from_env()
+    app = build_server(config).streamable_http_app()
+    app.router.routes.append(Route("/healthz", _healthz, methods=["GET"]))
+    if config.oauth_enabled:
+        if not config.public_base_url:
+            logger.warning(
+                "SIE_MCP_PUBLIC_URL is unset: OAuth metadata is served only for loopback or SIE_MCP_ALLOWED_HOSTS "
+                "Host headers. Pin SIE_MCP_PUBLIC_URL to the public https origin for any exposed deployment."
+            )
+        # The OAuth bridge lets claude.ai connectors authenticate via the connector
+        # secret; the gate below exempts these bootstrap endpoints.
+        app.router.routes.extend(build_oauth_routes(config))
+    app.add_middleware(ConnectorSecretAuthMiddleware, config=config)
+    return app

sie_mcp/auth.py

@@ -0,0 +1,173 @@
+"""Connector-secret authentication at the MCP edge.
+
+A per-user connector secret (Bearer) is validated here and mapped to a stable
+user identity, so per-user metering can attach later. The cluster
+credential the service uses downstream is held server-side and never travels
+through this edge.
+
+Implemented as pure ASGI (not ``BaseHTTPMiddleware``) so it does not buffer the
+streaming MCP responses.
+"""
+
+import re
+from ipaddress import IPv6Address
+from typing import Any
+
+from starlette.datastructures import Headers
+from starlette.responses import JSONResponse
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+from sie_mcp.config import MCPConfig
+
+# The OAuth bridge endpoints bootstrap auth for claude.ai connectors, so they sit
+# in front of the connector-secret gate. Metadata + DCR + authorize + token
+# must all be reachable unauthenticated.
+_EXEMPT_PATHS = frozenset(
+    {
+        "/healthz",
+        "/.well-known/oauth-protected-resource",
+        "/.well-known/oauth-protected-resource/mcp",
+        "/.well-known/oauth-authorization-server",
+        "/register",
+        "/authorize",
+        "/token",
+    }
+)
+
+
+_LOOPBACK_HOSTNAMES = frozenset({"localhost", "127.0.0.1", "[::1]"})
+
+_MAX_PORT = 65535
+
+# RFC 9110 s7.2: a Host header is "uri-host [ ':' port ]" and carries no userinfo,
+# path, query, or fragment.
+_HOST_RE = re.compile(
+    r"""
+    \A
+    (?:
+        \[(?P<ipv6>[0-9a-f:.]+)\]
+      | (?P<regname>[0-9a-z._~!$&'()*+,;=%-]+)
+    )
+    (?::(?P<port>[0-9]{1,5}))?
+    \Z
+    """,
+    re.VERBOSE,
+)
+
+
+def _split_host_port(host: str) -> tuple[str, str | None] | None:
+    """Split a lowercased ``Host`` into ``(hostname, port)``, or ``None`` if malformed."""
+    match = _HOST_RE.fullmatch(host)
+    if match is None:
+        return None
+    port = match["port"]
+    if port is not None and not 1 <= int(port) <= _MAX_PORT:
+        return None
+    ipv6 = match["ipv6"]
+    if ipv6 is not None:
+        try:
+            IPv6Address(ipv6)
+        except ValueError:
+            return None
+    return (f"[{ipv6}]" if ipv6 is not None else match["regname"]), port
+
+
+def _host_trusted(config: MCPConfig, host: str) -> bool:
+    host = host.lower()
+    parsed = _split_host_port(host)
+    if parsed is None:
+        return False
+    hostname, port = parsed
+    if hostname in _LOOPBACK_HOSTNAMES:
+        return True
+    for allowed in (entry.lower() for entry in config.allowed_hosts):
+        if host == allowed:
+            return True
+        if allowed.endswith(":*") and port is not None and hostname == allowed[:-2]:
+            return True
+    return False
+
+
+def base_url(config: MCPConfig, *, scheme: str, headers: Headers) -> str | None:
+    """Resolve the externally reachable origin for OAuth metadata URLs.
+
+    Prefers the pinned ``SIE_MCP_PUBLIC_URL``. Unpinned, the request's own scheme and
+    ``Host`` are used only when the host is loopback or listed in
+    ``SIE_MCP_ALLOWED_HOSTS``; otherwise ``None``. This origin names the authorization
+    server clients trust, so caller-controlled ``Host`` and ``X-Forwarded-*`` values are
+    never advertised. A proxy-set scheme is honoured only through uvicorn's
+    ``FORWARDED_ALLOW_IPS`` trust list, which rewrites ``scheme`` upstream.
+    """
+    if config.public_base_url:
+        return config.public_base_url
+    host = headers.get("host") or ""
+    if not host or not _host_trusted(config, host):
+        return None
+    return f"{scheme}://{host}"
+
+
+def bearer_token(authorization: str | None) -> str | None:
+    if not authorization:
+        return None
+    value = authorization.strip()
+    if not value:
+        return None
+    if value[:7].lower() == "bearer ":
+        return value[7:].strip() or None
+    # A bare "Bearer" scheme with no token is not a credential.
+    if value.lower() == "bearer":
+        return None
+    # Otherwise accept a raw token sent without the scheme prefix.
+    return value
+
+
+def authenticate(config: MCPConfig, token: str | None) -> str | None:
+    """Return a user identity for the token, or ``None`` to reject the request."""
+    if config.connector_secrets:
+        if token and token in config.connector_secrets:
+            return config.connector_secrets[token]
+        if not token and config.allow_anonymous:
+            return "anonymous"
+        return None
+    # No secrets configured: open only when anonymous access is explicitly allowed.
+    return "anonymous" if config.allow_anonymous else None
+
+
+class ConnectorSecretAuthMiddleware:
+    """Pure-ASGI auth gate that maps a connector secret to a user identity."""
+
+    def __init__(self, app: ASGIApp, config: MCPConfig) -> None:
+        self._app = app
+        self._config = config
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http" or scope.get("path") in _EXEMPT_PATHS:
+            await self._app(scope, receive, send)
+            return
+
+        headers = Headers(scope=scope)
+        token = bearer_token(headers.get("authorization"))
+        identity = authenticate(self._config, token)
+        if identity is None:
+            response = JSONResponse(
+                {"error": "unauthorized"},
+                status_code=401,
+                headers=self._challenge_headers(scope, headers),
+            )
+            await response(scope, receive, send)
+            return
+
+        state: dict[str, Any] = dict(scope.get("state") or {})
+        state["user_id"] = identity
+        scope["state"] = state
+        await self._app(scope, receive, send)
+
+    def _challenge_headers(self, scope: Scope, headers: Headers) -> dict[str, str]:
+        """Point unauthenticated clients at the OAuth bridge (RFC 9728)."""
+        if not self._config.oauth_enabled:
+            return {}
+        origin = base_url(self._config, scheme=scope.get("scheme", "http"), headers=headers)
+        if origin is None:
+            return {}
+        metadata = f"{origin}/.well-known/oauth-protected-resource"
+        return {"WWW-Authenticate": f'Bearer resource_metadata="{metadata}"'}

sie_mcp/chunking.py

@@ -0,0 +1,70 @@
+"""Transient text chunking for ``answer_questions``.
+
+SIE has no chunking pipeline today, so this is a deliberately small,
+self-contained primitive: a fixed-size sliding character window with overlap. It
+runs entirely in the MCP edge per request — chunks are never persisted and no
+index is built, preserving a transient retrieval boundary.
+
+Character windows (not model-tokenizer windows) keep the job dependency-free and
+predictable; sizes are expressed in characters and approximate a token budget at
+the ~4-chars-per-token heuristic the edge already uses elsewhere. Precise token
+accounting is the cluster's job, not the edge's.
+"""
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Chunk:
+    """A single passage carved from one source document.
+
+    ``id`` is stable within a single call (``d{doc}-c{chunk}``) so the reranker
+    can echo it back; ``doc_index`` and ``start`` point back to the source so a
+    caller can locate the passage in the original text.
+    """
+
+    id: str
+    text: str
+    doc_index: int
+    start: int
+
+
+def chunk_text(text: str, *, window: int, overlap: int) -> list[tuple[int, str]]:
+    """Slide a fixed character window over ``text``, yielding ``(start, piece)``.
+
+    ``overlap`` characters are shared between neighbouring windows so a passage
+    straddling a boundary still lands whole in at least one window. Returns an
+    empty list for empty text.
+    """
+    if window <= 0:
+        msg = f"window must be positive, got {window}"
+        raise ValueError(msg)
+    if not 0 <= overlap < window:
+        msg = f"overlap must satisfy 0 <= overlap < window, got overlap={overlap}, window={window}"
+        raise ValueError(msg)
+    stride = window - overlap
+    windows: list[tuple[int, str]] = []
+    start = 0
+    length = len(text)
+    while start < length:
+        windows.append((start, text[start : start + window]))
+        if start + window >= length:
+            break
+        start += stride
+    return windows
+
+
+def chunk_documents(documents: Sequence[str], *, window: int, overlap: int) -> list[Chunk]:
+    """Chunk a set of documents into overlapping windows.
+
+    Empty / whitespace-only documents contribute no chunks. Chunk ids are unique
+    within the returned list, so a reranker can echo them back unambiguously.
+    """
+    chunks: list[Chunk] = []
+    for doc_index, document in enumerate(documents):
+        if not document or not document.strip():
+            continue
+        for chunk_index, (start, piece) in enumerate(chunk_text(document, window=window, overlap=overlap)):
+            chunks.append(Chunk(id=f"d{doc_index}-c{chunk_index}", text=piece, doc_index=doc_index, start=start))
+    return chunks

sie_mcp/cli.py

@@ -0,0 +1,173 @@
+"""CLI entry point for the SIE MCP edge service."""
+
+import logging
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+from pathlib import Path
+from typing import Annotated
+
+import typer
+import uvicorn
+
+from sie_mcp.plugin_pack import build_plugin_pack
+from sie_mcp.skill_zip import build_skill_zip, skill_name
+
+app = typer.Typer(name="sie-mcp", help="SIE MCP edge service.", no_args_is_help=True)
+
+_PACKAGE_ROOT = Path(__file__).resolve().parents[2]
+_DEFAULT_SKILL_MD = _PACKAGE_ROOT / "plugin" / "SKILL.md"
+_DEFAULT_COWORK_GUIDE = _PACKAGE_ROOT / "plugin" / "superlinked.md"
+_DEFAULT_CLAUDE_CODE_SKILLS_DIR = _PACKAGE_ROOT / "plugin" / "claude-code"
+
+
+def _setup_logging(level: str) -> None:
+    logging.basicConfig(
+        level=level.upper(),
+        format="%(asctime)s %(levelname)s %(name)s %(message)s",
+    )
+
+
+@app.command()
+def serve(
+    host: Annotated[str, typer.Option("--host", "-h", help="Host to bind to.")] = "0.0.0.0",  # noqa: S104 — intentional bind to all interfaces for the edge service
+    port: Annotated[int, typer.Option("--port", "-p", help="Port to listen on.")] = 8088,
+    log_level: Annotated[
+        str,
+        typer.Option("--log-level", "-l", envvar="SIE_LOG_LEVEL", help="Log level."),
+    ] = "info",
+    reload: Annotated[
+        bool,
+        typer.Option("--reload", "-r", help="Auto-reload for development."),
+    ] = False,
+) -> None:
+    """Start the MCP edge over remote streamable-HTTP."""
+    _setup_logging(log_level)
+    uvicorn.run(
+        "sie_mcp.app:build_app",
+        host=host,
+        port=port,
+        factory=True,
+        reload=reload,
+        log_level=log_level.lower(),
+    )
+
+
+@app.command("skill-zip")
+def skill_zip(
+    skill: Annotated[
+        Path,
+        typer.Option(
+            "--skill", "-s", help="Path to the SKILL.md to package (default: the surface-agnostic plugin/SKILL.md)."
+        ),
+    ] = _DEFAULT_SKILL_MD,
+    out: Annotated[
+        Path | None,
+        typer.Option("--out", "-o", help="Output .zip path (default: dist/<name>-skill.zip)."),
+    ] = None,
+) -> None:
+    """Package the surface-agnostic Superlinked Agent Skill as a claude.ai-uploadable ZIP."""
+    if not skill.is_file():
+        raise typer.BadParameter(f"SKILL.md not found at {skill}")
+    text = skill.read_text(encoding="utf-8")
+    data = build_skill_zip(text)
+    target = out or (_PACKAGE_ROOT / "dist" / f"{skill_name(text)}-skill.zip")
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_bytes(data)
+    typer.echo(f"wrote {target} ({len(data)} bytes)")
+
+
+@app.command("plugin-pack")
+def plugin_pack(
+    mcp_url: Annotated[
+        str,
+        typer.Option(
+            "--mcp-url",
+            envvar="SIE_MCP_URL",
+            help="Hosted or self-hosted MCP endpoint to install, e.g. https://mcp.example.com/mcp.",
+        ),
+    ],
+    connector_secret: Annotated[
+        str | None,
+        typer.Option(
+            "--connector-secret",
+            envvar="SIE_MCP_CONNECTOR_SECRET",
+            help=(
+                "Deprecated compatibility input; ignored and never used, written, or printed. "
+                "Provide the secret during connector installation."
+            ),
+        ),
+    ] = None,
+    cluster_label: Annotated[
+        str,
+        typer.Option("--cluster-label", help="Human-readable cluster label for the generated install guide."),
+    ] = "sie-cluster",
+    skill: Annotated[
+        Path,
+        typer.Option("--skill", "-s", help="Path to the surface-agnostic Superlinked SKILL.md to package."),
+    ] = _DEFAULT_SKILL_MD,
+    cowork_guide: Annotated[
+        Path | None,
+        typer.Option("--cowork-guide", help="Optional Cowork install guide to include in the pack."),
+    ] = _DEFAULT_COWORK_GUIDE,
+    claude_code_skills_dir: Annotated[
+        Path | None,
+        typer.Option(
+            "--claude-code-skills-dir",
+            help="Optional directory of Claude Code skill folders to include in the pack.",
+        ),
+    ] = _DEFAULT_CLAUDE_CODE_SKILLS_DIR,
+    out_dir: Annotated[
+        Path,
+        typer.Option("--out-dir", "-o", help="Output directory for the plugin pack."),
+    ] = _PACKAGE_ROOT / "dist" / "superlinked-docs-plugin",
+) -> None:
+    """Build a quick install pack for a hosted or self-hosted Superlinked MCP edge."""
+    if not skill.is_file():
+        raise typer.BadParameter(f"SKILL.md not found at {skill}")
+    cowork_text = None
+    if cowork_guide is not None:
+        if not cowork_guide.is_file():
+            raise typer.BadParameter(f"Cowork guide not found at {cowork_guide}")
+        cowork_text = cowork_guide.read_text(encoding="utf-8")
+    claude_code_skill_mds = []
+    if claude_code_skills_dir is not None:
+        if not claude_code_skills_dir.is_dir():
+            raise typer.BadParameter(f"Claude Code skills directory not found at {claude_code_skills_dir}")
+        claude_code_skill_mds = [
+            skill_file.read_text(encoding="utf-8") for skill_file in sorted(claude_code_skills_dir.glob("*/SKILL.md"))
+        ]
+    try:
+        report = build_plugin_pack(
+            skill.read_text(encoding="utf-8"),
+            mcp_url=mcp_url,
+            connector_secret=connector_secret,
+            cluster_label=cluster_label,
+            claude_code_skill_mds=claude_code_skill_mds,
+            cowork_guide_md=cowork_text,
+            out_dir=out_dir,
+        )
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+
+    typer.echo(f"wrote plugin pack to {report.out_dir}")
+    typer.echo(f"- install guide: {report.install_guide}")
+    typer.echo(f"- claude.ai skill ZIP: {report.skill_zip}")
+    for skill_path in report.claude_code_skills:
+        typer.echo(f"- Claude Code skill: {skill_path}")
+
+
+@app.command()
+def version() -> None:
+    """Show version information."""
+    try:
+        typer.echo(f"sie-mcp {_pkg_version('sie-mcp')}")
+    except PackageNotFoundError:
+        typer.echo("sie-mcp (version unknown)")
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()