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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentruntime-mcp
-Version: 0.2.0
+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.2.0 → 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.2.0 → agentruntime_mcp-0.3.1}/pyproject.toml

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

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

@@ -27,4 +27,17 @@ from .control import (  # noqa: F401
     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/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.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.2.0 → 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.2.0
+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.2.0 → agentruntime_mcp-0.3.1}/src/agentruntime_mcp.egg-info/SOURCES.txt

@@ -14,9 +14,12 @@ 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
@@ -25,4 +28,5 @@ 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_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 == []