Skip to content

docs(mcp): document list_watches and cancel_watch in MCP integration table (#2110)#2134

Merged
qin-ctx merged 2 commits into
volcengine:mainfrom
r266-tech:docs-mcp-integration-watch-tools-2110
May 20, 2026
Merged

docs(mcp): document list_watches and cancel_watch in MCP integration table (#2110)#2134
qin-ctx merged 2 commits into
volcengine:mainfrom
r266-tech:docs-mcp-integration-watch-tools-2110

Conversation

@r266-tech
Copy link
Copy Markdown
Contributor

Summary

Updates the Available MCP Tools table in docs/{en,zh}/guides/06-mcp-integration.md to reflect the two new MCP tools added by #2110 (Watch Management API). Pre-#2110 the table claimed "9 tools" and listed 9 rows. After #2110 the MCP endpoint exposes 11 tools (list_watches + cancel_watch added in openviking/server/mcp_endpoint.py L618 / L655), so the integration guide that clients land on for tool discovery is now stale by 2 rows and a count.

This catch is scoped to the client-facing setup guide only. The deeper API reference (REST routes, CLI subcommands, MCP closure rationale) for the same feature is covered separately in #2123 under docs/{en,zh}/api/02-resources.md. Zero file overlap with #2123.

Why this matters

A user wiring up an MCP client lands on guides/06-mcp-integration.md to discover what tools OpenViking advertises. The current table omits list_watches and cancel_watch, so:

  • Agents auto-introspecting the table to plan tool use will miss the watch management surface entirely.
  • Operators writing system prompts that enumerate "the X OpenViking MCP tools" will under-count or list stale parameters.
  • The literal "9 tools" sentence directly contradicts the 11 tools actually exposed at runtime — a trivially-falsifiable claim that erodes doc trust.

Source of truth

All description and parameter text is paraphrased verbatim from the docstrings on the two @mcp.tool() decorated functions in openviking/server/mcp_endpoint.py (commit fc5ed54):

  • list_watches() -> str — no parameters, per-agent visibility, returns table-formatted lines.
  • cancel_watch(to_uri: str) -> str — single required URI parameter, must match the watch task's to value.

The trailing note ("Pause / resume / trigger / update intentionally not exposed") is paraphrased from the source-of-truth comment block at mcp_endpoint.py L609-614, which explicitly says MCP exposes the minimum closure and points power users at REST or ov task watch CLI.

Changes

  • docs/en/guides/06-mcp-integration.md: 9 tools11 tools, insert 2 rows after the add_resource row, append a one-line note pointing watch power-users at REST / CLI for the remaining verbs.
  • docs/zh/guides/06-mcp-integration.md: mirrored ZH update with the same byte-mirror structure.

Net: +8 LOC additive, 0 deletions other than the count number.

Test plan

  • Both files render — table column alignment preserved, blockquote note renders.
  • EN/ZH parity verified — both tables now have 11 rows under the same heading.
  • Tool names + parameters verified against openviking/server/mcp_endpoint.py at HEAD (commit fc5ed54).
  • No code change — docs-only PR.
  • Pre-existing add_resource watch_interval parameter description left untouched; this PR only adds rows + count + closing note.

@github-actions
Copy link
Copy Markdown

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

🎫 Ticket compliance analysis ✅

2123 - Fully compliant

Compliant requirements:

  • Update MCP integration guide in en and zh to add new watch tools
  • Update tool count from 9 to 11
  • Add note about minimum closure in MCP
⏱️ Estimated effort to review: 1 🔵⚪⚪⚪⚪
🏅 Score: 100
🧪 No relevant tests
🔒 No security concerns identified
✅ No TODO sections
🔀 No multiple PR themes
⚡ No major issues detected

@github-actions
Copy link
Copy Markdown

PR Code Suggestions ✨

No code suggestions found for the PR.

@qin-ctx qin-ctx merged commit c11e19f into volcengine:main May 20, 2026
3 checks passed
@github-project-automation github-project-automation Bot moved this from Backlog to Done in OpenViking project May 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

2 participants