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 sharedactions::AckOutputfor fire-and-forget tools.server.rsbase_tool_routerblock — 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
- Handler + I/O in
tools/<category>.rs(use an existing category file; only add a new module for a genuinely new category). - Wrapper — a
#[tool]method inserver.rsin the right router block (see table). - mod.rs —
pub mod <x>;only if you created a new module (#[cfg(feature = "...")]if gated). - Snapshot — register + regenerate + accept + commit the
.snap(gate #1). - Ledger — add a
covered/excludedentry for any newzendriversymbol exposed (gate #2). - 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 in | Also edit combined_tool_router()? |
|---|---|---|
| always available | base_tool_router block | no |
under an existing feature (interception/expect/monitor/cloudflare/imperva/fetcher/fingerprints) | that feature's #[cfg(feature=…)] #[tool_router(router = <feat>_tool_router)] block | no (already summed) |
| under a brand-new feature | a new #[cfg(feature=…)] #[tool_router(router = <feat>_tool_router)] block | yes — 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
阅读完整来源 ↗