agentruntime-mcp 0.0.1__tar.gz → 0.2.0__tar.gz

agentruntime_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: agentruntime-mcp
+Version: 0.2.0
+Summary: AgentRuntime MCP SDK (decorators, runtime, middleware, schemas, proxy)
+Author: AgentRuntime
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fastmcp>=2.10.0
+Requires-Dist: pydantic>=2
+Requires-Dist: starlette>=0.37
+Requires-Dist: uvicorn[standard]>=0.30
+Requires-Dist: opentelemetry-api>=1.25
+Requires-Dist: opentelemetry-sdk>=1.25
+Requires-Dist: opentelemetry-exporter-otlp>=1.25
+Requires-Dist: PyYAML>=6
+Requires-Dist: httpx>=0.25
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+
+# AgentRuntime MCP SDK (Python)
+
+Opinionated SDK for MCP connectors using **FastMCP** with the same **Control** integration as [`agentruntime-mcp-go`](https://github.com/agentruntime-io/agentruntime-mcp-go): optional `POST /mcp/config`, env merge, and request metadata (run token, instance id).
+
+There is **no mandatory legacy standalone token/HMAC middleware chain** in front of every request. Probe-style auth is the **Bearer run token** (or `X-MCP-Token`) and headers AgentRuntime sends; optional `auth.mode` in `config.yaml` is reserved for future templates and does not switch Control gating off.
+
+## Install
+
+```bash
+pip install agentruntime-mcp
+```
+
+## Runtimes
+
+| Entry | When to use | HTTP |
+|--------|-------------|------|
+| **`run(config_path)`** | Decorator-only `tool()` modules; tools registered from `config.yaml` / `build_schemas` | `/mcp` |
+| **`run_with_registry(config_path, *names)`** | Plugins registered with **`register_adapter`**; one process, one MCP server | `/mcp` |
+| **`run_with_router(config_path)`** | Same registry, **monolith routing** (Go **`RunWithRouter`** / TS **`runWithRouter`** parity) | `/{adapter}/mcp` plus optional **webhook** routes on the **same** ASGI app |
+
+Use **`register_adapter`** for anything that should share a process with other adapters. Keep plain **`run()`** for single-connector demos that only use decorators and YAML tools.
+
+**Webhooks:** Implement **`register_webhook(self, mux: ServeMux)`** on the adapter. Paths are registered on the **root** Starlette app **before** adapter mounts (same dispatch order as Go/TS). Operators expose vendor callbacks as `https://<host>:<port><path>` (same host/port as MCP).
+
+## Minimal example
+
+```python
+from pydantic import BaseModel, Field
+from agentruntime.mcp.decorators import tool
+from agentruntime.mcp.runtime import run
+from fastmcp import Context
+
+class In(BaseModel):
+    a: float = Field(...)
+    b: float = Field(...)
+
+class Out(BaseModel):
+    result: float
+    expression: str
+
+@tool(name="add", input_model=In, output_model=Out)
+def add(a: float, b: float, ctx: Context) -> Out:
+    region = ctx.config.region  # resolved config when schema + Control are used
+    return Out(result=a + b, expression=f"{a} + {b}")
+
+if __name__ == "__main__":
+    run("config.yaml")
+```
+
+## Config (`config.yaml`)
+
+- **`server`:** `name`, `host`, `port`, `stateless_http`
+- **`tracing`:** enable OpenTelemetry when dependencies are present
+- **`config`:** declarative schema for Control / `GET /mcp/config/schema`
+
+Env overrides: **`HOST`**, **`PORT`** (see [`docs/mcp/mcp_env.md`](../../docs/mcp/mcp_env.md)).
+
+Example:
+
+```yaml
+server:
+  name: "MyConnector"
+  host: "127.0.0.1"
+  port: 8012
+  stateless_http: true
+
+tracing:
+  enabled: false
+
+config:
+  apiKey:
+    type: string
+    displayName: API Key
+    required: true
+```
+
+## Control config resolution
+
+When the adapter registers at least one config key:
+
+- Set **`MCP_CONTROL_SERVER_URL`** to your control-service base URL.
+- The SDK may call **`POST /mcp/config`** with the run token from the request and your schema.
+- Set **`MCP_CONFIG_FETCH_REQUIRED=false`** for local work without Control (when you still declare schema keys).
+
+See [`docs/mcp/mcp_env.md`](../../docs/mcp/mcp_env.md) for the full variable list.
+
+## Proxy (library)
+
+```python
+from agentruntime.mcp.proxy import run_proxy
+run_proxy(
+    target_url="http://127.0.0.1:8000/mcp",
+    overlay_file="tools.yaml",
+    host="127.0.0.1",
+    port=8010,
+)
+```
+
+## TypeScript sibling SDK
+
+For Node deployments, use the monorepo package [`packages/agentruntime-mcp-ts`](../agentruntime-mcp-ts/README.md) (`@agentruntime-labs/agentruntime-mcp`): official **`@modelcontextprotocol/server`**, Zod 4, **`runWithRouter`**.
+
+## Examples in this repo
+
+- [`connectors/py-connectors/resend-connector`](../../connectors/py-connectors/resend-connector/) — Python Resend connector (illustrative layout)
+
+## Releasing
+
+See [`../RELEASE.md`](../RELEASE.md) (Python section): lightweight Git tags (`v0.1.0`, `v0.1.1`), bump `version` in `pyproject.toml`, do not commit `__pycache__` / `*.egg-info/`.

agentruntime_mcp-0.2.0/README.md

@@ -0,0 +1,109 @@
+# AgentRuntime MCP SDK (Python)
+
+Opinionated SDK for MCP connectors using **FastMCP** with the same **Control** integration as [`agentruntime-mcp-go`](https://github.com/agentruntime-io/agentruntime-mcp-go): optional `POST /mcp/config`, env merge, and request metadata (run token, instance id).
+
+There is **no mandatory legacy standalone token/HMAC middleware chain** in front of every request. Probe-style auth is the **Bearer run token** (or `X-MCP-Token`) and headers AgentRuntime sends; optional `auth.mode` in `config.yaml` is reserved for future templates and does not switch Control gating off.
+
+## Install
+
+```bash
+pip install agentruntime-mcp
+```
+
+## Runtimes
+
+| Entry | When to use | HTTP |
+|--------|-------------|------|
+| **`run(config_path)`** | Decorator-only `tool()` modules; tools registered from `config.yaml` / `build_schemas` | `/mcp` |
+| **`run_with_registry(config_path, *names)`** | Plugins registered with **`register_adapter`**; one process, one MCP server | `/mcp` |
+| **`run_with_router(config_path)`** | Same registry, **monolith routing** (Go **`RunWithRouter`** / TS **`runWithRouter`** parity) | `/{adapter}/mcp` plus optional **webhook** routes on the **same** ASGI app |
+
+Use **`register_adapter`** for anything that should share a process with other adapters. Keep plain **`run()`** for single-connector demos that only use decorators and YAML tools.
+
+**Webhooks:** Implement **`register_webhook(self, mux: ServeMux)`** on the adapter. Paths are registered on the **root** Starlette app **before** adapter mounts (same dispatch order as Go/TS). Operators expose vendor callbacks as `https://<host>:<port><path>` (same host/port as MCP).
+
+## Minimal example
+
+```python
+from pydantic import BaseModel, Field
+from agentruntime.mcp.decorators import tool
+from agentruntime.mcp.runtime import run
+from fastmcp import Context
+
+class In(BaseModel):
+    a: float = Field(...)
+    b: float = Field(...)
+
+class Out(BaseModel):
+    result: float
+    expression: str
+
+@tool(name="add", input_model=In, output_model=Out)
+def add(a: float, b: float, ctx: Context) -> Out:
+    region = ctx.config.region  # resolved config when schema + Control are used
+    return Out(result=a + b, expression=f"{a} + {b}")
+
+if __name__ == "__main__":
+    run("config.yaml")
+```
+
+## Config (`config.yaml`)
+
+- **`server`:** `name`, `host`, `port`, `stateless_http`
+- **`tracing`:** enable OpenTelemetry when dependencies are present
+- **`config`:** declarative schema for Control / `GET /mcp/config/schema`
+
+Env overrides: **`HOST`**, **`PORT`** (see [`docs/mcp/mcp_env.md`](../../docs/mcp/mcp_env.md)).
+
+Example:
+
+```yaml
+server:
+  name: "MyConnector"
+  host: "127.0.0.1"
+  port: 8012
+  stateless_http: true
+
+tracing:
+  enabled: false
+
+config:
+  apiKey:
+    type: string
+    displayName: API Key
+    required: true
+```
+
+## Control config resolution
+
+When the adapter registers at least one config key:
+
+- Set **`MCP_CONTROL_SERVER_URL`** to your control-service base URL.
+- The SDK may call **`POST /mcp/config`** with the run token from the request and your schema.
+- Set **`MCP_CONFIG_FETCH_REQUIRED=false`** for local work without Control (when you still declare schema keys).
+
+See [`docs/mcp/mcp_env.md`](../../docs/mcp/mcp_env.md) for the full variable list.
+
+## Proxy (library)
+
+```python
+from agentruntime.mcp.proxy import run_proxy
+run_proxy(
+    target_url="http://127.0.0.1:8000/mcp",
+    overlay_file="tools.yaml",
+    host="127.0.0.1",
+    port=8010,
+)
+```
+
+## TypeScript sibling SDK
+
+For Node deployments, use the monorepo package [`packages/agentruntime-mcp-ts`](../agentruntime-mcp-ts/README.md) (`@agentruntime-labs/agentruntime-mcp`): official **`@modelcontextprotocol/server`**, Zod 4, **`runWithRouter`**.
+
+## Examples in this repo
+
+- [`connectors/py-connectors/resend-connector`](../../connectors/py-connectors/resend-connector/) — Python Resend connector (illustrative layout)
+
+## Releasing
+
+See [`../RELEASE.md`](../RELEASE.md) (Python section): lightweight Git tags (`v0.1.0`, `v0.1.1`), bump `version` in `pyproject.toml`, do not commit `__pycache__` / `*.egg-info/`.

{agentruntime_mcp-0.0.1 → agentruntime_mcp-0.2.0}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentruntime-mcp"
-version = "0.0.1"
-description = "AgentRuntime MCP SDK (decorators, runtime, middleware, schemas, proxy, generators)"
+version = "0.2.0"
+description = "AgentRuntime MCP SDK (decorators, runtime, middleware, schemas, proxy)"
 requires-python = ">=3.10"
 readme = "README.md"
 authors = [{ name = "AgentRuntime" }]
 dependencies = [
-  "fastmcp",
+  "fastmcp>=2.10.0",
   "pydantic>=2",
   "starlette>=0.37",
   "uvicorn[standard]>=0.30",
@@ -21,7 +21,15 @@ dependencies = [
   "httpx>=0.25",
 ]
 
+[project.optional-dependencies]
+test = ["pytest>=7.0"]
+
 [tool.setuptools]
 package-dir = {"" = "src"}
 
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
 

{agentruntime_mcp-0.0.1 → agentruntime_mcp-0.2.0}/setup.cfg

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

{agentruntime_mcp-0.0.1 → agentruntime_mcp-0.2.0}/src/agentruntime/__init__.py

@@ -1,2 +1,2 @@
-# Namespace package for AgentRuntime
-
+# Namespace package for AgentRuntime
+

agentruntime_mcp-0.2.0/src/agentruntime/mcp/__init__.py

@@ -0,0 +1,30 @@
+from .decorators import tool, mount_tools  # noqa: F401
+from .runtime import run, make_server, load_config, run_with_registry, run_with_router  # noqa: F401
+from .schemas import emit_json_shape, emit_flat_shape, build_schemas  # noqa: F401
+from .context import get_config, ConfigView  # noqa: F401
+from .adapter_registry import register_adapter, list_adapter_names, instantiate_adapters  # noqa: F401
+from .adapter_registry import Adapter, WebhookAdapter, ServeMux  # noqa: F401
+from .config_schema import (  # noqa: F401
+    CONFIG_TYPE_STRING,
+    CONFIG_TYPE_NUMBER,
+    CONFIG_TYPE_BOOL,
+    field,
+    string_field,
+    opt_required,
+    opt_default,
+    new_schema_writer,
+    write_schema,
+    config_schema_has_keys,
+)
+from .errors import ErrAdapterNotFound, ControlError, human_message_from_control_api_body  # noqa: F401
+from .bridge import BRIDGE_MOUNT_PATH  # noqa: F401
+from .bridge_auth import apply_auth_mapping, apply_header_mappings, apply_bridge_headers  # noqa: F401
+from .control import (  # noqa: F401
+    HEADER_MCP_INSTANCE_ID,
+    HEADER_MCP_SERVER_ID,
+    ControlPayload,
+    fetch_control_payload,
+    build_runtime_context_from_request,
+)
+from .webhook import sign_mode_b, deliver_mode_b, ModeBRequest  # noqa: F401
+

agentruntime_mcp-0.2.0/src/agentruntime/mcp/adapter_registry.py

@@ -0,0 +1,87 @@
+"""Adapter registry mirroring agentruntime-mcp-go adapter.go."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Dict,
+    Iterable,
+    List,
+    Protocol,
+    Tuple,
+    runtime_checkable,
+)
+
+from .errors import ErrAdapterNotFound
+
+if TYPE_CHECKING:
+    from fastmcp import FastMCP
+
+    from .config_schema import SchemaWriter
+
+
+@runtime_checkable
+class Adapter(Protocol):
+    def register(self, mcp: "FastMCP", schema: "SchemaWriter") -> None: ...
+
+
+@runtime_checkable
+class WebhookAdapter(Protocol):
+    def register_webhook(self, mux: "ServeMux") -> None: ...
+
+
+@dataclass(frozen=True)
+class AdapterConstructorInput:
+    """Reserved for future use (parity with Go AdapterConstructorInput)."""
+
+
+AdapterConstructor = Callable[[AdapterConstructorInput], Adapter]
+
+
+class ServeMux:
+    """HTTP route table (exact path → handler). Order preserved (first match wins when iterating).
+
+    Handlers should be Starlette-style ``async def(request: Request) -> Response``.
+    """
+
+    def __init__(self) -> None:
+        self._routes: List[Tuple[str, Any]] = []
+
+    def handle(self, path: str, handler: Any) -> None:
+        self._routes.append((normalize_path(path), handler))
+
+    def __iter__(self) -> Iterable[Tuple[str, Any]]:
+        return iter(self._routes)
+
+
+def normalize_path(path: str) -> str:
+    if not path or path == "/":
+        return "/"
+    return path[:-1] if path.endswith("/") else path
+
+
+_registry: Dict[str, AdapterConstructor] = {}
+
+
+def register_adapter(name: str, ctor: AdapterConstructor) -> None:
+    _registry[name] = ctor
+
+
+def list_adapter_names() -> List[str]:
+    return sorted(_registry.keys())
+
+
+def instantiate_adapters(names: List[str]) -> List[Adapter]:
+    inp = AdapterConstructorInput()
+    if not names:
+        return [ctor(inp) for ctor in _registry.values()]
+    out: List[Adapter] = []
+    for n in names:
+        ctor = _registry.get(n)
+        if ctor is None:
+            raise ErrAdapterNotFound(n)
+        out.append(ctor(inp))
+    return out

agentruntime_mcp-0.2.0/src/agentruntime/mcp/auth_http.py

@@ -0,0 +1,43 @@
+"""HTTP helpers mirroring agentruntime-mcp-go auth.go."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional
+import urllib.parse
+
+NO_CONFIG_METHODS = frozenset({"tools/list", "initialize", "notifications/initialized"})
+
+
+def extract_token_from_headers(headers: Mapping[str, Any]) -> str:
+    auth = headers.get("authorization") or headers.get("Authorization")
+    if isinstance(auth, str) and auth.lower().startswith("bearer "):
+        return auth[7:].strip()
+    xt = headers.get("x-mcp-token") or headers.get("X-MCP-Token")
+    if isinstance(xt, str) and xt.strip():
+        return xt.strip()
+    return ""
+
+
+def normalize_url_path(url_path: str) -> str:
+    p = urllib.parse.urlsplit(url_path).path or ""
+    if len(p) > 1 and p.endswith("/"):
+        p = p[:-1]
+    return p or "/"
+
+
+def is_schema_endpoint_for_mount(method: str, url_path: str, mount_path: str) -> bool:
+    if method.upper() != "GET":
+        return False
+    path = normalize_url_path(url_path)
+    mp = mount_path.rstrip("/") or "/"
+    schema_path = normalize_url_path(mp + "/config/schema")
+    return path == schema_path
+
+
+def needs_resolved_config_from_body(data: Optional[Mapping[str, Any]]) -> bool:
+    if not data or not isinstance(data, Mapping):
+        return True
+    m = data.get("method")
+    if not isinstance(m, str):
+        return True
+    return m not in NO_CONFIG_METHODS

agentruntime_mcp-0.2.0/src/agentruntime/mcp/bridge.py

@@ -0,0 +1,164 @@
+"""Generic MCP bridge route — mirror agentruntime-mcp-go bridge.go."""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any, Dict, Mapping, Optional
+
+import httpx
+from starlette.requests import Request
+from starlette.responses import JSONResponse, PlainTextResponse, Response
+
+from .auth_http import extract_token_from_headers, is_schema_endpoint_for_mount
+from .bridge_auth import apply_bridge_headers
+from .control import build_runtime_context_from_request, fetch_control_payload
+from .errors import ControlError, human_message_from_control_api_body
+
+BRIDGE_MOUNT_PATH = "/bridge/mcp"
+_LOG = logging.getLogger(__name__)
+
+
+def _bridge_control_err(err: BaseException) -> str:
+    if isinstance(err, ControlError):
+        hm = human_message_from_control_api_body(err.body)
+        if hm:
+            return hm
+    return str(err)
+
+
+def _bridge_upstream_from_payload(bridge: Optional[Mapping[str, Any]]) -> str:
+    if not bridge:
+        raise ValueError(
+            "server is not configured for bridge mode (missing metadata.bridge upstream_url)"
+        )
+    upstream = str(bridge.get("upstream_url", "")).strip()
+    if not upstream:
+        raise ValueError("bridge upstream_url is not set on mcp_servers.metadata")
+    return upstream
+
+
+def _tool_name_from_params(data: Mapping[str, Any]) -> Optional[str]:
+    params = data.get("params")
+    if not isinstance(params, dict):
+        return None
+    name = str(params.get("name", "")).strip()
+    return name or None
+
+
+def _json_rpc_response(
+    req_id: Any,
+    result: Optional[Dict[str, Any]] = None,
+    rpc_err: Optional[Dict[str, Any]] = None,
+) -> JSONResponse:
+    body: Dict[str, Any] = {"jsonrpc": "2.0", "id": req_id}
+    if rpc_err is not None:
+        body["error"] = rpc_err
+    else:
+        body["result"] = result or {}
+    return JSONResponse(body)
+
+
+def _json_rpc_err(code: int, message: str) -> Dict[str, Any]:
+    return {"code": code, "message": message}
+
+
+async def _bridge_post(
+    target_url: str,
+    payload: Mapping[str, Any],
+    extra_headers: Mapping[str, str],
+) -> Dict[str, Any]:
+    if not target_url.strip():
+        raise ValueError("proxy target not configured")
+    headers = {
+        "Accept": "application/json, text/event-stream",
+        "Content-Type": "application/json",
+        **dict(extra_headers),
+    }
+    async with httpx.AsyncClient() as client:
+        resp = await client.post(target_url, json=dict(payload), headers=headers)
+    if resp.status_code != 200:
+        raise ValueError(f"proxy target not configured: target returned {resp.status_code}: {resp.text}")
+    try:
+        parsed = resp.json()
+    except Exception as exc:
+        raise ValueError(f"proxy target not configured: {exc}") from exc
+    if not isinstance(parsed, dict):
+        raise ValueError("proxy target not configured: invalid JSON object")
+    return parsed
+
+
+async def bridge_http_endpoint(request: Request) -> Response:
+    mount = BRIDGE_MOUNT_PATH
+    path = request.url.path
+
+    if is_schema_endpoint_for_mount(request.method, path, mount):
+        token = extract_token_from_headers(request.headers)
+        ctx = build_runtime_context_from_request(request)
+        try:
+            payload = fetch_control_payload(token, {}, ctx)
+            return JSONResponse(payload.config_schema or {})
+        except Exception as err:
+            return PlainTextResponse(_bridge_control_err(err), status_code=502)
+
+    if request.method.upper() != "POST":
+        return PlainTextResponse("Method Not Allowed", status_code=405)
+
+    try:
+        data = await request.json()
+    except Exception:
+        return _json_rpc_response(None, rpc_err=_json_rpc_err(-32700, "Parse error"))
+    if not isinstance(data, dict):
+        return _json_rpc_response(None, rpc_err=_json_rpc_err(-32700, "Parse error"))
+
+    req_id = data.get("id")
+    method = data.get("method") if isinstance(data.get("method"), str) else ""
+
+    ctx = build_runtime_context_from_request(request)
+    if method == "tools/call":
+        tn = _tool_name_from_params(data)
+        if tn:
+            ctx["tool_name"] = tn
+
+    token = extract_token_from_headers(request.headers)
+    try:
+        control_payload = fetch_control_payload(token, {}, ctx)
+    except Exception as err:
+        return _json_rpc_response(req_id, rpc_err=_json_rpc_err(-32603, _bridge_control_err(err)))
+
+    try:
+        upstream = _bridge_upstream_from_payload(control_payload.bridge)
+    except Exception as err:
+        return _json_rpc_response(req_id, rpc_err=_json_rpc_err(-32603, str(err)))
+
+    try:
+        auth_hdr = apply_bridge_headers(control_payload.config, control_payload.bridge)
+    except Exception as err:
+        return _json_rpc_response(req_id, rpc_err=_json_rpc_err(-32603, f"upstream auth: {err}"))
+
+    try:
+        proxied = await _bridge_post(upstream, data, auth_hdr)
+    except Exception as err:
+        return _json_rpc_response(req_id, rpc_err=_json_rpc_err(-32603, str(err)))
+
+    if method in ("tools/list", "tools/call"):
+        result = proxied.get("result")
+        if not isinstance(result, dict):
+            result = {}
+        return _json_rpc_response(req_id, result=result)
+    return JSONResponse(proxied)
+
+
+def bridge_routes() -> list[Any]:
+    """Starlette routes for the generic bridge mount."""
+    from starlette.routing import Route
+
+    return [
+        Route(BRIDGE_MOUNT_PATH, endpoint=bridge_http_endpoint, methods=["GET", "POST"]),
+        Route(f"{BRIDGE_MOUNT_PATH}/", endpoint=bridge_http_endpoint, methods=["GET", "POST"]),
+        Route(
+            f"{BRIDGE_MOUNT_PATH}/config/schema",
+            endpoint=bridge_http_endpoint,
+            methods=["GET"],
+        ),
+    ]