跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
浏览器与自动化

add-mcp-tool

Use when adding or extending a tool in the zendriver-mcp crate — exposing a zendriver `Tab`/`Browser`/`Frame`/`Element` API to MCP clients, creating a new `browser_*` tool, or changing a tool's input/output type. Triggers on edits under `crates/zendriver-mcp/src/tools/` or the `#[tool]` wrappers in `server.rs`. Keywords: rmcp, tool_router, JsonSchema, insta snapshot, coverage ledger, public_api, deny_unknown_fields, AckOutput.

TurtIeSocks · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add TurtIeSocks/zendriver-rs --skill add-mcp-tool

技能说明


name: add-mcp-tool description: >- Use when adding or extending a tool in the zendriver-mcp crate — exposing a zendriver Tab/Browser/Frame/Element API to MCP clients, creating a new browser_* tool, or changing a tool's input/output type. Triggers on edits under crates/zendriver-mcp/src/tools/ or the #[tool] wrappers in server.rs. Keywords: rmcp, tool_router, JsonSchema, insta snapshot, coverage ledger, public_api, deny_unknown_fields, AckOutput.

Add a zendriver-mcp tool

Overview

A tool is two pieces: a handler (free async fn + typed I/O structs) in tools/<category>.rs, and a thin #[tool] wrapper in server.rs that delegates to it. Two gates fail late (not in stable PR CI) and are routinely forgotten — the schema snapshot and the coverage ledger. This skill is mostly about not skipping them.

Mirror the canonical examples instead of inventing shape:

  • tools/scroll.rs — smallest complete end-to-end tool (I/O structs + handler + no-browser test).
  • tools/stealth.rs — reuses the shared actions::AckOutput for fire-and-forget tools.
  • server.rs base_tool_router block — the #[tool] wrapper pattern.

Categories (one file each under tools/): actions cloudflare cookies download eval expect fetcher find fingerprints frames imperva intercept lifecycle monitor mouse navigation pdf reads request scroll snapshot stealth storage tabs window. Add to the matching file; only make a new module for a genuinely new category.

Procedure

  1. Handler + I/O in tools/<category>.rs (use an existing category file; only add a new module for a genuinely new category).
  2. Wrapper — a #[tool] method in server.rs in the right router block (see table).
  3. mod.rs — pub mod <x>; only if you created a new module (#[cfg(feature = "...")] if gated).
  4. Snapshot — register + regenerate + accept + commit the .snap (gate #1).
  5. Ledger — add a covered/excluded entry for any new zendriver symbol exposed (gate #2).
  6. Verify — fmt, clippy, snapshot test, no-browser unit test.

Handler template (mirror scroll.rs)

use std::sync::Arc;
use rmcp::ErrorData;
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use tokio::sync::Mutex;

use crate::errors::{McpServerError, map_error};
use crate::state::SessionState;
use crate::tools::common::current_tab; // + page_snapshot if you support return_snapshot

/// Input for `browser_<name>`.
#[derive(Debug, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)] // REQUIRED on every input struct
pub struct FooInput {
    /// Doc comments BECOME the JSON-schema `description` — write them for the agent.
    pub bar: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub speed: Option<i64>,
}

// Fire-and-forget? Reuse `crate::tools::actions::AckOutput { ok: bool }` — do NOT
// invent a new output type. Returning data? Define a `#[derive(Debug, Serialize, JsonSchema)]`
// output and use `#[serde(skip_serializing_if = "Option::is_none")]` on optional fields.

pub async fn foo(state: Arc<Mutex<SessionState>>, input: FooInput)
    -> Result<crate::tools::actions::AckOutput, ErrorData>
{
    let s = state.lock().await;
    let tab = current_tab(&s).await?; // surfaces BrowserNotOpen / NoCurrentTab
    tab.some_api(input.bar)
        .await
        .map_err(|e| map_error(McpServerError::from(e)))?; // mandatory uniform error mapping
    Ok(crate::tools::actions::AckOutput { ok: true })
}

#[cfg(test)] // REQUIRED no-browser test — unit tests have no Chrome
#[allow(clippy::panic, clippy::unwrap_used)]
mod tests {
    use super::*;
    #[tokio::test]
    async fn foo_without_browser_errors() {
        let state = Arc::new(Mutex::new(SessionState::new()));
        let err = foo(state, FooInput { bar: "x".into(), speed: None })
            .await.expect_err("expected BrowserNotOpen");
        assert!(err.message.contains("Browser not open"));
    }
}

Wrapper template (in server.rs)

/// Doc comment should track the `description` string below.
#[tool(name = "browser_foo", description = "…agent-facing description…")]
pub async fn browser_foo(
    &self,
    Parameters(input): Parameters<foo::FooInput>, // rmcp `Parameters(..)` wrapper is mandatory
) -> Result<Json<actions::AckOutput>, ErrorData> {
    foo::foo(self.state.clone(), input).await.map(Json) // one-line delegate + `.map(Json)`
}

No-arg tool? Use the shared crate::tools::common::EmptyInput (a pub struct EmptyInput {}, constructed EmptyInput {}) — for both the handler param and Parameters<EmptyInput>. It is already schema-snapshotted (common_empty_input), so a no-arg tool registers only its output snapshot. Tool name must be globally unique across every router (a duplicate #[tool(name=...)] collides at runtime).

Which router block?

Tool is…Put wrapper inAlso edit combined_tool_router()?
always availablebase_tool_router blockno
under an existing feature (interception/expect/monitor/cloudflare/imperva/fetcher/fingerprints)that feature's #[cfg(feature=…)] #[tool_router(router = <feat>_tool_router)] blockno (already summed)
under a brand-new featurea new #[cfg(feature=…)] #[tool_router(router = <feat>_tool_router)] blockyes — add #[cfg] let router = router + Self::<feat>_tool_router();

The tool_router macro can't see through per-method #[cfg], which is why feature tools live in separate impl blocks summed by combined_tool_router().

The two gates that fail late (don't skip)

Gate 1 — schema snapshot. Register each new I/O type in tests/schema_snapshots.rs, naming the snapshot <category>_<thing>_in / _out (e.g. schema_snap!(scroll_page_out, tools::scroll::PageScrollOutput);). Then:

cargo test -p zendriver-mcp --test schema_snapshots --all-features --locked
cargo insta acc
阅读完整来源 ↗