mcpeye 0.1.0__tar.gz

mcpeye-0.1.0/.gitignore

@@ -0,0 +1,49 @@
+# deps
+node_modules/
+.pnpm-store/
+
+# build output
+dist/
+.next/
+out/
+build/
+*.tsbuildinfo
+
+# turbo
+.turbo/
+
+# env
+.env
+.env.local
+.env.*.local
+
+# logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+
+# os / editor
+.DS_Store
+.idea/
+.vscode/*
+!.vscode/extensions.json
+
+# generated reports (local self-host output) — anchored to the repo root so it does
+# NOT also match the app route source at apps/web/app/reports/
+/reports/
+
+# python
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+*.egg-info/
+
+# ruby
+/packages/sdk-ruby/pkg/
+/packages/sdk-ruby/*.gem
+/packages/sdk-ruby/Gemfile.lock
+.bundle/
+
+# Internal MVP feature specs (local only — implement from these; not for the public repo)
+specs/

mcpeye-0.1.0/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: mcpeye
+Version: 0.1.0
+Summary: mcpeye Python SDK — open-source product analytics for MCP servers. See why your agent is failing.
+Project-URL: Homepage, https://github.com/mcpeye/mcpeye
+Project-URL: Repository, https://github.com/mcpeye/mcpeye
+Author: mcpeye
+License: MIT
+Keywords: agent-analytics,ai-agents,llm,mcp,mcp-analytics,mcp-server,mcpeye,model-context-protocol,observability,product-analytics,self-hosted,session-replay
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# mcpeye (Python SDK)
+
+Open-source product analytics for MCP servers. **See why your agent is failing.**
+
+`mcpeye` instruments your MCP server so you can answer the question the
+hero **Intent Gap Report** is built around: *what did users ask the tools to do
+that the tools could not deliver?*
+
+It works by injecting an optional `mcpeyeIntent` parameter into every tool's
+input schema. The agent self-reports, in its own words, why it is calling a tool
+and any blocker the user hit — so intent is captured at near-zero cost, with **no
+per-call LLM**. The clustering LLM runs later, server-side, only to build reports.
+
+This is the Python SDK. The [TypeScript SDK](../sdk-typescript) is the reference
+implementation; behaviour and the wire contract are identical across SDKs.
+
+## Install
+
+```bash
+pip install mcpeye
+```
+
+Requires Python 3.9+. Depends on `httpx` and `pydantic`. The `mcp` package is
+**not** a hard dependency — it is your server's framework, imported lazily by
+`track()`. If you use the automatic `track()` path, install it alongside (or use
+the extra, which pins `mcp>=1.0.0`, itself Python 3.10+):
+
+```bash
+pip install "mcpeye[mcp]"
+```
+
+## Quick start
+
+Call `track(...)` once, **after** you have registered your `list_tools` and
+`call_tool` handlers:
+
+```python
+from mcp.server.lowlevel import Server
+import mcpeye
+
+server = Server("my-server", version="1.2.3")
+
+@server.list_tools()
+async def list_tools():
+    return [ ... ]
+
+@server.call_tool()
+async def call_tool(name, arguments):
+    ...
+
+# Instrument it. mcpeyeIntent is injected into every tool schema, calls are
+# captured, redacted, buffered, and shipped to the ingest API.
+mcpeye.track(
+    server,
+    project_id="proj_123",
+    ingest_url="http://localhost:3001",   # or set MCPEYE_INGEST_URL
+    ingest_secret="...",                  # or set MCPEYE_INGEST_SECRET
+)
+```
+
+`track` returns the same `server` instance, instrumented in place.
+
+### What `track` does
+
+1. **Injects `mcpeyeIntent`** into each tool's `inputSchema` (and teaches the
+   server's tool cache about it, so the built-in input validation accepts the
+   parameter). The agent fills it in; your tool handler never sees it — it is
+   stripped from the arguments before your code runs.
+2. **Captures every tool call**: tool name, redacted arguments, redacted result,
+   error state + message, duration, and the reported intent. Each captured field
+   is size-bounded (oversized or unserializable values become a small marker) so a
+   multi-MB tool result can never blow the ingest body limit or grow the buffer.
+3. **Adds a reserved `mcpeye_request_capability` tool** (active missing-capability
+   capture). When the agent wants a capability none of your tools cover, it can
+   call this tool to say so in the user's words. mcpeye answers it locally with a
+   canned acknowledgement — it is **never** forwarded to your server — and records
+   it as a normal tool call with `tool_name = "mcpeye_request_capability"`, which
+   the report folds into "Top missing capabilities" as a high-confidence,
+   explicitly-requested entry. This catches the *silent miss*, where the right move
+   is to call no tool at all. Disable with `capture_missing_capabilities=False`.
+4. **Ships** batches as the shared `IngestPayload` JSON to `<ingest_url>/ingest`
+   with the `x-mcpeye-secret` header, using `httpx`. Shipping happens on a
+   background daemon thread — **never on the tool-call thread** — so a slow or
+   unreachable ingest endpoint adds no latency to your tools. It flushes on a timer
+   (default every 5s), eagerly when the batch fills (`flush_at`), and a final time
+   at process exit. Shipping is best-effort: ingest failures are swallowed (routed
+   to `on_error`) and retried; analytics can never take down your MCP server.
+
+> **Strict ingest URL.** Unlike the TypeScript SDK (which defaults to
+> `http://localhost:3001`), the Python SDK raises `ValueError` at setup time if no
+> ingest URL is configured — there is no implicit localhost default, so a
+> misconfigured server fails loudly at your call site instead of silently dropping
+> telemetry into a dead port.
+
+## Configuration
+
+| Argument           | Env fallback            | Default                         |
+| ------------------ | ----------------------- | ------------------------------- |
+| `ingest_url`       | `MCPEYE_INGEST_URL`     | — (required, raises if unset)   |
+| `ingest_secret`    | `MCPEYE_INGEST_SECRET`  | none                            |
+| `redact`           | —                       | `True`                          |
+| `user_id`          | —                       | none                            |
+| `client`           | —                       | none                            |
+| `server_version`   | —                       | `server.version` when available |
+| `flush_at`         | —                       | `20` buffered events            |
+| `flush_interval_s` | —                       | `5.0` seconds (background timer) |
+| `denylist_fields`  | —                       | none (adds to the built-in denylist) |
+| `capture_missing_capabilities` | —           | `True` (inject `mcpeye_request_capability`) |
+| `on_error`         | —                       | debug log on the `mcpeye` logger |
+
+> **Manifest cost.** With `capture_missing_capabilities=True`, your server's
+> `tools/list` gains one extra tool — a few hundred tokens in any model context
+> that lists tools, and one more entry in any tool picker / doc generator. That is
+> the price of seeing silent misses; pass `False` to keep it out of the manifest.
+
+### Diagnostics
+
+Every swallowed error (transport failure, capture failure) is routed to `on_error`,
+which defaults to a `debug`-level log on `logging.getLogger("mcpeye")`. Pass your
+own sink to see why telemetry might be silent — it is wrapped so it can never throw
+back into your server:
+
+```python
+mcpeye.track(server, "proj_123", ingest_url="http://localhost:3001",
+             on_error=lambda err: print("mcpeye:", err))
+```
+
+## Redaction
+
+When `redact=True` (the default), arguments, results, and the reported intent are
+scrubbed **client-side before anything leaves your process**. The v1 redaction is
+a conservative regex pass — it over-redacts rather than leak — covering:
+
+- emails
+- API keys: `sk-…`, `sk-ant-…`, `ghp_…`/`gho_…`/etc., `AKIA…`
+- `Bearer …` tokens and JWTs
+- credit-card-shaped digit runs
+- loose international phone numbers
+- a field-name denylist (`password`, `secret`, `token`, `apiKey`, `authorization`, …)
+
+Self-hosting is the real privacy mitigation; redaction reduces the blast radius
+of obvious secrets in free-text. You can use the primitives directly:
+
+```python
+from mcpeye import redact_string, redact_value
+
+redact_string("ping me at a@b.com")            # -> "ping me at [REDACTED_EMAIL]"
+redact_value({"password": "hunter2"})           # -> {"password": "[REDACTED_FIELD]"}
+```
+
+## Manual instrumentation (`wrap_tool`)
+
+The `mcp` package's `Server` internals vary across versions. `track` attaches to
+`server.request_handlers`; if that layout ever changes, `track` raises a clear
+error and you can fall back to instrumenting individual tool handlers:
+
+```python
+import mcpeye
+
+@mcpeye.wrap_tool(project_id="proj_123", tool_name="search",
+                  ingest_url="http://localhost:3001")
+async def search(arguments):
+    ...
+```
+
+`wrap_tool` pulls `mcpeyeIntent` out of the arguments, times the call, captures
+the outcome, and ships it — the same capture path as `track`, scoped to one tool.
+It accepts `redact`, `ingest_url`, `ingest_secret`, `denylist_fields`, `flush_at`,
+`flush_interval_s`, and `on_error` (not `user_id`/`client`/`server_version`, which
+are server-level identity). Note: it does not inject the parameter into a published
+schema, so add `mcpeyeIntent` to that tool's `inputSchema` yourself (see
+`mcpeye.intent_param_json_schema`) if you want agents to populate it.
+
+## Development
+
+Unit tests stub the `mcp` package, so they run with only `httpx`, `pydantic`, and
+`pytest` installed (no `mcp`):
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install httpx pydantic pytest
+.venv/bin/pip install -e packages/sdk-python --no-deps
+.venv/bin/python -m pytest packages/sdk-python/tests -q
+```
+
+## License
+
+MIT

mcpeye-0.1.0/README.md

@@ -0,0 +1,187 @@
+# mcpeye (Python SDK)
+
+Open-source product analytics for MCP servers. **See why your agent is failing.**
+
+`mcpeye` instruments your MCP server so you can answer the question the
+hero **Intent Gap Report** is built around: *what did users ask the tools to do
+that the tools could not deliver?*
+
+It works by injecting an optional `mcpeyeIntent` parameter into every tool's
+input schema. The agent self-reports, in its own words, why it is calling a tool
+and any blocker the user hit — so intent is captured at near-zero cost, with **no
+per-call LLM**. The clustering LLM runs later, server-side, only to build reports.
+
+This is the Python SDK. The [TypeScript SDK](../sdk-typescript) is the reference
+implementation; behaviour and the wire contract are identical across SDKs.
+
+## Install
+
+```bash
+pip install mcpeye
+```
+
+Requires Python 3.9+. Depends on `httpx` and `pydantic`. The `mcp` package is
+**not** a hard dependency — it is your server's framework, imported lazily by
+`track()`. If you use the automatic `track()` path, install it alongside (or use
+the extra, which pins `mcp>=1.0.0`, itself Python 3.10+):
+
+```bash
+pip install "mcpeye[mcp]"
+```
+
+## Quick start
+
+Call `track(...)` once, **after** you have registered your `list_tools` and
+`call_tool` handlers:
+
+```python
+from mcp.server.lowlevel import Server
+import mcpeye
+
+server = Server("my-server", version="1.2.3")
+
+@server.list_tools()
+async def list_tools():
+    return [ ... ]
+
+@server.call_tool()
+async def call_tool(name, arguments):
+    ...
+
+# Instrument it. mcpeyeIntent is injected into every tool schema, calls are
+# captured, redacted, buffered, and shipped to the ingest API.
+mcpeye.track(
+    server,
+    project_id="proj_123",
+    ingest_url="http://localhost:3001",   # or set MCPEYE_INGEST_URL
+    ingest_secret="...",                  # or set MCPEYE_INGEST_SECRET
+)
+```
+
+`track` returns the same `server` instance, instrumented in place.
+
+### What `track` does
+
+1. **Injects `mcpeyeIntent`** into each tool's `inputSchema` (and teaches the
+   server's tool cache about it, so the built-in input validation accepts the
+   parameter). The agent fills it in; your tool handler never sees it — it is
+   stripped from the arguments before your code runs.
+2. **Captures every tool call**: tool name, redacted arguments, redacted result,
+   error state + message, duration, and the reported intent. Each captured field
+   is size-bounded (oversized or unserializable values become a small marker) so a
+   multi-MB tool result can never blow the ingest body limit or grow the buffer.
+3. **Adds a reserved `mcpeye_request_capability` tool** (active missing-capability
+   capture). When the agent wants a capability none of your tools cover, it can
+   call this tool to say so in the user's words. mcpeye answers it locally with a
+   canned acknowledgement — it is **never** forwarded to your server — and records
+   it as a normal tool call with `tool_name = "mcpeye_request_capability"`, which
+   the report folds into "Top missing capabilities" as a high-confidence,
+   explicitly-requested entry. This catches the *silent miss*, where the right move
+   is to call no tool at all. Disable with `capture_missing_capabilities=False`.
+4. **Ships** batches as the shared `IngestPayload` JSON to `<ingest_url>/ingest`
+   with the `x-mcpeye-secret` header, using `httpx`. Shipping happens on a
+   background daemon thread — **never on the tool-call thread** — so a slow or
+   unreachable ingest endpoint adds no latency to your tools. It flushes on a timer
+   (default every 5s), eagerly when the batch fills (`flush_at`), and a final time
+   at process exit. Shipping is best-effort: ingest failures are swallowed (routed
+   to `on_error`) and retried; analytics can never take down your MCP server.
+
+> **Strict ingest URL.** Unlike the TypeScript SDK (which defaults to
+> `http://localhost:3001`), the Python SDK raises `ValueError` at setup time if no
+> ingest URL is configured — there is no implicit localhost default, so a
+> misconfigured server fails loudly at your call site instead of silently dropping
+> telemetry into a dead port.
+
+## Configuration
+
+| Argument           | Env fallback            | Default                         |
+| ------------------ | ----------------------- | ------------------------------- |
+| `ingest_url`       | `MCPEYE_INGEST_URL`     | — (required, raises if unset)   |
+| `ingest_secret`    | `MCPEYE_INGEST_SECRET`  | none                            |
+| `redact`           | —                       | `True`                          |
+| `user_id`          | —                       | none                            |
+| `client`           | —                       | none                            |
+| `server_version`   | —                       | `server.version` when available |
+| `flush_at`         | —                       | `20` buffered events            |
+| `flush_interval_s` | —                       | `5.0` seconds (background timer) |
+| `denylist_fields`  | —                       | none (adds to the built-in denylist) |
+| `capture_missing_capabilities` | —           | `True` (inject `mcpeye_request_capability`) |
+| `on_error`         | —                       | debug log on the `mcpeye` logger |
+
+> **Manifest cost.** With `capture_missing_capabilities=True`, your server's
+> `tools/list` gains one extra tool — a few hundred tokens in any model context
+> that lists tools, and one more entry in any tool picker / doc generator. That is
+> the price of seeing silent misses; pass `False` to keep it out of the manifest.
+
+### Diagnostics
+
+Every swallowed error (transport failure, capture failure) is routed to `on_error`,
+which defaults to a `debug`-level log on `logging.getLogger("mcpeye")`. Pass your
+own sink to see why telemetry might be silent — it is wrapped so it can never throw
+back into your server:
+
+```python
+mcpeye.track(server, "proj_123", ingest_url="http://localhost:3001",
+             on_error=lambda err: print("mcpeye:", err))
+```
+
+## Redaction
+
+When `redact=True` (the default), arguments, results, and the reported intent are
+scrubbed **client-side before anything leaves your process**. The v1 redaction is
+a conservative regex pass — it over-redacts rather than leak — covering:
+
+- emails
+- API keys: `sk-…`, `sk-ant-…`, `ghp_…`/`gho_…`/etc., `AKIA…`
+- `Bearer …` tokens and JWTs
+- credit-card-shaped digit runs
+- loose international phone numbers
+- a field-name denylist (`password`, `secret`, `token`, `apiKey`, `authorization`, …)
+
+Self-hosting is the real privacy mitigation; redaction reduces the blast radius
+of obvious secrets in free-text. You can use the primitives directly:
+
+```python
+from mcpeye import redact_string, redact_value
+
+redact_string("ping me at a@b.com")            # -> "ping me at [REDACTED_EMAIL]"
+redact_value({"password": "hunter2"})           # -> {"password": "[REDACTED_FIELD]"}
+```
+
+## Manual instrumentation (`wrap_tool`)
+
+The `mcp` package's `Server` internals vary across versions. `track` attaches to
+`server.request_handlers`; if that layout ever changes, `track` raises a clear
+error and you can fall back to instrumenting individual tool handlers:
+
+```python
+import mcpeye
+
+@mcpeye.wrap_tool(project_id="proj_123", tool_name="search",
+                  ingest_url="http://localhost:3001")
+async def search(arguments):
+    ...
+```
+
+`wrap_tool` pulls `mcpeyeIntent` out of the arguments, times the call, captures
+the outcome, and ships it — the same capture path as `track`, scoped to one tool.
+It accepts `redact`, `ingest_url`, `ingest_secret`, `denylist_fields`, `flush_at`,
+`flush_interval_s`, and `on_error` (not `user_id`/`client`/`server_version`, which
+are server-level identity). Note: it does not inject the parameter into a published
+schema, so add `mcpeyeIntent` to that tool's `inputSchema` yourself (see
+`mcpeye.intent_param_json_schema`) if you want agents to populate it.
+
+## Development
+
+Unit tests stub the `mcp` package, so they run with only `httpx`, `pydantic`, and
+`pytest` installed (no `mcp`):
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install httpx pydantic pytest
+.venv/bin/pip install -e packages/sdk-python --no-deps
+.venv/bin/python -m pytest packages/sdk-python/tests -q
+```
+
+## License
+
+MIT

mcpeye-0.1.0/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@mcpeye/sdk-python",
+  "version": "0.0.0",
+  "private": true,
+  "description": "mcpeye Python SDK (distribution name: mcpeye). turbo wrapper — the real build is via pyproject.toml.",
+  "scripts": {
+    "build": "true",
+    "typecheck": "true",
+    "clean": "true"
+  }
+}

mcpeye-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mcpeye"
+version = "0.1.0"
+description = "mcpeye Python SDK — open-source product analytics for MCP servers. See why your agent is failing."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "mcpeye" }]
+keywords = ["mcp", "model-context-protocol", "mcp-server", "mcp-analytics", "product-analytics", "agent-analytics", "ai-agents", "observability", "session-replay", "self-hosted", "llm", "mcpeye"]
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+]
+# `mcp` is the USER's server framework, not something mcpeye needs at runtime: it
+# is imported lazily inside track(), and the SDK's own code is 3.9-clean. Keeping
+# it OUT of the hard deps means `pip install mcpeye` works on 3.9+ and the unit
+# tests run with no `mcp` installed (they stub the Server shape). Servers that use
+# the auto-`track` path install `mcpeye[mcp]` (mcp itself requires Python >=3.10).
+dependencies = [
+  "httpx>=0.27",
+  "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+mcp = ["mcp>=1.0.0"]
+
+[project.urls]
+Homepage = "https://github.com/mcpeye/mcpeye"
+Repository = "https://github.com/mcpeye/mcpeye"
+
+[tool.hatch.build.targets.wheel]
+# `py.typed` ships automatically because it lives inside the packaged dir.
+packages = ["src/mcpeye"]

mcpeye-0.1.0/src/mcpeye/__init__.py

@@ -0,0 +1,50 @@
+"""mcpeye -- open-source intent-gap analytics for MCP servers.
+
+See why your agent is failing.
+
+Public API::
+
+    import mcpeye
+
+    mcpeye.track(server, "proj_123", ingest_url="http://localhost:3001")
+
+Falls back to :func:`mcpeye.wrap_tool` for per-tool instrumentation when the
+automatic ``track`` hook cannot attach to your ``Server``.
+"""
+
+from __future__ import annotations
+
+from .intent import (
+    INTENT_PARAM_DESCRIPTION,
+    INTENT_PARAM_NAME,
+    inject_intent_param,
+    intent_param_json_schema,
+)
+from .redaction import redact_string, redact_value
+from .request_capability import (
+    REQUEST_CAPABILITY_ACK,
+    REQUEST_CAPABILITY_TOOL_DESCRIPTION,
+    REQUEST_CAPABILITY_TOOL_NAME,
+    request_capability_descriptor,
+    request_capability_input_schema,
+)
+from .tracker import track, wrap_tool
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "track",
+    "wrap_tool",
+    "redact_string",
+    "redact_value",
+    "INTENT_PARAM_NAME",
+    "INTENT_PARAM_DESCRIPTION",
+    "intent_param_json_schema",
+    "inject_intent_param",
+    "REQUEST_CAPABILITY_TOOL_NAME",
+    "REQUEST_CAPABILITY_TOOL_DESCRIPTION",
+    "REQUEST_CAPABILITY_ACK",
+    "request_capability_input_schema",
+    "request_capability_descriptor",
+    "__version__",
+]

mcpeye-0.1.0/src/mcpeye/intent.py

@@ -0,0 +1,83 @@
+"""The injected-intent contract.
+
+mcpeye's cheap capture trick: the SDK injects an optional ``mcpeyeIntent``
+parameter into every tool's input schema. The agent self-reports, in its own
+words, why it is calling the tool and any blocker the user hit -- so we capture
+intent at near-zero cost, with NO per-call LLM. The LLM runs later, in the
+worker, only to cluster sessions into reports.
+
+The description below is what the agent reads. It is deliberately specific about
+surfacing failures/blockers AND naming any capability the user wanted that no tool
+provides -- those attempted-but-failed asks, phrased as the user's own unmet need,
+are the hero signal (the Intent Gap Report) and the highest-value, most roadmap-
+actionable thing this whole product captures.
+
+This is the Python port of ``@mcpeye/core``'s ``intent.ts``; the strings MUST
+match byte-for-byte across every SDK. ``tests/test_intent.py`` asserts this.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+INTENT_PARAM_NAME = "mcpeyeIntent"
+
+# Byte-for-byte identical to packages/core/src/intent.ts INTENT_PARAM_DESCRIPTION.
+# If you change one, change all SDKs (TS, Python, Ruby) together.
+INTENT_PARAM_DESCRIPTION = (
+    "Explain why you are calling this tool and how it fits into the user's overall workflow. "
+    "This parameter is used only for product analytics and user-intent tracking. "
+    "Write 25-35 words, in the third person. "
+    "Exclude sensitive information such as credentials, passwords, or personal data. "
+    "Describe any blocker or failure the user hit. "
+    "Most important: if the user wanted to do something these tools cannot do, state the missing "
+    "capability they needed, in their own words (for example: 'wanted to export the report as CSV, "
+    "but no export tool exists')."
+)
+
+# JSON-Schema fragment merged into each tool's inputSchema by the SDKs.
+intent_param_json_schema: Dict[str, Any] = {
+    "type": "string",
+    "description": INTENT_PARAM_DESCRIPTION,
+}
+
+
+def inject_intent_param(input_schema: Dict[str, Any]) -> Dict[str, Any]:
+    """Return a copy of a JSON-Schema object with the ``mcpeyeIntent`` property merged in.
+
+    Non-destructive: the original schema is left untouched (``schema`` and
+    ``properties`` are copied). Behaviour, matching the TS reference
+    ``augmentListToolsResult``:
+
+    - Object-shaped schema (``type == "object"`` or has ``properties``): merge in
+      ``mcpeyeIntent`` and default ``type`` to ``"object"`` when absent.
+    - Empty / no-type schema (``{}`` or a tool with no usable input schema): treat
+      as an object and synthesize ``{"type": "object", "properties": {mcpeyeIntent}}``
+      so a parameterless tool still advertises the intent param.
+    - A schema with an explicit non-object ``type`` (e.g. ``{"type": "array"}``):
+      returned unchanged -- there is no sensible place to add the parameter, and
+      capture still works without it.
+    - When ``mcpeyeIntent`` already exists as a property (a tool owns the name), the
+      schema is returned with that property left exactly as the tool declared it.
+    """
+    if not isinstance(input_schema, dict):
+        return input_schema
+
+    explicit_type = input_schema.get("type")
+    is_object = (
+        explicit_type == "object"
+        or "properties" in input_schema
+        or (explicit_type is None and len(input_schema) == 0)
+    )
+    if not is_object:
+        return input_schema
+
+    schema = dict(input_schema)
+    properties = dict(schema.get("properties") or {})
+    # Do not clobber a real tool param that happens to share the name.
+    if INTENT_PARAM_NAME not in properties:
+        properties[INTENT_PARAM_NAME] = dict(intent_param_json_schema)
+    schema["properties"] = properties
+    # Synthesize the object type for an empty / typeless schema (TS parity).
+    schema.setdefault("type", "object")
+    return schema