diff --git a/.sampo/changesets/mcp-directory-listing.md b/.sampo/changesets/mcp-directory-listing.md new file mode 100644 index 000000000..4faf7a796 --- /dev/null +++ b/.sampo/changesets/mcp-directory-listing.md @@ -0,0 +1,11 @@ +--- +pypi/posthog: minor +--- + +MCP analytics tool definitions change in three ways: + +- `get_more_tools` and `send_feedback` declare `readOnlyHint`, `destructiveHint`, `idempotentHint`, and `openWorldHint` as `false`, because a call records data in your PostHog project. Their annotations no longer carry a `title`. +- The injected `context` argument has a shorter description. +- The injected `llm_model` argument is always optional. + +These changes alter your published tool definitions. If your server is listed in the ChatGPT or Claude directories, those platforms may re-review the updated tools. diff --git a/posthog/mcp/README.md b/posthog/mcp/README.md index bd179597d..58f177233 100644 --- a/posthog/mcp/README.md +++ b/posthog/mcp/README.md @@ -145,9 +145,9 @@ contains the sanitized tool arguments and their original names. Custom dispatchers can call `get_tool_input_properties()` and add its result to the `properties` argument of `capture_tool_call()`. -Model capture adds an `llm_model` argument to compatible tool schemas, required on the official -high-level adapters and optional elsewhere. Dispatch never enforces it, so servers keep working; -strict-schema clients see the new field. Set `capture_model=False` to leave schemas untouched. +Model capture adds an optional `llm_model` argument to compatible tool schemas. Dispatch never +enforces it, so servers keep working; strict-schema clients see the new field. Set +`capture_model=False` to leave schemas untouched. Conversation correlation adds an optional `conversation_id` argument and returns a handle in eligible tool results. Clients must echo it to group later calls; calls without it mint new handles. Set `enable_conversation_id=False` to retain transport-based session grouping and unchanged @@ -161,11 +161,9 @@ The SDK records the best model identifier visible to the server as `$mcp_llm_model`. Recognized client metadata wins and sets `$mcp_llm_model_source` to `client_metadata`. The SDK also adds an `llm_model` string to each compatible tool schema as a fallback, recorded with source -`self_reported`. It is required for custom dispatchers and the official high-level -MCP SDK adapters. Raw low-level servers and standalone `fastmcp.FastMCP` advertise -it as optional; the standalone adapter strips it before input validation, so -requiring it would reject calls. Existing schema strictness is preserved when -analytics fields are added. +`self_reported`. It is always optional: an agent that does not know its model would +otherwise guess one. Existing schema strictness is preserved when analytics fields +are added. The recognized metadata path is Codex's `x-codex-turn-metadata.model` field in request `_meta`. Other clients, including Claude Code, use the self-report path diff --git a/posthog/mcp/_instrumentation.py b/posthog/mcp/_instrumentation.py index cd87dd4a2..ae8d7b30b 100644 --- a/posthog/mcp/_instrumentation.py +++ b/posthog/mcp/_instrumentation.py @@ -1180,9 +1180,7 @@ def mutate_tool_schema( required=context_required, ) if inject_model: - schema = _mutate_model_schema( - data, tool.name, schema, required=context_required - ) + schema = _mutate_model_schema(data, tool.name, schema) else: # Discard any earlier registered-tool verdict: middleware may now # advertise or dispatch an application-owned field with the same name. @@ -1202,9 +1200,7 @@ def mutate_tool_schema( ) -def _mutate_model_schema( - data: MCPAnalyticsData, name: str, schema: Any, *, required: bool -) -> Any: +def _mutate_model_schema(data: MCPAnalyticsData, name: str, schema: Any) -> Any: if not is_capture_model_enabled(data.options.capture_model): return schema model_was_injected = data.tool_model_parameter_injected.get(name, False) @@ -1214,7 +1210,6 @@ def _mutate_model_schema( schema, name, get_model_description(data.options.capture_model), - required=required, ) data.tool_model_parameter_injected[name] = not app_owns_model and schema_has_param( schema, "llm_model" diff --git a/posthog/mcp/_model_parameters.py b/posthog/mcp/_model_parameters.py index 05ee0f29f..be26fd14c 100644 --- a/posthog/mcp/_model_parameters.py +++ b/posthog/mcp/_model_parameters.py @@ -33,9 +33,10 @@ def add_model_parameter_to_schema( input_schema: Optional[Dict[str, Any]], tool_name: str = "unknown", description_override: Optional[str] = None, - required: bool = True, ) -> Optional[Dict[str, Any]]: - """Return a copied schema with an SDK-owned ``llm_model`` field. + """Return a copied schema with an optional, SDK-owned ``llm_model`` field. + Never required: an agent that does not know its model would guess one, and + a model the client sends in request ``_meta`` wins anyway. Existing application fields and complex schemas fail closed: the SDK must never overwrite or later strip a value that belongs to the tool itself. @@ -58,13 +59,6 @@ def add_model_parameter_to_schema( "type": "string", "description": description_override or DEFAULT_MODEL_PARAMETER_DESCRIPTION, } - if required: - required_list = schema.get("required") - if isinstance(required_list, list): - if "llm_model" not in required_list: - required_list.append("llm_model") - else: - schema["required"] = ["llm_model"] return schema diff --git a/posthog/mcp/constants.py b/posthog/mcp/constants.py index 47a2b2c62..5fc725b35 100644 --- a/posthog/mcp/constants.py +++ b/posthog/mcp/constants.py @@ -18,13 +18,9 @@ INACTIVITY_TIMEOUT_IN_MINUTES = 30 DEFAULT_CONTEXT_PARAMETER_DESCRIPTION = ( - "Explain in 15-25 words, in third person, why this tool is called and how it supports " - "the user's goal. For analytics only. You MUST describe only the abstract purpose of the " - "tool call. NEVER include, repeat, paraphrase, or infer personal, sensitive, or identifying " - "information from the user request or tool results, including names, emails, phone numbers, " - 'IPs, IDs, or credentials. You MUST generalize specific entities into roles such as "a user", ' - '"the customer", or "an account". Example: "Retrieving a customer\'s recent orders to ' - 'investigate a billing issue and help support determine the appropriate resolution."' + "A few words on why you are calling this tool, for the server developer's " + 'analytics. Describe people and things by role, such as "a customer". Do not ' + "quote the user or include names, emails, or other personal details." ) DEFAULT_CONVERSATION_ID_DESCRIPTION = ( diff --git a/posthog/mcp/feedback.py b/posthog/mcp/feedback.py index fd937070b..5d1bc1d08 100644 --- a/posthog/mcp/feedback.py +++ b/posthog/mcp/feedback.py @@ -13,6 +13,7 @@ from ._sanitization import sanitize_free_text, sanitize_free_text_value from .constants import PostHogMCPAnalyticsProperty from .logger import log +from .tools import VIRTUAL_TOOL_HINTS from .types import CollectFeedbackOptions, FeedbackReport, JsonRecord __all__ = ["SEND_FEEDBACK_TOOL_NAME", "send_feedback_result"] @@ -168,17 +169,7 @@ def get_feedback_tool_descriptor( "properties": properties, "required": ["feedback_type", "summary", *extra_required], }, - "annotations": { - "title": "Send feedback", - "readOnlyHint": True, - # Interacts with an external entity: the report lands in analytics. - "openWorldHint": True, - # Only records the feedback, so repeat calls are harmless — and - # advertising it as idempotent makes agents more willing to call it - # proactively. - "idempotentHint": True, - "destructiveHint": False, - }, + "annotations": dict(VIRTUAL_TOOL_HINTS), } diff --git a/posthog/mcp/tools.py b/posthog/mcp/tools.py index 97d4bb6eb..36222bf96 100644 --- a/posthog/mcp/tools.py +++ b/posthog/mcp/tools.py @@ -16,6 +16,16 @@ GET_MORE_TOOLS_NAME = "get_more_tools" +# A call records one event in the server owner's PostHog project: a write +# outside the conversation that deletes nothing, repeats on every call, and +# reaches only that project. Fixed so host configuration cannot misdeclare it. +VIRTUAL_TOOL_HINTS = { + "readOnlyHint": False, + "destructiveHint": False, + "idempotentHint": False, + "openWorldHint": False, +} + _GET_MORE_TOOLS_RESULT_TEXT = ( "Unfortunately, we have shown you the full tool list. We have noted your feedback " "and will work to improve the tool list in the future." @@ -52,13 +62,7 @@ def build_report_missing_descriptor(name: str = GET_MORE_TOOLS_NAME) -> Dict[str }, "required": ["context"], }, - "annotations": { - "title": "Get More Tools", - "readOnlyHint": True, - "openWorldHint": True, - "idempotentHint": True, - "destructiveHint": False, - }, + "annotations": dict(VIRTUAL_TOOL_HINTS), } diff --git a/posthog/test/mcp/test_fastmcp.py b/posthog/test/mcp/test_fastmcp.py index 53cdfea34..5be832d69 100644 --- a/posthog/test/mcp/test_fastmcp.py +++ b/posthog/test/mcp/test_fastmcp.py @@ -82,7 +82,7 @@ async def test_list_tools_injects_model_into_real_and_virtual_tools(): for name in ("add", "boom", "get_more_tools"): assert "llm_model" in tools[name].inputSchema["properties"] - assert "llm_model" in tools[name].inputSchema["required"] + assert "llm_model" not in tools[name].inputSchema.get("required", []) async def test_virtual_tool_uses_conversation_id(): diff --git a/posthog/test/mcp/test_feedback.py b/posthog/test/mcp/test_feedback.py index 315623546..b45721c38 100644 --- a/posthog/test/mcp/test_feedback.py +++ b/posthog/test/mcp/test_feedback.py @@ -100,13 +100,6 @@ def test_descriptor_defaults(): "sentiment", "task_completed", } - assert descriptor["annotations"] == { - "title": "Send feedback", - "readOnlyHint": True, - "openWorldHint": True, - "idempotentHint": True, - "destructiveHint": False, - } def test_descriptor_merges_extras_and_custom_name(): diff --git a/posthog/test/mcp/test_model_parameters.py b/posthog/test/mcp/test_model_parameters.py index 0891f0e95..1c2620f8c 100644 --- a/posthog/test/mcp/test_model_parameters.py +++ b/posthog/test/mcp/test_model_parameters.py @@ -31,7 +31,7 @@ def test_add_model_parameter_to_schema(schema): "type": "string", "description": DEFAULT_MODEL_PARAMETER_DESCRIPTION, } - assert "llm_model" in result["required"] + assert "llm_model" not in result.get("required", []) assert result.get("additionalProperties") == (schema or {}).get( "additionalProperties" ) diff --git a/posthog/test/mcp/test_posthog_mcp.py b/posthog/test/mcp/test_posthog_mcp.py index 1251db910..51bbb679b 100644 --- a/posthog/test/mcp/test_posthog_mcp.py +++ b/posthog/test/mcp/test_posthog_mcp.py @@ -286,6 +286,26 @@ def test_prepare_tool_list_injects_context_into_tool_objects(sdk_tool: bool) -> assert "context" not in schema["properties"] +# The spec's text, pinned on purpose: every SDK sends this exact string, and +# importing the constant would make this test agree with any change to it. +_CROSS_SDK_CONTEXT_DESCRIPTION = ( + "A few words on why you are calling this tool, for the server developer's " + 'analytics. Describe people and things by role, such as "a customer". Do not ' + "quote the user or include names, emails, or other personal details." +) + + +def test_prepare_tool_list_advertises_the_cross_sdk_context_description(): + client, _ = make_client() + tools = [{"name": "search", "inputSchema": {"type": "object", "properties": {}}}] + + prepared = client.prepare_tool_list(tools) + + assert prepared[0]["inputSchema"]["properties"]["context"]["description"] == ( + _CROSS_SDK_CONTEXT_DESCRIPTION + ) + + def test_prepare_tool_list_can_be_disabled(): client, _ = make_client() tools = [{"name": "search", "inputSchema": {"type": "object", "properties": {}}}] @@ -309,7 +329,7 @@ async def test_prepare_and_capture_model(options: dict[str, bool]) -> None: prepared_tools = client.prepare_tool_list(tools) schema = prepared_tools[0]["inputSchema"] assert ("llm_model" in schema["properties"]) == enabled - assert ("llm_model" in schema.get("required", [])) == enabled + assert "llm_model" not in schema.get("required", []) call = client.prepare_tool_call( "search", diff --git a/posthog/test/mcp/test_v2_wire_dual_era.py b/posthog/test/mcp/test_v2_wire_dual_era.py index 58fbf4e9a..df5f23235 100644 --- a/posthog/test/mcp/test_v2_wire_dual_era.py +++ b/posthog/test/mcp/test_v2_wire_dual_era.py @@ -146,7 +146,7 @@ async def test_modern_tools_list_advertises_injected_params(): assert "context" in tools["add"]["inputSchema"]["properties"] assert "conversation_id" in tools["add"]["inputSchema"]["properties"] assert "llm_model" in tools["add"]["inputSchema"]["properties"] - assert "llm_model" in tools["add"]["inputSchema"]["required"] + assert "llm_model" not in tools["add"]["inputSchema"]["required"] listed = _events(client, "$mcp_tools_list") assert listed and set(listed[0]["properties"]["$mcp_listed_tool_names"]) == { diff --git a/posthog/test/mcp/test_virtual_tools.py b/posthog/test/mcp/test_virtual_tools.py index c02ecc7bf..4e45ed31f 100644 --- a/posthog/test/mcp/test_virtual_tools.py +++ b/posthog/test/mcp/test_virtual_tools.py @@ -89,6 +89,54 @@ async def test_both_virtual_tools_are_appended_to_the_first_page_only(): assert _names(await _list_page(server, cursor="1")) == ["echo"] +# --- annotations --------------------------------------------------------------- + +# The spec's annotations JSON, pinned on purpose: importing VIRTUAL_TOOL_HINTS +# would make this test agree with any change to it. +_RECORDS_DATA = { + "readOnlyHint": False, + "destructiveHint": False, + "idempotentHint": False, + "openWorldHint": False, +} + + +@pytest.mark.parametrize( + "options, advertised_name", + [ + (MCPAnalyticsOptions(report_missing=True), "get_more_tools"), + (MCPAnalyticsOptions(collect_feedback=True), "send_feedback"), + ( + MCPAnalyticsOptions( + report_missing=True, missing_capability_tool_name="request_tool" + ), + "request_tool", + ), + ( + MCPAnalyticsOptions( + collect_feedback=CollectFeedbackOptions( + tool_name="rate_server", description="Tell us how it went." + ) + ), + "rate_server", + ), + ], +) +async def test_virtual_tools_declare_that_they_record_data(options, advertised_name): + server = FastMCP("annotations") + + @server.tool() + def add(a: int, b: int) -> int: + return a + b + + instrument(server, FakeClient(), options) + handler = server._mcp_server.request_handlers[mcp_types.ListToolsRequest] + result = await handler(mcp_types.ListToolsRequest(method="tools/list")) + tool = {t.name: t for t in result.root.tools}[advertised_name] + + assert tool.annotations.model_dump(exclude_none=True) == (_RECORDS_DATA) + + # --- name collisions -----------------------------------------------------------