Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions .sampo/changesets/mcp-directory-listing.md
Original file line number Diff line number Diff line change
@@ -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.
14 changes: 6 additions & 8 deletions posthog/mcp/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
9 changes: 2 additions & 7 deletions posthog/mcp/_instrumentation.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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)
Expand All @@ -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"
Expand Down
12 changes: 3 additions & 9 deletions posthog/mcp/_model_parameters.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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


Expand Down
10 changes: 3 additions & 7 deletions posthog/mcp/constants.py
Original file line number Diff line number Diff line change
Expand Up @@ -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 = (
Expand Down
13 changes: 2 additions & 11 deletions posthog/mcp/feedback.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"]
Expand Down Expand Up @@ -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),
}


Expand Down
18 changes: 11 additions & 7 deletions posthog/mcp/tools.py
Original file line number Diff line number Diff line change
Expand Up @@ -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."
Expand Down Expand Up @@ -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),
}


Expand Down
2 changes: 1 addition & 1 deletion posthog/test/mcp/test_fastmcp.py
Original file line number Diff line number Diff line change
Expand Up @@ -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():
Expand Down
7 changes: 0 additions & 7 deletions posthog/test/mcp/test_feedback.py
Original file line number Diff line number Diff line change
Expand Up @@ -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():
Expand Down
2 changes: 1 addition & 1 deletion posthog/test/mcp/test_model_parameters.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"
)
Expand Down
22 changes: 21 additions & 1 deletion posthog/test/mcp/test_posthog_mcp.py
Original file line number Diff line number Diff line change
Expand Up @@ -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": {}}}]
Expand All @@ -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",
Expand Down
2 changes: 1 addition & 1 deletion posthog/test/mcp/test_v2_wire_dual_era.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"]) == {
Expand Down
48 changes: 48 additions & 0 deletions posthog/test/mcp/test_virtual_tools.py
Original file line number Diff line number Diff line change
Expand Up @@ -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 -----------------------------------------------------------


Expand Down
Loading