From b155e28d786e51738af444477b1b094e2e19647e Mon Sep 17 00:00:00 2001 From: silviu Date: Mon, 18 May 2026 22:17:48 +0300 Subject: [PATCH] docs(v1.6.16): close doc-update gaps + document new tools + bump GH repo desc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - docs/API_REFERENCE.md §16: document the two new tools (td_get_activity_log, td_self_update) + new `_read_journal` response envelope. The header was already at "v1.6.16 | 106 tools" but the tool tables only had the v1.6.15 surface — closes that gap so the auto-generated header is honest. - docs/INSTALL_CLAUDE_PLUGIN.md: "104 MCP tools" → "106 MCP tools". - td_component/build_export_mcp_tox.py: docstring examples that illustrated the versioned-tox filename pattern used 1.6.15 as a placeholder; bumped to 1.6.16 to match current state. - GitHub repo description bumped via `gh repo edit` from "v1.6.14 ... 104 MCP tools" to "v1.6.16 ... 106 MCP tools, agent activity log, self-update". (Not in any file; manage via gh CLI per CLAUDE.md binding rule.) Pre-push gate per the new ruff binding rule: `ruff check` + `ruff format --check` both clean; 970 pytest pass. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/API_REFERENCE.md | 25 +++++++++++++++++++++++++ docs/INSTALL_CLAUDE_PLUGIN.md | 2 +- td_component/build_export_mcp_tox.py | 8 ++++---- 3 files changed, 30 insertions(+), 5 deletions(-) diff --git a/docs/API_REFERENCE.md b/docs/API_REFERENCE.md index c0788ee..70ef258 100644 --- a/docs/API_REFERENCE.md +++ b/docs/API_REFERENCE.md @@ -238,6 +238,31 @@ All tools in this section execute Python inside TouchDesigner. Most require `ful | `td_get_server_metrics` | Get MCP server runtime metrics: telemetry, events, streams, safety, snapshots, jobs, audit status. | _(none)_ | JSON with `runtime`, `telemetry`, `events`, `visual_monitor`, `top_stream`, `safety`, `snapshots`, `jobs`, `audit_enabled`. | | `td_describe_surface` | Describe the MCP server surface: tool count, resource count, capabilities, version. | _(none)_ | JSON with `version`, `tool_count`, `resource_count`, `capabilities`. | | `td_tool_batch` | Dispatch up to 8 tool calls in a single model roundtrip. Sequential execution; per-call failures don't abort siblings. Backport from deepseek-v4. | `calls` (list[dict], **required**, max 8): Each entry is `{tool: str, args: dict}`. | JSON with `ok: true`, `count` (int), `results` array of `{tool, ok, result, error, elapsed_ms}`. | +| `td_get_activity_log` *(new in v1.6.16)* | Return recent tool-call activity from a 200-entry server-side ring buffer (mirrored to in-TD Table DAT `/local/mcp_server/activity_log`). | `limit` (int, default 20, 1-200), `tool_filter` (str, optional, exact tool name match). | JSON with `schema_version`, `count`, `max_buffer`, `entries[]` (newest first; each entry has `ts`, `tool`, `args_summary`, `result_summary`, `duration_ms`, `ok`). | +| `td_self_update` *(new in v1.6.16)* | Check (and optionally install) the latest TDPilot release from GitHub. Pure-stdlib so it also runs from TD Textport via `python -m td_mcp.self_updater`. | `check_only` (bool, default `True`). When `False`, downloads the asset and writes it to the three install paths (repo working-tree, Claude Code plugin cache, `~/.tdpilot/`). | JSON with `installed`, `latest`, `newer_available`, `release_url`, `follow_up` (re-run-setup_mcp_in_td.py reminder). When `check_only=False` and an update happened: `installed_to[]`, `md5{path: hash}`, `bytes_written`. | + +### Response envelope: `_read_journal` *(new in v1.6.16)* + +Every successful tool response routed through the MCP dispatcher now carries an +extra top-level field on its JSON envelope: + +```json +{ + "...tool-specific fields...": "...", + "_read_journal": { + "call_count": 3, + "first_seen_at": "2026-05-18T18:30:00Z", + "last_seen_at": "2026-05-18T18:32:01Z", + "result_unchanged": true + } +} +``` + +* `call_count` — how many times this session has dispatched the same tool with the same arguments. +* `result_unchanged` — `null` on the first call; `true` when the repeated result hash matches the previous one; `false` when it differs. +* The journal is **advisory only** — every call still executes against TD. The hint exists so AI agents can decide whether to re-fetch across MCP request boundaries without paying token cost on stable data. +* Bounded to 500 distinct `(tool_name, args_fingerprint)` keys; oldest-by-`last_seen_at` evicted under pressure. +* **Not** attached on error responses (4xx / `success: false` envelopes) — error responses have no meaningful "result hash" to dedupe. --- diff --git a/docs/INSTALL_CLAUDE_PLUGIN.md b/docs/INSTALL_CLAUDE_PLUGIN.md index 1129ec6..e599b31 100644 --- a/docs/INSTALL_CLAUDE_PLUGIN.md +++ b/docs/INSTALL_CLAUDE_PLUGIN.md @@ -1,7 +1,7 @@ # Installing TDPilot as a Claude Code Plugin TDPilot ships as a Claude Code plugin via the `dreamrec/TDPilot` marketplace. -You get 104 MCP tools, three skills (`tdpilot-core`, `tdpilot-production`, +You get 106 MCP tools, three skills (`tdpilot-core`, `tdpilot-production`, `popx-touchdesigner`), two slash commands (`/td-check`, `/td-snapshot`), and the TD-side `.tox` component all in one install. diff --git a/td_component/build_export_mcp_tox.py b/td_component/build_export_mcp_tox.py index 0e5a66d..ab4e4ba 100644 --- a/td_component/build_export_mcp_tox.py +++ b/td_component/build_export_mcp_tox.py @@ -309,9 +309,9 @@ def _read_pkg_version(repo_root): def _save_versioned_export(repo_root, export_comp, canonical_path): """Save a versioned `.tox` sidecar with a version-named COMP baked in. - For ``td_component/tdpilot.tox`` at version ``1.6.15`` this produces - ``td_component/tdpilot1.6.15.tox`` whose embedded COMP is named - ``tdpilot1_6_15`` (underscores — TD operator names disallow dots). + For ``td_component/tdpilot.tox`` at version ``1.6.16`` this produces + ``td_component/tdpilot1.6.16.tox`` whose embedded COMP is named + ``tdpilot1_6_16`` (underscores — TD operator names disallow dots). Result: when a user drags this `.tox` into TD's network view, the resulting COMP shows the version in its node label immediately — no need to open the info DAT to identify which build is loaded. @@ -325,7 +325,7 @@ def _save_versioned_export(repo_root, export_comp, canonical_path): then renaming back to ``mcp_server`` before the caller's downstream install step runs. - Filename keeps dots (``tdpilot1.6.15.tox``) for semver clarity and to + Filename keeps dots (``tdpilot1.6.16.tox``) for semver clarity and to match Finder-friendly version strings; COMP name uses underscores (``tdpilot1_6_15``) because TD operator names allow only alphanumerics and underscores.