From f5bd635db878796f504bfe00bcb0303edd38ace6 Mon Sep 17 00:00:00 2001 From: BlockVectra <5194435+gjwang@users.noreply.github.com> Date: Wed, 11 Nov 2026 17:19:54 +0800 Subject: [PATCH 1/2] docs: add standalone mcp-use documentation example --- AGENTS.md | 1 + README.md | 14 ++ README.zh.md | 14 ++ examples/mcp-use-docs/package-lock.json | 228 ++++++++++++++++++++++++ examples/mcp-use-docs/package.json | 15 ++ examples/mcp-use-docs/remote-docs.ts | 91 ++++++++++ 6 files changed, 363 insertions(+) create mode 100644 examples/mcp-use-docs/package-lock.json create mode 100644 examples/mcp-use-docs/package.json create mode 100644 examples/mcp-use-docs/remote-docs.ts diff --git a/AGENTS.md b/AGENTS.md index 841d199..2f7224a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,6 +10,7 @@ Choose the entry that matches the requested task before installing dependencies | Read documentation through Google ADK tools | [ADK MCP example](examples/adk_docs.py) and the README section “Read documentation with Google ADK”; Python 3.11+, uv, no model, Cloud project or account key. | | Read documentation through Pydantic AI tools | [Pydantic AI MCP example](examples/pydantic_docs.py) and the README section “Read documentation with Pydantic AI”; Python 3.11+, uv, no model or account key. | | Read documentation through the OpenAI Agents SDK | [OpenAI Agents SDK MCP example](examples/openai_agents_docs.py) and the README section “Read documentation with the OpenAI Agents SDK”; Python 3.12+, uv, no model or account key. | +| Read documentation with mcp-use from Node.js | [Standalone mcp-use example](examples/mcp-use-docs/remote-docs.ts) and the README section “Read documentation with mcp-use (Node.js)”; Node.js 22.22.2+, no model or account key. | | Check a chain's identity with Python | [Standard-library public reader](examples/public_chain.py) and the README section “Python standard-library entry”. | | Check chain identity and read the latest block number | [Public TypeScript reader](src/public-read-cli.ts) and the README section “Start with a keyless read”. | | Inspect a saved BSC receipt and fixed-block logs offline | [Pinned BSC event sample](https://gist.github.com/gjwang/5a8f80f5e441a5701e2e01ae73f187bf/0f680ce849c78375537fce5ed1ce9e447fe2f341) and the README section “Check a saved BSC receipt and its logs”; Node.js 22+, no account or key. | diff --git a/README.md b/README.md index b5b5d24..58df045 100644 --- a/README.md +++ b/README.md @@ -455,6 +455,20 @@ The `async with server` block keeps the connection open for both calls and close This calls the SDK-managed MCP server directly; it does not run an `Agent` or `Runner`. For a model-backed agent, configure your model separately and pass the same server in the agent's `mcp_servers`. See the [official OpenAI Agents SDK guide](https://developers.openai.com/api/docs/guides/agents/integrations-observability). This example does not test a model-driven agent workflow. +### Read documentation with mcp-use (Node.js) + +Use the standalone [mcp-use example](examples/mcp-use-docs/remote-docs.ts) with Node.js 22.22.2+: + +```bash +cd examples/mcp-use-docs +npm ci --ignore-scripts +npm start +``` + +It connects to the docs-only MCP endpoint, lists the tools, searches for `quickstart` in English and prints the page returned by the search. No local server, model, account or API key is needed. The client closes on success or failure; tool errors and empty results stop the script. Calls have 15-second timeouts. Dependency installation needs network access and happens before the script starts. + +The example pins `@mcp-use/client` to 2.4.5 and commits its dependency lockfile. Internal QA runs set `BLOCKVECTRA_INTERNAL_QA=1`; ordinary runs leave it unset. Reading the document does not execute its RPC or account instructions. + ### 1. Claude Code Configuration #### Keyless Documentation MCP diff --git a/README.zh.md b/README.zh.md index 7c2b6b0..48e8a1d 100644 --- a/README.zh.md +++ b/README.zh.md @@ -455,6 +455,20 @@ uv run examples/openai_agents_docs.py 此例直接调用由 SDK 管理的 MCP server，不运行 `Agent` 或 `Runner`。需要模型参与时，另行配置模型，并把同一个 server 放入 agent 的 `mcp_servers`。参见 [OpenAI Agents SDK 官方指南](https://developers.openai.com/api/docs/guides/agents/integrations-observability)。此例未验证模型驱动的 Agent 工作流。 +### 使用 mcp-use 读取文档（Node.js） + +使用独立的 [mcp-use 示例](examples/mcp-use-docs/remote-docs.ts)，需要 Node.js 22.22.2+： + +```bash +cd examples/mcp-use-docs +npm ci --ignore-scripts +npm start +``` + +示例连接仅文档 MCP 入口，列出工具，用英语搜索 `quickstart`，然后打印搜索返回的页面。无需本地服务、模型、账号或 API key。成功或失败都会关闭客户端；工具报错或结果为空时停止。每次调用超时为 15 秒。安装依赖需要联网，在脚本启动前完成。 + +示例固定 `@mcp-use/client` 2.4.5，并提交依赖锁文件。内部 QA 设置 `BLOCKVECTRA_INTERNAL_QA=1`，正常使用时不设置。读取文档不会执行文中的 RPC 或账号操作。 + ### 1. Claude Code 配置 #### 免 Key 文档服务 diff --git a/examples/mcp-use-docs/package-lock.json b/examples/mcp-use-docs/package-lock.json new file mode 100644 index 0000000..6ff6100 --- /dev/null +++ b/examples/mcp-use-docs/package-lock.json @@ -0,0 +1,228 @@ +{ + "name": "blockvectra-mcp-use-docs-example", + "version": "1.0.0", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "blockvectra-mcp-use-docs-example", + "version": "1.0.0", + "dependencies": { + "@mcp-use/client": "2.4.5" + }, + "engines": { + "node": ">=22.22.2" + } + }, + "node_modules/@mcp-use/client": { + "version": "2.4.5", + "resolved": "https://registry.npmjs.org/@mcp-use/client/-/client-2.4.5.tgz", + "integrity": "sha512-/Z1tjbyZGzxD3ef2WCOX/hfbhUTkcoMnY9REcjdVvRCBPII+qWA00u6nEffOESy7QN6OLeq8R5w7okqBpgZECA==", + "license": "MIT", + "dependencies": { + "@modelcontextprotocol/client": "2.3.1", + "@modelcontextprotocol/core": "2.3.1", + "@modelcontextprotocol/ext-apps": "2.0.3" + }, + "engines": { + "node": ">=22.22.2" + }, + "peerDependencies": { + "@e2b/code-interpreter": "^2.6.1", + "react": "^18.0.0 || ^19.0.0", + "zod": "^4.2.0" + }, + "peerDependenciesMeta": { + "@e2b/code-interpreter": { + "optional": true + }, + "react": { + "optional": true + } + } + }, + "node_modules/@modelcontextprotocol/client": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/@modelcontextprotocol/client/-/client-2.3.1.tgz", + "integrity": "sha512-mIGZXpHsjnZ6lD+gD/WCMpR5k8yVQQ8nNFH1N0Srf7AvnwTUMYD6pvTY8ng2+He5FfV7YMZLmrjL7cLa/cc3dQ==", + "license": "Apache-2.0", + "dependencies": { + "@modelcontextprotocol/core": "2.3.1", + "cross-spawn": "^7.0.5", + "eventsource": "^3.0.2", + "eventsource-parser": "^3.0.8", + "jose": "^6.1.3", + "pkce-challenge": "^5.0.0", + "zod": "^4.2.0" + }, + "engines": { + "node": ">=20" + } + }, + "node_modules/@modelcontextprotocol/core": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/@modelcontextprotocol/core/-/core-2.3.1.tgz", + "integrity": "sha512-laVmIhPGpWi7rG9q+0UigblRN0Hws/Yjlb6qLFtVqryXVLkc4h+yN8z731POD2LnAGQlFe7/tXhUm7Bi0YB91g==", + "license": "Apache-2.0", + "dependencies": { + "zod": "^4.2.0" + }, + "engines": { + "node": ">=20" + } + }, + "node_modules/@modelcontextprotocol/ext-apps": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/@modelcontextprotocol/ext-apps/-/ext-apps-2.0.3.tgz", + "integrity": "sha512-Tn+4+cyhO4f4cQSDxNyLiIfEE+qlTTuIbWBJB8JTinEXOhDYgCT4wDTQplxD9MBYZH5pCYGC59GaxiwIT4bu8w==", + "license": "MIT", + "workspaces": [ + "examples/*" + ], + "dependencies": { + "@standard-schema/spec": "^1.1.0" + }, + "engines": { + "node": ">=20" + }, + "peerDependencies": { + "@modelcontextprotocol/client": "^2.0.0", + "@modelcontextprotocol/core": "^2.0.0", + "@modelcontextprotocol/server": "^2.0.0", + "react": "^17.0.0 || ^18.0.0 || ^19.0.0", + "react-dom": "^17.0.0 || ^18.0.0 || ^19.0.0", + "zod": "^4.2.0" + }, + "peerDependenciesMeta": { + "@modelcontextprotocol/server": { + "optional": true + }, + "react": { + "optional": true + }, + "react-dom": { + "optional": true + } + } + }, + "node_modules/@standard-schema/spec": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/@standard-schema/spec/-/spec-1.1.0.tgz", + "integrity": "sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==", + "license": "MIT" + }, + "node_modules/cross-spawn": { + "version": "7.0.6", + "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz", + "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==", + "license": "MIT", + "dependencies": { + "path-key": "^3.1.0", + "shebang-command": "^2.0.0", + "which": "^2.0.1" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/eventsource": { + "version": "3.0.7", + "resolved": "https://registry.npmjs.org/eventsource/-/eventsource-3.0.7.tgz", + "integrity": "sha512-CRT1WTyuQoD771GW56XEZFQ/ZoSfWid1alKGDYMmkt2yl8UXrVR4pspqWNEcqKvVIzg6PAltWjxcSSPrboA4iA==", + "license": "MIT", + "dependencies": { + "eventsource-parser": "^3.0.1" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/eventsource-parser": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/eventsource-parser/-/eventsource-parser-3.1.1.tgz", + "integrity": "sha512-EKN1vKAMcZ8MlYMpaNuxN6R9yakzH6uajHcHVTqWJzvu5pWw9DyhbP35HH8MVBQ+dZjAfDxk+A8NiR9KWaXiyQ==", + "license": "MIT", + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/isexe": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz", + "integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==", + "license": "ISC" + }, + "node_modules/jose": { + "version": "6.2.17", + "resolved": "https://registry.npmjs.org/jose/-/jose-6.2.17.tgz", + "integrity": "sha512-wOuK9V1yujQFH5S0ZWmLcDZN7+IKh9bUCC2ZPCf2HDlol3WWHy+PPyNjEI75FXRLMp3vDKQcupP59xhVU95hcg==", + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/panva" + } + }, + "node_modules/path-key": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz", + "integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==", + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/pkce-challenge": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/pkce-challenge/-/pkce-challenge-5.0.1.tgz", + "integrity": "sha512-wQ0b/W4Fr01qtpHlqSqspcj3EhBvimsdh0KlHhH8HRZnMsEa0ea2fTULOXOS9ccQr3om+GcGRk4e+isrZWV8qQ==", + "license": "MIT", + "engines": { + "node": ">=16.20.0" + } + }, + "node_modules/shebang-command": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz", + "integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==", + "license": "MIT", + "dependencies": { + "shebang-regex": "^3.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/shebang-regex": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz", + "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==", + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/which": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz", + "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==", + "license": "ISC", + "dependencies": { + "isexe": "^2.0.0" + }, + "bin": { + "node-which": "bin/node-which" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/zod": { + "version": "4.6.7", + "resolved": "https://registry.npmjs.org/zod/-/zod-4.6.7.tgz", + "integrity": "sha512-g8W2D2kU6a8untc053fX1uVBKzM7yqAxW/3zwk83+6RyF2+SKOuV+c0wBDhUwzV1PaGapmZH+rmcUzPf+3CGwg==", + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/colinhacks" + } + } + } +} diff --git a/examples/mcp-use-docs/package.json b/examples/mcp-use-docs/package.json new file mode 100644 index 0000000..bbd7dfd --- /dev/null +++ b/examples/mcp-use-docs/package.json @@ -0,0 +1,15 @@ +{ + "name": "blockvectra-mcp-use-docs-example", + "private": true, + "version": "1.0.0", + "type": "module", + "engines": { + "node": ">=22.22.2" + }, + "scripts": { + "start": "node remote-docs.ts" + }, + "dependencies": { + "@mcp-use/client": "2.4.5" + } +} diff --git a/examples/mcp-use-docs/remote-docs.ts b/examples/mcp-use-docs/remote-docs.ts new file mode 100644 index 0000000..5246e50 --- /dev/null +++ b/examples/mcp-use-docs/remote-docs.ts @@ -0,0 +1,91 @@ +/** + * Search and read BlockVectra documentation with @mcp-use/client. + * Node.js 22.22.2+; from this directory: npm ci --ignore-scripts && npm start. + * No local server, model, account or API key is needed. + */ + +import { MCPClient } from "@mcp-use/client"; + +const TIMEOUT = 15000; +const LANG = "en"; +// Internal QA runs set BLOCKVECTRA_INTERNAL_QA=1 so traffic can be told apart. +const USER_AGENT = + "mcp-use-remote-docs-example/1" + + (process.env.BLOCKVECTRA_INTERNAL_QA === "1" ? " BlockVectraQA/1" : ""); + +function textOf( + result: { isError?: boolean; content: unknown[] }, + label: string +): string { + if (result.isError) throw new Error(`${label} returned an error result`); + for (const block of result.content) { + if (typeof block !== "object" || block === null) continue; + if ("type" in block && block.type === "text" && "text" in block) { + if (typeof block.text === "string" && block.text.trim()) { + return block.text; + } + } + } + throw new Error(`${label} returned no text content`); +} + +function firstResultPath(payload: unknown): string { + if (typeof payload === "object" && payload !== null && "results" in payload) { + const { results } = payload; + if (Array.isArray(results) && results.length > 0) { + const first: unknown = results[0]; + if (typeof first === "object" && first !== null && "path" in first) { + if (typeof first.path === "string" && first.path !== "") { + return first.path; + } + } + } + } + throw new Error("search_docs returned no usable results; stopping"); +} + +async function main(): Promise { + const client = new MCPClient({ + mcpServers: { + docs: { + url: "https://docs.blockvectra.com/mcp/docs", + oauth: false, + detectMixedAuth: false, + timeout: TIMEOUT, + headers: { + "User-Agent": USER_AGENT, + }, + }, + }, + }); + + try { + const connection = await client.connect("docs"); + + const tools = await connection.listTools({ timeout: TIMEOUT }); + console.log("tools:", tools.map((t) => t.name).join(", ")); + + const search = await connection.callTool( + "search_docs", + { query: "quickstart", lang: LANG, limit: 1 }, + { timeout: TIMEOUT } + ); + const payload: unknown = JSON.parse(textOf(search, "search_docs")); + const path = firstResultPath(payload); + console.log("first result:", path); + + const doc = await connection.callTool( + "read_doc", + { path, lang: LANG }, + { timeout: TIMEOUT } + ); + console.log(textOf(doc, "read_doc")); + } finally { + await client.close(); + } +} + +main().catch((err) => { + console.error(err); + process.exitCode = 1; +}); From d3b9d203cb492723b987a9a24314af2b5afbcaba Mon Sep 17 00:00:00 2001 From: BlockVectra <5194435+gjwang@users.noreply.github.com> Date: Wed, 11 Nov 2026 17:25:07 +0800 Subject: [PATCH 2/2] fix: disable example telemetry before loading the client --- README.md | 2 ++ README.zh.md | 2 ++ examples/mcp-use-docs/.npmrc | 1 + examples/mcp-use-docs/remote-docs.ts | 6 +++++- 4 files changed, 10 insertions(+), 1 deletion(-) create mode 100644 examples/mcp-use-docs/.npmrc diff --git a/README.md b/README.md index 58df045..c2d98f8 100644 --- a/README.md +++ b/README.md @@ -467,6 +467,8 @@ npm start It connects to the docs-only MCP endpoint, lists the tools, searches for `quickstart` in English and prints the page returned by the search. No local server, model, account or API key is needed. The client closes on success or failure; tool errors and empty results stop the script. Calls have 15-second timeouts. Dependency installation needs network access and happens before the script starts. +SDK anonymous telemetry is disabled before the client module loads. + The example pins `@mcp-use/client` to 2.4.5 and commits its dependency lockfile. Internal QA runs set `BLOCKVECTRA_INTERNAL_QA=1`; ordinary runs leave it unset. Reading the document does not execute its RPC or account instructions. ### 1. Claude Code Configuration diff --git a/README.zh.md b/README.zh.md index 48e8a1d..93dd18d 100644 --- a/README.zh.md +++ b/README.zh.md @@ -467,6 +467,8 @@ npm start 示例连接仅文档 MCP 入口，列出工具，用英语搜索 `quickstart`，然后打印搜索返回的页面。无需本地服务、模型、账号或 API key。成功或失败都会关闭客户端；工具报错或结果为空时停止。每次调用超时为 15 秒。安装依赖需要联网，在脚本启动前完成。 +示例在加载客户端模块前关闭 SDK 匿名遥测。 + 示例固定 `@mcp-use/client` 2.4.5，并提交依赖锁文件。内部 QA 设置 `BLOCKVECTRA_INTERNAL_QA=1`，正常使用时不设置。读取文档不会执行文中的 RPC 或账号操作。 ### 1. Claude Code 配置 diff --git a/examples/mcp-use-docs/.npmrc b/examples/mcp-use-docs/.npmrc new file mode 100644 index 0000000..b6f27f1 --- /dev/null +++ b/examples/mcp-use-docs/.npmrc @@ -0,0 +1 @@ +engine-strict=true diff --git a/examples/mcp-use-docs/remote-docs.ts b/examples/mcp-use-docs/remote-docs.ts index 5246e50..85d28d3 100644 --- a/examples/mcp-use-docs/remote-docs.ts +++ b/examples/mcp-use-docs/remote-docs.ts @@ -4,7 +4,11 @@ * No local server, model, account or API key is needed. */ -import { MCPClient } from "@mcp-use/client"; +export {}; + +// Disable SDK telemetry before the module initializes. +process.env.MCP_USE_ANONYMIZED_TELEMETRY = "false"; +const { MCPClient } = await import("@mcp-use/client"); const TIMEOUT = 15000; const LANG = "en";