diff --git a/scripts/generate_mcp_tools.py b/scripts/generate_mcp_tools.py index 3a3703bc..8c6102bf 100644 --- a/scripts/generate_mcp_tools.py +++ b/scripts/generate_mcp_tools.py @@ -64,6 +64,10 @@ "getAnalytics": (20, 40), } +AGENT_VIEWS = { + "getAnalytics": "summary", +} + SAME_ARGUMENTS_IDEMPOTENT_OPERATIONS = { "createCallAd", "createCtwaAd", @@ -433,6 +437,24 @@ def _with_page_size(operation_id: str, params: list[dict[str, Any]]) -> list[dic ] +def _with_agent_view(operation_id: str, params: list[dict[str, Any]]) -> list[dict[str, Any]]: + view = AGENT_VIEWS.get(operation_id) + if view is None: + return params + if not any(p["name"] == "view" for p in params): + print(f"Warning: {operation_id} has no `view` parameter; its agent default is not applied.", file=sys.stderr) + return [ + { + **p, + "default": f'"{view}"', + "description": f"{p['description'].strip()} Defaults to {view} here; pass full for every field.".strip(), + } + if p["name"] == "view" + else p + for p in params + ] + + def extract_parameters( operation: dict[str, Any], spec: dict[str, Any] | None = None, @@ -740,7 +762,10 @@ def main() -> int: # Human-readable title for the annotation. First line of the # OpenAPI summary, capped so it stays a short label. "title": summary.split("\n")[0].strip()[:80], - "params": _with_page_size(operation_id, _with_bounded_limit(operation_id, extract_parameters(operation, spec))), + "params": _with_agent_view( + operation_id, + _with_page_size(operation_id, _with_bounded_limit(operation_id, extract_parameters(operation, spec))), + ), "idempotency_scope": tool_name if operation_id in SAME_ARGUMENTS_IDEMPOTENT_OPERATIONS else None, }) diff --git a/tests/test_mcp_agent_views.py b/tests/test_mcp_agent_views.py new file mode 100644 index 00000000..ef12ed1c --- /dev/null +++ b/tests/test_mcp_agent_views.py @@ -0,0 +1,44 @@ +from __future__ import annotations + +import importlib +from pathlib import Path + +import pytest + +ANALYTICS_OPERATION = { + "operationId": "getAnalytics", + "parameters": [ + { + "name": "view", + "in": "query", + "schema": {"type": "string", "enum": ["full", "summary"], "default": "full"}, + "description": "full returns everything.", + } + ], +} + + +@pytest.fixture +def mcp_generator(monkeypatch: pytest.MonkeyPatch): + monkeypatch.syspath_prepend(str(Path(__file__).resolve().parents[1] / "scripts")) + return importlib.import_module("generate_mcp_tools") + + +def test_analytics_listing_defaults_to_the_summary_view_for_agents(mcp_generator) -> None: + params = mcp_generator._with_agent_view("getAnalytics", mcp_generator.extract_parameters(ANALYTICS_OPERATION, {})) + handler = mcp_generator.generate_tool_handler( + "analytics_get_analytics", "analytics", "get_analytics", "Get analytics", params, True, "Get analytics" + ) + + assert "view: Literal['full', 'summary'] = \"summary\"" in handler + assert "view=view" in handler + assert "Defaults to summary here" in handler + + +def test_a_spec_without_the_view_parameter_warns_instead_of_silently_skipping( + mcp_generator, capsys: pytest.CaptureFixture[str] +) -> None: + params = mcp_generator._with_agent_view("getAnalytics", []) + + assert params == [] + assert "getAnalytics has no `view` parameter" in capsys.readouterr().err