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

{agentruntime_mcp-0.1.2 → agentruntime_mcp-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentruntime-mcp
-Version: 0.1.2
+Version: 0.3.1
 Summary: AgentRuntime MCP SDK (decorators, runtime, middleware, schemas, proxy)
 Author: AgentRuntime
 Requires-Python: >=3.10
@@ -115,6 +115,19 @@ run_proxy(
 )
 ```
 
+## Tool organization (`toolorg`)
+
+Large connectors can build publish metadata for Control catalog grouping. Parity with Go `toolorg` — see [MCP_SDK_PARITY.md](../../docs/mcp/MCP_SDK_PARITY.md).
+
+```python
+from agentruntime.mcp.toolorg import publisher_metadata, Metadata
+
+meta = publisher_metadata("clickup_get_task", Metadata())
+# → display_name, suggested_group, suggested_tags for mcp_tools.metadata
+```
+
+Per-request caller bearer (for downstream HTTP): `request_bearer_from_context()`.
+
 ## 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`**.

{agentruntime_mcp-0.1.2 → agentruntime_mcp-0.3.1}/README.md

@@ -96,6 +96,19 @@ run_proxy(
 )
 ```
 
+## Tool organization (`toolorg`)
+
+Large connectors can build publish metadata for Control catalog grouping. Parity with Go `toolorg` — see [MCP_SDK_PARITY.md](../../docs/mcp/MCP_SDK_PARITY.md).
+
+```python
+from agentruntime.mcp.toolorg import publisher_metadata, Metadata
+
+meta = publisher_metadata("clickup_get_task", Metadata())
+# → display_name, suggested_group, suggested_tags for mcp_tools.metadata
+```
+
+Per-request caller bearer (for downstream HTTP): `request_bearer_from_context()`.
+
 ## 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`**.

{agentruntime_mcp-0.1.2 → agentruntime_mcp-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentruntime-mcp"
-version = "0.1.2"
+version = "0.3.1"
 description = "AgentRuntime MCP SDK (decorators, runtime, middleware, schemas, proxy)"
 requires-python = ">=3.10"
 readme = "README.md"

{agentruntime_mcp-0.1.2 → agentruntime_mcp-0.3.1}/src/agentruntime/mcp/__init__.py

@@ -17,5 +17,27 @@ from .config_schema import (  # noqa: F401
     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
-
+from .request_bearer import request_bearer_from_context  # noqa: F401
+from .toolorg import (  # noqa: F401
+    Metadata,
+    EffectiveOrganization,
+    ToolGroup,
+    suggest_from_wire_name,
+    format_display_name,
+    publisher_metadata,
+    default_publisher_metadata,
+    group_label,
+    parse_metadata,
+    metadata_is_empty,
+    merge_effective,
+)

agentruntime_mcp-0.3.1/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"],
+        ),
+    ]

agentruntime_mcp-0.3.1/src/agentruntime/mcp/bridge_auth.py

@@ -0,0 +1,109 @@
+"""Bridge outbound auth/header mapping — mirror agentruntime-mcp-go bridge_auth.go."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Mapping, MutableMapping, Optional
+
+
+def _string_from_map(m: Optional[Mapping[str, Any]], key: str) -> str:
+    if not m:
+        return ""
+    v = m.get(key)
+    if v is None:
+        return ""
+    return v if isinstance(v, str) else str(v)
+
+
+def _config_string(cfg: Optional[Mapping[str, Any]], key: str) -> str:
+    if not cfg or not key:
+        return ""
+    v = cfg.get(key)
+    if v is None:
+        return ""
+    return v.strip() if isinstance(v, str) else str(v).strip()
+
+
+def apply_auth_mapping(
+    cfg: Mapping[str, Any],
+    mapping: Optional[Mapping[str, Any]],
+) -> Dict[str, str]:
+    """auth_mapping: { type: none | bearer | header, from?, name? }."""
+    h: Dict[str, str] = {}
+    if not mapping:
+        return h
+
+    typ = _string_from_map(mapping, "type").lower().strip()
+    if not typ or typ == "none":
+        return h
+
+    from_key = _string_from_map(mapping, "from").strip()
+    if not from_key:
+        from_key = _string_from_map(mapping, "value_from").strip()
+    val = _config_string(cfg, from_key)
+    if not val and typ != "none":
+        raise ValueError(f'auth mapping requires config key "{from_key}"')
+
+    if typ == "bearer":
+        h["Authorization"] = f"Bearer {val}"
+    elif typ == "header":
+        name = _string_from_map(mapping, "name").strip()
+        if not name:
+            raise ValueError("auth mapping type header requires name")
+        h[name] = val
+    else:
+        raise ValueError(f'unsupported auth_mapping type "{typ}"')
+    return h
+
+
+def apply_header_mappings(
+    cfg: Mapping[str, Any],
+    mappings: List[Optional[Mapping[str, Any]]],
+) -> Dict[str, str]:
+    """Each mapping: { name, from } or { name, value_from }."""
+    h: Dict[str, str] = {}
+    for m in mappings:
+        if not m:
+            continue
+        name = _string_from_map(m, "name").strip()
+        from_key = _string_from_map(m, "from").strip()
+        if not from_key:
+            from_key = _string_from_map(m, "value_from").strip()
+        if not name:
+            raise ValueError("header mapping requires name")
+        if not from_key:
+            raise ValueError(f'header mapping for "{name}" requires from')
+        val = _config_string(cfg, from_key)
+        if not val:
+            raise ValueError(f'header mapping requires config key "{from_key}"')
+        h[name] = val
+    return h
+
+
+def _coerce_header_mappings(raw: Any) -> List[Dict[str, Any]]:
+    if not isinstance(raw, list):
+        return []
+    out: List[Dict[str, Any]] = []
+    for item in raw:
+        if isinstance(item, dict):
+            out.append(item)
+    return out
+
+
+def apply_bridge_headers(
+    cfg: Mapping[str, Any],
+    bridge: Optional[Mapping[str, Any]],
+) -> Dict[str, str]:
+    """Merge auth_mapping then header_mappings from bridge metadata."""
+    h: Dict[str, str] = {}
+    if not bridge:
+        return h
+
+    auth_map = bridge.get("auth_mapping")
+    if isinstance(auth_map, dict):
+        h.update(apply_auth_mapping(cfg, auth_map))
+
+    header_mappings = _coerce_header_mappings(bridge.get("header_mappings"))
+    if not header_mappings:
+        return h
+    h.update(apply_header_mappings(cfg, header_mappings))
+    return h

agentruntime_mcp-0.3.1/src/agentruntime/mcp/control.py

@@ -0,0 +1,124 @@
+"""Control POST /mcp/config client — mirror agentruntime-mcp-go control.go."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from typing import Any, Dict, Mapping, Optional
+from urllib import error as urlerror
+from urllib import request as urlrequest
+
+from .errors import ControlError
+
+HEADER_MCP_INSTANCE_ID = "X-MCP-Instance-Id"
+HEADER_MCP_SERVER_ID = "X-MCP-Server-Id"
+
+
+@dataclass
+class ControlPayload:
+    config: Dict[str, Any] = field(default_factory=dict)
+    config_schema: Dict[str, Any] = field(default_factory=dict)
+    bridge: Optional[Dict[str, Any]] = None
+
+
+def fetch_control_payload(
+    token: str,
+    config_schema: Mapping[str, Any],
+    runtime_context: Mapping[str, Any],
+) -> ControlPayload:
+    base = os.environ.get("MCP_CONTROL_SERVER_URL", "").strip().rstrip("/")
+    if not base:
+        return ControlPayload()
+
+    timeout = 5.0
+    ts = os.environ.get("MCP_CONTROL_TIMEOUT_SEC", "").strip()
+    if ts:
+        try:
+            n = int(ts)
+            if n > 0:
+                timeout = float(n)
+        except ValueError:
+            pass
+
+    payload = {
+        "configSchema": dict(config_schema),
+        "config_schema": dict(config_schema),
+        "schema": dict(config_schema),
+        "runtimeContext": dict(runtime_context),
+        "runtime_context": dict(runtime_context),
+    }
+    data = json.dumps(payload).encode("utf-8")
+    req = urlrequest.Request(
+        f"{base}/mcp/config",
+        data=data,
+        method="POST",
+        headers={
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {token}",
+        },
+    )
+    try:
+        with urlrequest.urlopen(req, timeout=timeout) as resp:
+            raw = resp.read().decode("utf-8")
+    except urlerror.HTTPError as exc:
+        body = ""
+        try:
+            body = exc.read().decode("utf-8")
+        except Exception:
+            body = ""
+        raise ControlError(exc.code, body) from exc
+    except Exception as exc:
+        raise ControlError(502, str(exc)) from exc
+
+    if not raw:
+        return ControlPayload()
+    try:
+        parsed = json.loads(raw)
+    except Exception as exc:
+        raise ControlError(502, f"invalid response: {exc}") from exc
+    if not isinstance(parsed, dict):
+        raise ControlError(502, "invalid control config response")
+
+    out = ControlPayload()
+    cfg = parsed.get("config")
+    if isinstance(cfg, dict):
+        out.config = cfg
+    cs = parsed.get("config_schema")
+    if isinstance(cs, dict):
+        out.config_schema = cs
+    bridge = parsed.get("bridge")
+    if isinstance(bridge, dict):
+        out.bridge = bridge
+    return out
+
+
+def build_runtime_context_from_request(req: Any) -> Dict[str, Any]:
+    """Build runtime_context for bridge/control calls from a Starlette request."""
+    ctx: Dict[str, Any] = {}
+    if req is None:
+        ctx["tool_name"] = "__initialize"
+        return ctx
+
+    headers = getattr(req, "headers", None)
+
+    def _hdr(name: str) -> str:
+        if headers is None:
+            return ""
+        v = headers.get(name)
+        return v.strip() if isinstance(v, str) else ""
+
+    inst = _hdr(HEADER_MCP_INSTANCE_ID) or _hdr("x-mcp-instance-id")
+    if inst:
+        ctx["instance_id"] = inst
+
+    sid = _hdr(HEADER_MCP_SERVER_ID) or _hdr("x-mcp-server-id")
+    env_sid = os.environ.get("MCP_SERVER_ID", "").strip()
+    if env_sid:
+        sid = env_sid
+    if sid:
+        ctx["server_id"] = sid
+
+    tn = _hdr("X-Tool-Name") or _hdr("x-tool-name") or _hdr("X-MCP-Tool-Name") or _hdr("x-mcp-tool-name")
+    ctx["tool_name"] = tn or "__initialize"
+    return ctx

agentruntime_mcp-0.3.1/src/agentruntime/mcp/request_bearer.py

@@ -0,0 +1,12 @@
+"""Per-request bearer token context (parity with agentruntime-mcp-go request_bearer)."""
+
+from __future__ import annotations
+
+from .context import get_auth_token
+
+__all__ = ["request_bearer_from_context"]
+
+
+def request_bearer_from_context() -> str | None:
+    """Return the incoming MCP caller bearer token for the active request, if set."""
+    return get_auth_token()

{agentruntime_mcp-0.1.2 → agentruntime_mcp-0.3.1}/src/agentruntime/mcp/runtime.py

@@ -150,8 +150,10 @@ def run_with_router(config_path: str = "config.yaml") -> None:
             if callable(reg):
                 reg(mux)
 
+    from .bridge import bridge_routes
+
     sub_apps: List[Any] = []
-    routes: List[Any] = []
+    routes: List[Any] = list(bridge_routes())
     for path, handler in mux:
         routes.append(Route(path, endpoint=handler, methods=list(_WEBHOOK_METHODS)))
     for n in names:

agentruntime_mcp-0.3.1/src/agentruntime/mcp/toolorg/__init__.py

@@ -0,0 +1,29 @@
+"""Tool organization helpers for MCP publish metadata (parity with agentruntime-mcp-go/toolorg)."""
+
+from .toolorg import (
+    Metadata,
+    EffectiveOrganization,
+    ToolGroup,
+    suggest_from_wire_name,
+    format_display_name,
+    publisher_metadata,
+    default_publisher_metadata,
+    group_label,
+    parse_metadata,
+    metadata_is_empty,
+    merge_effective,
+)
+
+__all__ = [
+    "Metadata",
+    "EffectiveOrganization",
+    "ToolGroup",
+    "suggest_from_wire_name",
+    "format_display_name",
+    "publisher_metadata",
+    "default_publisher_metadata",
+    "group_label",
+    "parse_metadata",
+    "metadata_is_empty",
+    "merge_effective",
+]

agentruntime_mcp-0.3.1/src/agentruntime/mcp/toolorg/toolorg.py

@@ -0,0 +1,225 @@
+"""Publish-time tool organization — mirror agentruntime-mcp-go/toolorg."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any, Mapping, Optional, Sequence
+
+_DEFAULT_GROUP_LABELS: dict[str, str] = {
+    "hierarchy": "Hierarchy",
+    "tasks": "Tasks",
+    "search_members": "Search & members",
+    "comments": "Comments",
+    "time": "Time tracking",
+    "docs": "Docs",
+    "chat": "Chat",
+    "uncategorized": "Other",
+}
+
+
+@dataclass
+class Metadata:
+    display_name: str = ""
+    suggested_group: str = ""
+    suggested_tags: list[str] = field(default_factory=list)
+    suggested_rank_key: str = ""
+
+
+@dataclass
+class EffectiveOrganization:
+    group_id: str = ""
+    group_label: str = ""
+    rank_key: str = ""
+    tags: list[str] = field(default_factory=list)
+
+
+@dataclass
+class ToolGroup:
+    id: str = ""
+    label: str = ""
+    rank_key: str = ""
+    source: str = ""
+
+
+def _normalize_tags(tags: Sequence[str]) -> list[str]:
+    seen: set[str] = set()
+    out: list[str] = []
+    for t in tags:
+        t = str(t).strip().lower()
+        if not t or t in seen:
+            continue
+        seen.add(t)
+        out.append(t)
+    out.sort()
+    return out
+
+
+def _infer_group_id(body: str) -> str:
+    if "chat" in body:
+        return "chat"
+    if "doc" in body:
+        return "docs"
+    if "comment" in body:
+        return "comments"
+    if "time" in body:
+        return "time"
+    if body == "search" or "member" in body or "assignee" in body or "filtered_team" in body:
+        return "search_members"
+    if (
+        "workspace" in body
+        or "space" in body
+        or "folder" in body
+        or "hierarchy" in body
+        or body == "get_list"
+        or body.startswith("get_lists")
+        or body.startswith("create_list")
+        or body.startswith("update_list")
+        or body.startswith("create_folder")
+        or body.startswith("update_folder")
+    ):
+        return "hierarchy"
+    return "tasks"
+
+
+def _is_read_only_verb(body: str) -> bool:
+    for prefix in ("get_", "list_", "find_", "resolve_", "search"):
+        if body.startswith(prefix) or body == prefix.rstrip("_"):
+            return True
+    return False
+
+
+def _infer_tags(body: str, group_id: str) -> list[str]:
+    tags = [group_id]
+    tags.append("read_only" if _is_read_only_verb(body) else "mutating")
+    tags.append("v3" if ("chat" in body or "doc" in body) else "v2")
+    return _normalize_tags(tags)
+
+
+def suggest_from_wire_name(tool_name: str) -> tuple[str, list[str]]:
+    name = tool_name.strip().lower()
+    parts = name.split("_")
+    if len(parts) < 2:
+        return "uncategorized", ["mutating"]
+    body = "_".join(parts[1:])
+    group_id = _infer_group_id(body)
+    return group_id, _infer_tags(body, group_id)
+
+
+def format_display_name(tool_name: str) -> str:
+    parts = tool_name.strip().split("_")
+    if len(parts) <= 1:
+        return tool_name
+    body = " ".join(parts[1:])
+    if not body:
+        return tool_name
+    return body[0].upper() + body[1:]
+
+
+def publisher_metadata(tool_name: str, overrides: Optional[Metadata] = None) -> dict[str, Any]:
+    ov = overrides or Metadata()
+    out: dict[str, Any] = {}
+    display = ov.display_name.strip()
+    if not display:
+        display = format_display_name(tool_name)
+    if display:
+        out["display_name"] = display
+    group = ov.suggested_group.strip().lower()
+    if not group:
+        group, _ = suggest_from_wire_name(tool_name)
+    if group:
+        out["suggested_group"] = group
+    tags = list(ov.suggested_tags)
+    if not tags:
+        _, tags = suggest_from_wire_name(tool_name)
+    if tags:
+        out["suggested_tags"] = tags
+    rk = ov.suggested_rank_key.strip()
+    if rk:
+        out["suggested_rank_key"] = rk
+    return out
+
+
+def default_publisher_metadata(tool_name: str) -> dict[str, Any]:
+    return publisher_metadata(tool_name, Metadata())
+
+
+def group_label(group_id: str) -> str:
+    gid = group_id.strip().lower()
+    if gid in _DEFAULT_GROUP_LABELS:
+        return _DEFAULT_GROUP_LABELS[gid]
+    parts = gid.split("_")
+    titled = []
+    for p in parts:
+        if not p:
+            continue
+        titled.append(p[0].upper() + p[1:])
+    return " ".join(titled)
+
+
+def _normalize_group_id(group_id: str) -> str:
+    return group_id.strip().lower().replace(" ", "_")
+
+
+def parse_metadata(raw: bytes | str) -> Metadata:
+    if not raw:
+        return Metadata()
+    if isinstance(raw, bytes):
+        text = raw.decode("utf-8", errors="replace")
+    else:
+        text = raw
+    try:
+        parsed = json.loads(text)
+    except json.JSONDecodeError:
+        return Metadata()
+    if not isinstance(parsed, dict):
+        return Metadata()
+    tags_raw = parsed.get("suggested_tags") or []
+    tags: list[str] = []
+    if isinstance(tags_raw, list):
+        tags = [str(t) for t in tags_raw]
+    return Metadata(
+        display_name=str(parsed.get("display_name") or ""),
+        suggested_group=_normalize_group_id(str(parsed.get("suggested_group") or "")),
+        suggested_tags=_normalize_tags(tags),
+        suggested_rank_key=str(parsed.get("suggested_rank_key") or ""),
+    )
+
+
+def metadata_is_empty(meta: Mapping[str, Any]) -> bool:
+    if not meta:
+        return True
+    for k, v in meta.items():
+        if v is None:
+            continue
+        if k == "suggested_tags":
+            if isinstance(v, list) and len(v) > 0:
+                return False
+            continue
+        if isinstance(v, str) and v.strip():
+            return False
+    return True
+
+
+def merge_effective(
+    published: Metadata,
+    overlay_group_id: Optional[str] = None,
+    overlay_rank_key: Optional[str] = None,
+) -> EffectiveOrganization:
+    group_id = published.suggested_group.strip()
+    tags = list(published.suggested_tags)
+    if overlay_group_id is not None:
+        g = _normalize_group_id(overlay_group_id)
+        if g:
+            group_id = g
+    rank_key = published.suggested_rank_key.strip()
+    if overlay_rank_key is not None:
+        rk = overlay_rank_key.strip()
+        if rk:
+            rank_key = rk
+    return EffectiveOrganization(
+        group_id=group_id,
+        group_label=group_label(group_id),
+        rank_key=rank_key,
+        tags=tags,
+    )

{agentruntime_mcp-0.1.2 → agentruntime_mcp-0.3.1}/src/agentruntime_mcp.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentruntime-mcp
-Version: 0.1.2
+Version: 0.3.1
 Summary: AgentRuntime MCP SDK (decorators, runtime, middleware, schemas, proxy)
 Author: AgentRuntime
 Requires-Python: >=3.10
@@ -115,6 +115,19 @@ run_proxy(
 )
 ```
 
+## Tool organization (`toolorg`)
+
+Large connectors can build publish metadata for Control catalog grouping. Parity with Go `toolorg` — see [MCP_SDK_PARITY.md](../../docs/mcp/MCP_SDK_PARITY.md).
+
+```python
+from agentruntime.mcp.toolorg import publisher_metadata, Metadata
+
+meta = publisher_metadata("clickup_get_task", Metadata())
+# → display_name, suggested_group, suggested_tags for mcp_tools.metadata
+```
+
+Per-request caller bearer (for downstream HTTP): `request_bearer_from_context()`.
+
 ## 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`**.

{agentruntime_mcp-0.1.2 → agentruntime_mcp-0.3.1}/src/agentruntime_mcp.egg-info/SOURCES.txt

@@ -4,21 +4,29 @@ src/agentruntime/__init__.py
 src/agentruntime/mcp/__init__.py
 src/agentruntime/mcp/adapter_registry.py
 src/agentruntime/mcp/auth_http.py
+src/agentruntime/mcp/bridge.py
+src/agentruntime/mcp/bridge_auth.py
 src/agentruntime/mcp/config_schema.py
 src/agentruntime/mcp/context.py
+src/agentruntime/mcp/control.py
 src/agentruntime/mcp/decorators.py
 src/agentruntime/mcp/env_merge.py
 src/agentruntime/mcp/errors.py
 src/agentruntime/mcp/middleware.py
 src/agentruntime/mcp/proxy.py
+src/agentruntime/mcp/request_bearer.py
 src/agentruntime/mcp/runtime.py
 src/agentruntime/mcp/schemas.py
 src/agentruntime/mcp/webhook.py
+src/agentruntime/mcp/toolorg/__init__.py
+src/agentruntime/mcp/toolorg/toolorg.py
 src/agentruntime_mcp.egg-info/PKG-INFO
 src/agentruntime_mcp.egg-info/SOURCES.txt
 src/agentruntime_mcp.egg-info/dependency_links.txt
 src/agentruntime_mcp.egg-info/requires.txt
 src/agentruntime_mcp.egg-info/top_level.txt
+tests/test_bridge_auth.py
 tests/test_context.py
 tests/test_runtime.py
-tests/test_runtime_router.py
+tests/test_runtime_router.py
+tests/test_toolorg.py

agentruntime_mcp-0.3.1/tests/test_bridge_auth.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import pytest
+
+from agentruntime.mcp.bridge_auth import (
+    apply_auth_mapping,
+    apply_bridge_headers,
+    apply_header_mappings,
+)
+
+
+def test_apply_auth_mapping_bearer() -> None:
+    h = apply_auth_mapping({"access_token": "tok123"}, {"type": "bearer", "from": "access_token"})
+    assert h["Authorization"] == "Bearer tok123"
+
+
+def test_apply_auth_mapping_none() -> None:
+    assert apply_auth_mapping({}, {"type": "none"}) == {}
+
+
+def test_apply_header_mappings_grafana() -> None:
+    h = apply_header_mappings(
+        {
+            "grafana_url": "https://acme.grafana.net",
+            "service_account_token": "glsa_xxx",
+        },
+        [
+            {"name": "X-Grafana-URL", "from": "grafana_url"},
+            {"name": "X-Grafana-Service-Account-Token", "from": "service_account_token"},
+        ],
+    )
+    assert h["X-Grafana-URL"] == "https://acme.grafana.net"
+    assert h["X-Grafana-Service-Account-Token"] == "glsa_xxx"
+
+
+def test_apply_header_mappings_missing_key() -> None:
+    with pytest.raises(ValueError, match="grafana_url"):
+        apply_header_mappings({}, [{"name": "X-Grafana-URL", "from": "grafana_url"}])
+
+
+def test_apply_bridge_headers_combined() -> None:
+    h = apply_bridge_headers(
+        {
+            "grafana_url": "https://acme.grafana.net",
+            "service_account_token": "glsa_xxx",
+        },
+        {
+            "auth_mapping": {"type": "none"},
+            "header_mappings": [
+                {"name": "X-Grafana-URL", "from": "grafana_url"},
+                {"name": "X-Grafana-Service-Account-Token", "from": "service_account_token"},
+            ],
+        },
+    )
+    assert h["X-Grafana-URL"] == "https://acme.grafana.net"
+
+
+def test_apply_bridge_headers_legacy_auth_only() -> None:
+    h = apply_bridge_headers(
+        {"access_token": "tok"},
+        {"auth_mapping": {"type": "bearer", "from": "access_token"}},
+    )
+    assert h["Authorization"] == "Bearer tok"

agentruntime_mcp-0.3.1/tests/test_toolorg.py

@@ -0,0 +1,54 @@
+"""Tests for toolorg parity with agentruntime-mcp-go/toolorg."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from agentruntime.mcp.toolorg import (
+    Metadata,
+    default_publisher_metadata,
+    merge_effective,
+    suggest_from_wire_name,
+)
+
+
+def _load_cases() -> list[dict]:
+    path = (
+        Path(__file__).resolve().parent.parent
+        / "src"
+        / "agentruntime"
+        / "mcp"
+        / "toolorg"
+        / "fixtures"
+        / "suggest_cases.json"
+    )
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+@pytest.mark.parametrize("case", _load_cases(), ids=lambda c: c["tool_name"])
+def test_suggest_from_wire_name_fixtures(case: dict) -> None:
+    group, tags = suggest_from_wire_name(case["tool_name"])
+    assert group == case["group"]
+    assert tags == case["tags"]
+
+
+@pytest.mark.parametrize("case", _load_cases(), ids=lambda c: c["tool_name"])
+def test_default_publisher_metadata_fixtures(case: dict) -> None:
+    meta = default_publisher_metadata(case["tool_name"])
+    assert meta["suggested_group"] == case["group"]
+
+
+def test_merge_effective_explicit_only() -> None:
+    eff = merge_effective(Metadata(), overlay_group_id="docs", overlay_rank_key="n")
+    assert eff.group_id == "docs"
+    assert eff.rank_key == "n"
+
+    eff = merge_effective(Metadata(suggested_group="tasks"))
+    assert eff.group_id == "tasks"
+
+    eff = merge_effective(Metadata())
+    assert eff.group_id == ""
+    assert eff.tags == []