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

agentruntime_mcp-0.1.2/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: agentruntime-mcp
+Version: 0.1.2
+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.1.2/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.1.2}/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.1.2"
+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.1.2}/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.1.2}/src/agentruntime/__init__.py

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

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

@@ -0,0 +1,21 @@
+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 .webhook import sign_mode_b, deliver_mode_b, ModeBRequest  # noqa: F401
+

agentruntime_mcp-0.1.2/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.1.2/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.1.2/src/agentruntime/mcp/config_schema.py

@@ -0,0 +1,86 @@
+"""Config schema helpers mirroring agentruntime-mcp-go config_schema.go."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, List, Mapping, Optional
+
+CONFIG_TYPE_STRING = "string"
+CONFIG_TYPE_NUMBER = "number"
+CONFIG_TYPE_BOOL = "boolean"
+
+
+@dataclass
+class ConfigField:
+    type: str
+    display_name: str
+    required: bool = False
+    default: Any = None
+
+
+@dataclass
+class ConfigFieldDef:
+    key: str
+    field: ConfigField
+
+
+ConfigFieldOpt = Callable[[ConfigField], None]
+
+
+def opt_required() -> ConfigFieldOpt:
+    def _apply(f: ConfigField) -> None:
+        f.required = True
+
+    return _apply
+
+
+def opt_default(v: Any) -> ConfigFieldOpt:
+    def _apply(f: ConfigField) -> None:
+        f.default = v
+
+    return _apply
+
+
+def field(key: str, typ: str, display_name: str, *opts: ConfigFieldOpt) -> ConfigFieldDef:
+    cf = ConfigField(type=typ, display_name=display_name)
+    for o in opts:
+        o(cf)
+    return ConfigFieldDef(key=key, field=cf)
+
+
+def string_field(key: str, display_name: str, *opts: ConfigFieldOpt) -> ConfigFieldDef:
+    return field(key, CONFIG_TYPE_STRING, display_name, *opts)
+
+
+class SchemaWriter:
+    """Writes merged Control config_schema entries into a dict."""
+
+    def __init__(self, into: Dict[str, Any]) -> None:
+        self._into = into
+
+    def add(self, key: str, f: ConfigField) -> None:
+        m: Dict[str, Any] = {
+            "type": f.type,
+            "displayName": f.display_name,
+            "required": f.required,
+        }
+        if f.default is not None:
+            m["default"] = f.default
+        self._into[key] = m
+
+
+def new_schema_writer(into: Optional[Dict[str, Any]] = None) -> SchemaWriter:
+    target = into if into is not None else {}
+    return SchemaWriter(target)
+
+
+def write_schema(sw: Optional[SchemaWriter], prefix: str, defs: List[ConfigFieldDef]) -> None:
+    if sw is None:
+        return
+    for d in defs:
+        sw.add(prefix + d.key, d.field)
+
+
+def config_schema_has_keys(schema: Mapping[str, Any]) -> bool:
+    return len(schema) > 0
+

agentruntime_mcp-0.1.2/src/agentruntime/mcp/context.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from contextvars import ContextVar, Token
+from typing import Any, Dict, Iterable, Mapping, Optional
+
+
+_current_token: ContextVar[Optional[str]] = ContextVar("agentruntime_mcp_auth_token", default=None)
+_current_config: ContextVar["ConfigView"] = ContextVar("agentruntime_mcp_resolved_config", default=None)  # type: ignore[assignment]
+
+
+class ConfigView(dict):
+    """Dictionary with attribute access for config values."""
+
+    def __init__(self, data: Optional[Mapping[str, Any]] = None) -> None:
+        super().__init__()
+        if data:
+            for k, v in data.items():
+                self[k] = _to_config_value(v)
+
+    def __getattr__(self, item: str) -> Any:
+        try:
+            return self[item]
+        except KeyError as exc:
+            raise AttributeError(item) from exc
+
+    def __setattr__(self, key: str, value: Any) -> None:
+        self[key] = _to_config_value(value)
+
+    def copy(self) -> "ConfigView":
+        return ConfigView(self)
+
+
+def _to_config_value(value: Any) -> Any:
+    if isinstance(value, ConfigView):
+        return value
+    if isinstance(value, Mapping):
+        return ConfigView(value)
+    if isinstance(value, list):
+        return [_to_config_value(v) for v in value]
+    return value
+
+
+def set_request_context(token: Optional[str], config: Optional[Mapping[str, Any]]) -> tuple[Token, Token]:
+    cfg = ConfigView(config or {})
+    t1 = _current_token.set(token)
+    t2 = _current_config.set(cfg)
+    return t1, t2
+
+
+def reset_request_context(tokens: Iterable[Token]) -> None:
+    t = list(tokens)
+    if len(t) >= 1:
+        _current_token.reset(t[0])
+    if len(t) >= 2:
+        _current_config.reset(t[1])
+
+
+def get_auth_token() -> Optional[str]:
+    return _current_token.get()
+
+
+def get_config() -> ConfigView:
+    cfg = _current_config.get()
+    if cfg is None:
+        return ConfigView({})
+    return cfg
+
+
+def attach_config_to_ctx(ctx: Any, config: Optional[Mapping[str, Any]] = None) -> None:
+    if ctx is None:
+        return
+    cfg = ConfigView(config or get_config())
+    try:
+        setattr(ctx, "config", cfg)
+    except Exception:
+        pass