@nstdata-ai/mcp-server 0.0.0-stage → 1.0.1

package/docs/mcp_zh.md

@@ -0,0 +1,193 @@
+# MCP 客户端接入与 Crawl 参考
+
+[English](mcp.md) · [快速开始](../README_zh.md)
+
+## 客户端接入
+
+安装后使用 [README_zh.md](../README_zh.md) 中的 stdio 配置。
+
+- **Cursor：** 项目配置为 `.cursor/mcp.json`，用户配置为 `~/.cursor/mcp.json`。本地服务条目也可使用 `envFile` 指向受保护凭据文件的绝对路径，见 [Cursor MCP 文档](https://cursor.com/docs/mcp)。
+- **Claude Desktop：** 按[本地 MCP 接入文档](https://modelcontextprotocol.io/docs/develop/connect-local-servers)将条目合入客户端配置。
+
+标准配置通过 `npx` 启动安装包，保留其他服务条目。凭据不纳入版本控制。修改环境配置后重启该 MCP 服务。
+
+仅 Crawl 提供6个工具，仅 Proxy 提供2个，同时启用提供8个。提交任务前先确认工具发现成功。启动失败时查看客户端诊断或 stderr，依次核对受支持的 Node 版本、`npx` 可用性和必填环境变量。图形客户端找不到 `npx` 时，可改用它的绝对可执行路径，保留包名参数。
+
+## 配置
+
+| 变量 | 默认值 | 约束 |
+|---|---|---|
+| `NSTDATA_MODULES` | `crawl` | `crawl`、`proxy`，或逗号分隔的两者 |
+| `NSTDATA_API_TOKEN` | 无 | 启用 Crawl 时必填 |
+| `NSTDATA_API_BASE_URL` | `https://api.nstdata.io` | 可信 HTTP(S) 地址，不含凭据、查询串或 fragment |
+| `NSTDATA_HTTP_TIMEOUT_MS` | `120000` | 整数1–600000；本地工具期限，包含正文读取 |
+| `NSTDATA_MAX_RESPONSE_BYTES` | `8388608` | 整数256–67108864；每次 API／存储下载上限 |
+| `NSTDATA_MAX_OUTPUT_CHARS` | `16000` | 整数1024–64000；每份序列化 JSON 的 UTF-16 代码单元上限 |
+| `NSTDATA_MAX_CRAWL_PAGES` | `10` | 整数1–1000；`maxPages` 的默认值和本地允许上限 |
+
+Proxy 专用变量见 [proxy_zh.md](proxy_zh.md)。未启用的模块不要求其凭据。
+
+## 工具参考
+
+| 工具 | 必填输入 | 操作与结果 |
+|---|---|---|
+| `nstdata_crawl_scrape` | `url` | 一次同步／异步单页提交；返回状态和内容或任务 ID |
+| `nstdata_crawl_scrape_result` | `taskId` | 一次结果查询；保留状态及可用内容／引用 |
+| `nstdata_crawl_start` | `url` | 一次有页数上限的整站提交；返回实际任务 ID |
+| `nstdata_crawl_status` | `crawlId` | 一次汇总进度查询，不自动轮询 |
+| `nstdata_crawl_pages` | `crawlId` | 一页结果、实际游标及逐页状态 |
+| `nstdata_crawl_read_result` | `ref`、`format` | 一次有体积上限的引用下载及本地分块 |
+
+提交工具可能创建计费任务，读取也可能消耗服务资源。`formats` 支持 `markdown`（默认）、`html`、`links`、`pdf`、`screenshot`、`rawData`，每次1–6项。单页 `mode` 默认为 `sync`，不接受整站页数／深度选项。代理工具见 [Proxy 参考](proxy_zh.md#工具)。
+
+## 使用流程
+
+### 单页抓取
+
+```json
+{
+  "name": "nstdata_crawl_scrape",
+  "arguments": {
+    "url": "https://example.com/",
+    "formats": [
+      "markdown"
+    ],
+    "mode": "sync",
+    "options": {
+      "onlyMainContent": true
+    }
+  }
+}
+```
+
+异步使用 `mode: "async"`，保存返回的 `id`，作为 `taskId` 传给 `nstdata_crawl_scrape_result`。每次调用仅查询一次，调用方应限制轮询次数与总等待。同步结果已完成时直接消费，不为取得内容再创建任务。
+
+同步及查询结果保留服务提供的 `id`；查询结果还保留输入的 `taskId`。同步结果包含 ID 不代表该内容一定可再次按 ID 查询。
+
+### 整站与分页
+
+调用 `nstdata_crawl_start` 时显式指定 `maxPages`，保存返回的 `id`，作为 `crawlId` 传给进度和分页工具。
+
+例如收集 Quotes 首页及第二页：
+
+```json
+{
+  "name": "nstdata_crawl_start",
+  "arguments": {
+    "url": "https://quotes.toscrape.com/",
+    "formats": [
+      "markdown"
+    ],
+    "maxPages": 2,
+    "maxDepth": 1,
+    "includeUrls": [
+      "/page/2/"
+    ],
+    "options": {
+      "onlyMainContent": false
+    }
+  }
+}
+```
+
+使用路径选择被发现的链接，起始页单独放在 `url`。过滤条件加入 `/` 可能放行其他路径。上述示例中，`onlyMainContent: true` 仅返回起始页，`false` 才收集到两页；完整页面也可能包含导航。过滤语义由服务决定，`maxPages` 只是上限，应核对返回 URL，不能只看任务完成或数量。
+
+分页输入接受 `limit`（1–100，默认10），以及 `afterCursor`／`beforeCursor` 两者之一。原样复制 `nextCursor`／`prevCursor`；带游标的空页不代表结束。遇到重复游标或达到调用方页数／调用上限时停止。汇总完成不代表每页成功。
+
+列表触发 `OUTPUT_LIMIT` 时，保持相同输入游标，减小 `limit` 至最小1后重新读取该页，再使用成功结果中的游标继续。不能跳过被隐藏的页面结果。
+
+### 引用读取
+
+把 `data.markdownRef` 的原值传给 **`ref`**，不是把 `markdownRef` 当作输入字段名：
+
+```json
+{
+  "name": "nstdata_crawl_read_result",
+  "arguments": {
+    "ref": "RETURNED_MARKDOWN_REF",
+    "format": "markdown",
+    "offset": 0,
+    "length": 2000
+  }
+}
+```
+
+其余对应关系为 htmlRef→html、pdfRef→pdf、screenshotRef→screenshot、rawDataRef→rawData。引用是不可解释的值，不是公开 URL；只读取获准任务返回的引用。
+
+`length` 为1–4000，默认2000。文本按 Unicode 码点偏移并以 UTF-8 返回，损坏 UTF-8 在切片前返回 `INVALID_RESPONSE`。二进制按字节偏移并以 Base64 返回。存在 `nextOffset` 时按其继续；分别解码二进制分块后再拼接字节。每次调用都会在体积上限内重新下载完整引用，再本地切片；不提供 HTTP Range 或持久缓存。
+
+## 选项与浏览器动作
+
+顶层通用输入为 `url`、`formats`，单页还有 `mode`。整站专用顶层输入为 `maxPages`、`maxDepth`（0–100）、`includeUrls`、`excludeUrls`、`ignoreQuery`。`maxPages` 默认为配置的本地上限，初始为10。
+
+服务端请求选项放在 `options` 内，转发时移除这层包装：
+
+| 选项 | 约束 |
+|---|---|
+| `cookies` | 最多100项；name／value 必填；可选 domain／httpOnly／path／secure |
+| `proxy.country` | 两字母国家代码，不接收原始代理凭据 |
+| `headers` | 最多100项；名称最多256字符，字符串值最多8192字符 |
+| `excludeTags`、`includeTags`、`removeSelectors` | 最多100个非空字符串，每项最多8192字符 |
+| `targetSelector` | 一个非空字符串，最多8192字符 |
+| `mobile`、`onlyMainContent` | 布尔值 |
+| `timeout` | 整数1000–60000毫秒；与本地工具期限独立 |
+| `jsRender.waitFor` | 整数1000–30000毫秒 |
+| `jsRender.waitForSelector` | 非空选择器，最多8192字符 |
+| `jsRender.actions` | 最多100项，见下表 |
+
+`includeTags` 可能移除周围结构，仅在确实需要时设置。Cookie 名称非空，值允许空串；Cookie其他可选字符串若提供则非空，最多8192字符。
+
+| 动作 type | 必填字段 | 可选字段 |
+|---|---|---|
+| click | selector | waitSelector |
+| wait | milliseconds | 无 |
+| waitSelector | selector | milliseconds |
+| scrollX | x（整数像素） | text |
+| scrollY | y（整数像素） | text |
+| scrollTo | selector | 无 |
+| fill | selector、text（允许空串） | 无 |
+| execute | execute | 无 |
+| screenshot | 无 | fullScreenshot、particularScreenshot |
+| waitForRequestCompletion | urlPattern | milliseconds |
+
+动作 `milliseconds` 为0–600000整数，与 `jsRender.waitFor` 的范围不同。URL 最多8192字符，任务／整站 ID 最多256字符，游标最多8192字符，存储引用最多4096字符。未知字段会被拒绝。这些是本地输入约束，不代表服务端全部限制或行为保证。
+
+## 结果与错误
+
+`content` 文本与 `structuredContent` 包含同一份 JSON。协议封装和重复表示还会增加传输体积。网页内容不可信，也可能含敏感信息。
+
+某格式存在引用时，只返回引用并省略同格式内联内容。没有引用时，Markdown／HTML 保持字符串，内联 PDF／截图／原始数据使用字节对象：
+
+```json
+{
+  "data": {
+    "screenshot": {
+      "encoding": "base64",
+      "base64": "AP+A"
+    }
+  }
+}
+```
+
+解码 `base64` 得到字节；原始文本先转换为 UTF-8 字节再编码。空内容保留空字符串或空 Base64，缺失内容省略。结果序列化不会自动下载引用。
+
+`data.truncated` 保留服务返回的标记，包括 false；缺失表示未知。它与本地输出上限独立。单页触发输出上限时，若可放入预算，`error.recovery` 保留实际 ID、引用和截断标记。
+
+任务 failed／expired 或 success=false 时设置 `isError`；列表逐页保留失败。缺失状态、耗时或内容表示未知，不能当作成功空结果。
+
+| 错误码 | 含义与处理 |
+|---|---|
+| `AUTHORIZATION_FAILED` | HTTP／业务码401或403；检查凭据与权限 |
+| `RATE_LIMITED` | HTTP／业务码429；停止并核对服务限制 |
+| `UPSTREAM_ERROR` | 请求／响应失败；statusCode 与 apiCode 独立；3xx 表示拒绝重定向 |
+| `TIMEOUT`、`CANCELLED` | 本地等待停止，已提交任务可能仍在执行 |
+| `RESPONSE_LIMIT` | 响应超过下载体积上限 |
+| `INVALID_RESPONSE` | 响应不合法，包括损坏 UTF-8 文本引用 |
+| `OUTPUT_LIMIT` | 序列化输出超限；减小页／分块，或使用实际 recovery 标识 |
+| `SENSITIVE_OUTPUT` | 配置凭据命中字段名、二进制或不透明标识，结果被隐藏 |
+
+所有请求均不自动重试。提交时发生连接失败、服务端错误或响应无法读取／超限，可能在没有收到 ID 时已创建任务。错误会说明结果未知；先查服务任务历史，不能直接重提。异步确认必须包含可供查询工具接受的 ID；缺失或不可用时也属于未知结果。明确任务失败、无诊断 ID 的同步内容及认证／限流拒绝分别处理。
+
+`OUTPUT_LIMIT` 不提供通用续传。仅内联内容可能没有引用，ID 也不保证可分块恢复。配置凭据会从显示文本中过滤，并在字段名、解码后二进制（含嵌套字节对象）中检查；命中字段名、标识或二进制时隐藏而不改写。短凭据也可能命中普通字段名；其他网页秘密不会自动识别。请求错误不包含原始 HTTP 正文或传输消息。
+
+API／存储重定向一律拒绝，包括同源重定向；应配置核实后的最终地址。Proxy 错误见 [proxy_zh.md](proxy_zh.md#错误与输出)。失败读取不会创建或取消任务。

package/docs/proxy.md

@@ -0,0 +1,74 @@
+# Proxy tools
+
+[中文](proxy_zh.md) · [Quick start](../README.md)
+
+## Configuration
+
+Proxy-only requires no Crawl token. Use this client entry and replace the generated proxy connection:
+
+```json
+{
+  "mcpServers": {
+    "nstdata": {
+      "command": "npx",
+      "args": ["--yes", "@nstdata-ai/mcp-server@1.0.1"],
+      "env": {
+        "NSTDATA_MODULES": "proxy",
+        "NSTDATA_PROXY_URL": "http://PROXY_USER:PROXY_PASSWORD@PROXY_HOST:PROXY_PORT",
+        "NSTDATA_PROXY_CHECK_URL": "https://api.nstdata.io/api/v2/public/utility/client-ip"
+      }
+    }
+  }
+}
+```
+
+For both modules, set `NSTDATA_MODULES=crawl,proxy` and add `NSTDATA_API_TOKEN` in this same entry. The check URL is operator-selected; the Nstdata echo endpoint above returns the IP observed for that request.
+
+| Variable | Purpose |
+|---|---|
+| `NSTDATA_PROXY_URL` | Required HTTP/HTTPS gateway URL, including encoded username/password when needed |
+| `NSTDATA_PROXY_CHECK_URL` | Required HTTP/HTTPS target for `nstdata_proxy_check` |
+| `NSTDATA_PROXY_CA_FILE` | Optional absolute path to a PEM CA bundle for Proxy TLS only |
+
+Use the full generated Nstdata or PM Router URL. Preserve channel/region/session/task username syntax. Gateway and target can each be HTTP or HTTPS; HTTPS targets use CONNECT. SOCKS proxies are not supported.
+
+CA files must be regular files, at most 1 MiB, containing parseable certificates. Trust is added to Node's default CA set; gateway/target hostname verification stays enabled. Crawl trust settings are unchanged.
+
+## Tools
+
+- `nstdata_proxy_fetch`: `url`, optional `method` (GET/HEAD), target `headers`, and `format` (`text` or `base64`).
+- `nstdata_proxy_check`: no arguments; checks only the configured target and returns status and elapsed milliseconds. `observedIp` is included only when the response supplies a valid plain IP, JSON `ip` string, or successful Nstdata envelope (`code=200`, `err=false`, `data.ip`). Invalid or unavailable IPs are omitted. The same single request supplies status, duration and any IP; no second probe or IP information lookup is performed.
+
+`elapsedMs` covers the request through complete body decoding; it is not TCP latency, TTFB or bandwidth. An echo identifies what that endpoint observed; a rotating proxy may use a different exit for another target or request.
+
+These tools forward requests; they do not render browsers, manage PM resources or verify exit region/anonymity. Calls may consume proxy traffic.
+
+## Request behavior
+
+Each call uses one connection lifetime. There is no redirect following, automatic retry, authentication negotiation, direct-network fallback or persistent connection pool. The local deadline covers DNS, TCP, CONNECT, TLS, headers and body. Cancellation, EOF and SIGTERM close active connections.
+
+Proxy Basic credentials are sent only to the gateway. Target headers may include Authorization/Cookie; send them only to trusted targets. Reserved host/connection/framing/proxy-auth headers and invalid header names/values are rejected. Limits are 100 headers, 256 characters per name, 8192 per value and 8192 per URL.
+
+Response headers, including CONNECT, are capped at 16 KiB. Transferred and decompressed bodies each obey `NSTDATA_MAX_RESPONSE_BYTES`. Gzip/deflate/br are decoded; invalid or unsupported encodings fail. Text must be valid UTF-8 or the tool returns `INVALID_RESPONSE`; base64 preserves decoded body bytes. Network/TLS/framing overhead is not included in the body limit.
+
+Output follows [shared MCP limits](mcp.md#configuration). An oversized Proxy response has no storage reference or local continuation. Use a smaller source response, a target-supported Range request, or an appropriate output limit.
+
+## Errors and output
+
+| Result | Meaning |
+|---|---|
+| Target non-2xx, including 3xx | `isError` with actual target status |
+| `PROXY_AUTHORIZATION_FAILED` | Gateway authentication failed, including 407 |
+| `PROXY_CONNECT_FAILED` | CONNECT establishment failed |
+| `TLS_ERROR` | Gateway or target TLS failed |
+| `UNSUPPORTED_ENCODING`, `INVALID_RESPONSE` | Response decoding or protocol failure |
+| `UNSUPPORTED_RESPONSE` | HTTP 101 upgrades are not supported |
+| `TIMEOUT`, `CANCELLED` | Local request stopped; no automatic retry |
+
+Errors may omit status or timing; keep missing values unknown. A failed check does not establish a quota, billing or region problem.
+
+Only selected response headers are returned. Configured credentials are filtered from display text; sensitive binary/opaque values are withheld with `SENSITIVE_OUTPUT`. Arbitrary target content is not guaranteed secret-free. Gateways that inspect TLS may observe target headers. Avoid debug logging with production credentials.
+
+[Proxy products](https://docs.nstdata.io/docs/proxy) · [PM Router](https://docs.nstdata.io/docs/proxy-manager)
+
+Transport is provided by `@nstdata-ai/proxy-checker/transport`. MCP retains tool validation, credential filtering and output limits; no checker CLI process or additional hosted service is started.

package/docs/proxy_zh.md

@@ -0,0 +1,79 @@
+# Proxy 工具
+
+[English](proxy.md) · [快速开始](../README_zh.md)
+
+## 配置
+
+仅 Proxy 无需 Crawl Token。使用以下客户端条目，替换为平台生成的代理连接：
+
+```json
+{
+  "mcpServers": {
+    "nstdata": {
+      "command": "npx",
+      "args": ["--yes", "@nstdata-ai/mcp-server@1.0.1"],
+      "env": {
+        "NSTDATA_MODULES": "proxy",
+        "NSTDATA_PROXY_URL": "http://PROXY_USER:PROXY_PASSWORD@PROXY_HOST:PROXY_PORT",
+        "NSTDATA_PROXY_CHECK_URL": "https://api.nstdata.io/api/v2/public/utility/client-ip"
+      }
+    }
+  }
+}
+
+```
+
+同时启用两模块时，在同一条目设置 `NSTDATA_MODULES=crawl,proxy` 并补充 `NSTDATA_API_TOKEN`。检测地址由操作者选择；上述 Nstdata 回显接口返回该次请求被观测到的 IP。
+
+| 变量 | 用途 |
+|---|---|
+| `NSTDATA_PROXY_URL` | 必填HTTP／HTTPS网关URL；需要时包含编码后的用户名密码 |
+| `NSTDATA_PROXY_CHECK_URL` | `nstdata_proxy_check` 的必填HTTP／HTTPS目标 |
+| `NSTDATA_PROXY_CA_FILE` | 可选PEM CA文件绝对路径，仅用于Proxy TLS |
+
+使用完整的平台或PM Router连接，保留通道／地域／会话／任务的用户名语法。网关和目标各自可为HTTP或HTTPS；HTTPS目标使用CONNECT。不支持SOCKS代理。
+
+CA文件必须为普通文件、最多1 MiB，并包含可解析证书。信任追加到Node默认CA，网关／目标主机名校验保持开启，不改变Crawl信任设置。
+
+## 工具
+
+| 工具 | 输入 | 结果 |
+|---|---|---|
+| `nstdata_proxy_fetch` | url；可选method（GET／HEAD）、目标headers、format（text／base64） | statusCode、正文、编码及选定响应头 |
+| `nstdata_proxy_check` | 空对象 | statusCode、elapsedMs及可用时的observedIp |
+
+检测只访问配置目标一次。有效纯IP、JSON `ip` 或成功Nstdata包装（code=200、err=false、data.ip）可产生 `observedIp`，无效或缺失时省略。不为检测另发探测或信息查询。
+
+`elapsedMs` 包含请求至完整正文解码完成，不是TCP延迟、TTFB或带宽。回显只说明该接口观测到的出口；轮换代理对另一目标或另一次请求可能使用不同出口。
+
+工具转发请求，不渲染浏览器、不管理PM资源，也不验证出口地域或匿名性。调用可能消耗代理流量。
+
+## 请求行为
+
+每次调用使用一次连接生命周期，不跟随重定向、不自动重试、不协商其他认证方式、不回退直连，也不保留连接池。本地期限覆盖DNS、TCP、CONNECT、TLS、响应头和正文。取消、EOF及SIGTERM会关闭活动连接。
+
+代理Basic凭据仅发送给网关。目标请求头可含Authorization／Cookie，只发送到可信目标。保留的host／连接／消息分帧／代理认证头及无效名称／值会被拒绝。上限为100个头、每名称256字符、每值8192字符、每URL8192字符。
+
+响应头（含CONNECT）最多16 KiB；下载和解压后的正文分别受 `NSTDATA_MAX_RESPONSE_BYTES` 限制。支持gzip／deflate／br解码，无效或不支持的编码失败。text要求有效UTF-8，否则返回 `INVALID_RESPONSE`；base64保留解码后的字节。体积上限不包含网络／TLS／分帧开销。
+
+输出遵循[MCP通用上限](mcp_zh.md#配置)。超大Proxy响应没有存储引用或本地续传；应减少源响应、使用目标支持的Range请求，或配置合适的输出上限。
+
+## 错误与输出
+
+| 结果 | 含义 |
+|---|---|
+| 目标非2xx（含3xx） | isError及实际目标状态 |
+| `PROXY_AUTHORIZATION_FAILED` | 网关认证失败，含407 |
+| `PROXY_CONNECT_FAILED` | CONNECT建立失败 |
+| `TLS_ERROR` | 网关或目标TLS失败 |
+| `UNSUPPORTED_ENCODING`、`INVALID_RESPONSE` | 编码或协议错误 |
+| `UNSUPPORTED_RESPONSE` | 不支持HTTP 101升级 |
+| `TIMEOUT`、`CANCELLED` | 本地请求停止，无自动重试 |
+
+错误可能没有状态／耗时，应保留未知。检测失败不能直接认定为额度、计费或地域问题。
+
+仅返回选定响应头。配置凭据从显示文本中过滤；敏感二进制／不透明值被隐藏并返回 `SENSITIVE_OUTPUT`。不保证任意目标内容不含其他秘密。拦截TLS的网关可能观察到目标请求头；不要用生产凭据打开调试日志。
+
+[代理产品](https://docs.nstdata.io/docs/proxy) · [PM Router](https://docs.nstdata.io/docs/proxy-manager)
+
+传输来自 `@nstdata-ai/proxy-checker/transport`；MCP负责工具校验、凭据过滤及输出上限，不启动Checker CLI或额外托管服务。

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@nstdata-ai/mcp-server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "MCP access to Nstdata web data capabilities",
+  "type": "module",
+  "main": "dist/server.js",
+  "types": "dist/server.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    }
+  },
+  "bin": {
+    "nstdata-mcp-server": "dist/stdio.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "README_zh.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "docs"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": "^22.18.0 || ^24.0.0"
+  },
+  "scripts": {
+    "build": "node --input-type=module -e \"import {rmSync} from 'node:fs'; rmSync('dist',{recursive:true,force:true});\" && tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "check:package": "node scripts/check-package.mjs",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "2.3.1",
+    "@nstdata-ai/crawl": "2.0.0",
+    "@nstdata-ai/proxy-checker": "1.2.0",
+    "zod": "4.6.7"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/client": "2.3.1",
+    "@modelcontextprotocol/core": "2.3.1",
+    "@types/node": "22.18.0",
+    "marked": "18.1.1",
+    "typescript": "5.9.3"
+  },
+  "keywords": [
+    "mcp",
+    "nstdata",
+    "crawl"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nstdata-ai/nstdata-mcp-server.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}