@nstdata-ai/mcp-server 1.0.1 → 1.0.2

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 1.0.2
+
+- Preserve bounded page summaries and storage references when a single crawl result row exceeds the output limit; separate continuation cursors from unread page results.
+- Describe reference inputs, offset units, page bounds and cursor recovery in tool schemas.
+- Default Proxy checks to `https://example.com/`, with an optional target override and no requests during startup.
+- Add credential-free `--help` and `--version` commands; reject unsupported arguments without printing their values.
+
 ## 1.0.1
 
 - Provide six Crawl tools and two HTTP/HTTPS Proxy tools in one local stdio server, with independently enabled modules.

package/CONTRIBUTING.md

@@ -13,10 +13,10 @@ For offline development, cache the complete locked dependency graph before runni
 
 ## Local package installation
 
-After the checks pass, run `npm pack` to build `nstdata-ai-mcp-server-1.0.1.tgz`. Install it from a separate application directory:
+After the checks pass, run `npm pack` to build `nstdata-ai-mcp-server-1.0.2.tgz`. Install it from a separate application directory:
 
 ```sh
-npm install --ignore-scripts /path/to/nstdata-ai-mcp-server-1.0.1.tgz
+npm install --ignore-scripts /path/to/nstdata-ai-mcp-server-1.0.2.tgz
 ```
 
 Configure the installed package using the README template; do not point clients at source files.
@@ -29,7 +29,7 @@ Verify license ownership, dependency availability, compatibility and maintainer
 
 ## Releases
 
-The `Publish npm` workflow runs only when manually dispatched from `main`, with the stable version in `package.json` and a full reviewed commit SHA. Checks produce one archive and its integrity manifest. The `npm-production` reviewer approves publication of those exact bytes. Published integrity, default installation and tool discovery must pass afterward.
+The `Publish npm` workflow runs only when manually dispatched from `main`, with the stable version in `package.json` and a full reviewed commit SHA. Checks produce one archive and its integrity manifest. The `npm-production` reviewer approves publication of those exact bytes. The workflow finishes when `npm publish` succeeds. Public availability may be delayed; registry integrity, installation and tool discovery are checked separately.
 
 Crawl SDK and Proxy Checker dependencies must be publicly available with the lock's exact integrity before remote CI or release. Configure [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/) for this repository, `release.yml` and `npm-production`, permitting `npm publish`. Require an environment reviewer, allow only `main` and disable administrator bypass. No npm token is needed.
 

package/README.md

@@ -22,6 +22,13 @@ Supports Node.js 22 (22.18 or later) and 24. The client template below can start
 npm install @nstdata-ai/mcp-server
 ```
 
+To inspect setup requirements or the installed version without credentials:
+
+```sh
+npx --yes @nstdata-ai/mcp-server --help
+npx --yes @nstdata-ai/mcp-server --version
+```
+
 ## Connect a client
 
 Add this entry to your client's MCP configuration and replace the Crawl token. Preserve other server entries. The client must be able to find Node.js and `npx` on PATH.
@@ -31,7 +38,7 @@ Add this entry to your client's MCP configuration and replace the Crawl token. P
   "mcpServers": {
     "nstdata": {
       "command": "npx",
-      "args": ["--yes", "@nstdata-ai/mcp-server@1.0.1"],
+      "args": ["--yes", "@nstdata-ai/mcp-server@1.0.2"],
       "env": {
         "NSTDATA_MODULES": "crawl",
         "NSTDATA_API_TOKEN": "YOUR_CRAWL_API_TOKEN"

package/README_zh.md

@@ -22,6 +22,13 @@
 npm install @nstdata-ai/mcp-server
 ```
 
+无需凭据即可查看配置要求和版本：
+
+```sh
+npx --yes @nstdata-ai/mcp-server --help
+npx --yes @nstdata-ai/mcp-server --version
+```
+
 ## 连接客户端
 
 在客户端 MCP 配置中添加以下条目并替换 Crawl Token，保留其他服务条目。客户端需要能够从 PATH 找到 Node.js 和 `npx`。
@@ -31,7 +38,7 @@ npm install @nstdata-ai/mcp-server
   "mcpServers": {
     "nstdata": {
       "command": "npx",
-      "args": ["--yes", "@nstdata-ai/mcp-server@1.0.1"],
+      "args": ["--yes", "@nstdata-ai/mcp-server@1.0.2"],
       "env": {
         "NSTDATA_MODULES": "crawl",
         "NSTDATA_API_TOKEN": "YOUR_CRAWL_API_TOKEN"

package/dist/config.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+export declare const DEFAULT_PROXY_CHECK_URL = "https://example.com/";
 declare const configuration: z.ZodObject<{
     apiToken: z.ZodOptional<z.ZodString>;
     baseURL: z.ZodURL;

package/dist/config.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { isAbsolute } from 'node:path';
+export const DEFAULT_PROXY_CHECK_URL = 'https://example.com/';
 const configuration = z.strictObject({
     apiToken: z.string().trim().min(1).optional(),
     baseURL: z.url().refine(value => {
@@ -43,8 +44,6 @@ const configuration = z.strictObject({
     if (config.modules.includes('proxy')) {
         if (!config.proxyURL)
             ctx.addIssue({ code: 'custom', path: ['proxyURL'], message: 'Required for proxy' });
-        if (!config.proxyCheckURL)
-            ctx.addIssue({ code: 'custom', path: ['proxyCheckURL'], message: 'Required for proxy' });
     }
 });
 const environmentVariables = {
@@ -73,7 +72,7 @@ function parseConfig(input, fromEnvironment) {
             throw new EnvironmentConfigError(fields);
         throw new Error(`Invalid configuration: ${fields.join(', ')}`);
     }
-    return result.data;
+    return { ...result.data, proxyCheckURL: result.data.proxyCheckURL ?? DEFAULT_PROXY_CHECK_URL };
 }
 export function validateConfig(input) {
     return parseConfig(input, false);

package/dist/modules/crawl-schema.js

@@ -5,10 +5,10 @@ const milliseconds = z.number().int().min(0).max(600000);
 export const httpURL = z.url().max(8192).refine(value => {
     const url = new URL(value);
     return ['http:', 'https:'].includes(url.protocol) && !url.username && !url.password;
-}, 'Use an HTTP(S) URL without embedded credentials');
+}, 'Use an HTTP(S) URL without embedded credentials').describe('Target HTTP(S) URL without embedded credentials. For a site crawl this is the single seed URL.');
 export const identifier = z.string().trim().min(1).max(256)
     .refine(value => value !== '.' && value !== '..', 'Task IDs must not be . or ..');
-export const formats = z.array(z.enum(['markdown', 'html', 'links', 'pdf', 'screenshot', 'rawData'])).min(1).max(6).default(['markdown']);
+export const formats = z.array(z.enum(['markdown', 'html', 'links', 'pdf', 'screenshot', 'rawData'])).min(1).max(6).default(['markdown']).describe('Requested output formats. Large results may contain storage references instead of inline content.');
 const action = z.discriminatedUnion('type', [
     z.strictObject({ type: z.literal('click'), selector, waitSelector: selector.optional() }),
     z.strictObject({ type: z.literal('wait'), milliseconds }),
@@ -34,4 +34,4 @@ export const scrapeOptions = z.strictObject({
     removeSelectors: z.array(selector).max(100).optional(),
     targetSelector: selector.optional(),
     timeout: z.number().int().min(1000).max(60000).optional(),
-}).default({});
+}).default({}).describe('Optional Crawl service settings. Set onlyMainContent=false when full-page navigation is needed for link discovery.');

package/dist/modules/crawl.js

@@ -6,7 +6,12 @@ import { serializeData, taskFailed, requireSubmissionId } from './crawl-result.j
 export function registerCrawlTools(server, client, config) {
     server.registerTool('nstdata_crawl_read_result', {
         description: 'Read a bounded chunk of a Crawl storage reference. Text offsets count Unicode code points; binary offsets count bytes. Each call downloads the reference again, within the response byte limit.',
-        inputSchema: z.strictObject({ ref: z.string().min(1).max(4096), format: z.enum(['markdown', 'html', 'pdf', 'screenshot', 'rawData']), offset: z.number().int().min(0).default(0), length: z.number().int().min(1).max(4000).default(2000) }),
+        inputSchema: z.strictObject({
+            ref: z.string().min(1).max(4096).describe('Copy the actual value of markdownRef, htmlRef, pdfRef, screenshotRef or rawDataRef into ref; do not use the output field name as an input key.'),
+            format: z.enum(['markdown', 'html', 'pdf', 'screenshot', 'rawData']).describe('Must match the reference field: markdownRef uses markdown, htmlRef uses html, and so on.'),
+            offset: z.number().int().min(0).default(0).describe('Start position: Unicode code points for markdown/html, bytes for binary formats. Use the preceding read result\'s nextOffset to continue.'),
+            length: z.number().int().min(1).max(4000).default(2000).describe('Maximum Unicode code points for markdown/html, or bytes for binary formats, in this chunk. Reduce it if the chunk exceeds the output limit.'),
+        }),
         annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
     }, async (args, ctx) => guard(ctx, config, async (options) => {
         const bytes = Buffer.from(await client.readStorage(args.ref, options));
@@ -23,7 +28,14 @@ export function registerCrawlTools(server, client, config) {
     }));
     server.registerTool('nstdata_crawl_start', {
         description: 'Start a bounded site crawl and return its task ID immediately.',
-        inputSchema: z.strictObject({ url: httpURL, formats, options: scrapeOptions, maxPages: z.number().int().min(1).max(config.maxCrawlPages).default(config.maxCrawlPages), maxDepth: z.number().int().min(0).max(100).optional(), includeUrls: z.array(z.string().max(8192)).max(100).optional(), excludeUrls: z.array(z.string().max(8192)).max(100).optional(), ignoreQuery: z.boolean().optional() }),
+        inputSchema: z.strictObject({
+            url: httpURL, formats, options: scrapeOptions,
+            maxPages: z.number().int().min(1).max(config.maxCrawlPages).default(config.maxCrawlPages).describe('Page-count upper bound, not a guarantee of that many pages. Check actual returned URLs and per-page results.'),
+            maxDepth: z.number().int().min(0).max(100).optional().describe('Optional service-side link-discovery depth limit; depth counting follows the Crawl service.'),
+            includeUrls: z.array(z.string().max(8192)).max(100).optional().describe('Optional service-side include filters for discovered links. These are not extra seed URLs or a batch scrape list.'),
+            excludeUrls: z.array(z.string().max(8192)).max(100).optional().describe('Optional service-side exclude filters for discovered links.'),
+            ignoreQuery: z.boolean().optional().describe('Optional service-side query-string handling setting.'),
+        }),
         annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
     }, async (args, ctx) => guard(ctx, config, async (options) => {
         const { options: advanced, ...request } = args;
@@ -33,15 +45,20 @@ export function registerCrawlTools(server, client, config) {
     }, 'task'));
     server.registerTool('nstdata_crawl_status', {
         description: 'Read aggregate crawl progress without polling.',
-        inputSchema: z.strictObject({ crawlId: identifier }),
+        inputSchema: z.strictObject({ crawlId: identifier.describe('Actual id returned by nstdata_crawl_start; reuse the existing task instead of submitting another crawl.') }),
         annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
     }, async (args, ctx) => guard(ctx, config, async (options) => {
         const output = { ...await client.getCrawlStatus(args.crawlId, options), crawlId: args.crawlId };
         return { content: [{ type: 'text', text: JSON.stringify(output) }], structuredContent: { ...output }, isError: taskFailed(output) };
     }));
     server.registerTool('nstdata_crawl_pages', {
-        description: 'Read one page of crawl results and return actual cursors and storage references. Does not download referenced files.',
-        inputSchema: z.strictObject({ crawlId: identifier, afterCursor: z.string().min(1).max(8192).optional(), beforeCursor: z.string().min(1).max(8192).optional(), limit: z.number().int().min(1).max(100).default(10) }).refine(args => !(args.afterCursor && args.beforeCursor)),
+        description: 'Read one page of crawl results without downloading referenced files. On OUTPUT_LIMIT, retry the same input cursor with a smaller limit. A single-row error may retain recovery.page references; handle that page before using recovery.continuation.',
+        inputSchema: z.strictObject({
+            crawlId: identifier.describe('Actual id of the existing site crawl.'),
+            afterCursor: z.string().min(1).max(8192).optional().describe('Copy nextCursor from a successful page read. On OUTPUT_LIMIT, keep the original input cursor. Only use recovery.continuation.nextCursor after handling recovery.page. Mutually exclusive with beforeCursor.'),
+            beforeCursor: z.string().min(1).max(8192).optional().describe('Copy prevCursor from a successful read, or recovery.continuation.prevCursor after handling recovery.page. On OUTPUT_LIMIT keep the original input cursor; do not combine with afterCursor.'),
+            limit: z.number().int().min(1).max(100).default(10).describe('Maximum rows in this response. Reduce down to 1 on OUTPUT_LIMIT; a single row may still exceed the output cap.'),
+        }).refine(args => !(args.afterCursor && args.beforeCursor)),
         annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
     }, async ({ crawlId, ...pageOptions }, ctx) => guard(ctx, config, async (options) => {
         const result = await client.listCrawlPages(crawlId, pageOptions, options);
@@ -54,7 +71,7 @@ export function registerCrawlTools(server, client, config) {
         description: 'Retrieve a webpage through Nstdata Crawl. Creates a potentially billable scrape task.',
         inputSchema: z.strictObject({
             url: httpURL, formats, options: scrapeOptions,
-            mode: z.enum(['sync', 'async']).default('sync'),
+            mode: z.enum(['sync', 'async']).default('sync').describe('sync waits for the single-page response; async returns a task id to resume with nstdata_crawl_scrape_result. Neither mode retries submission.'),
         }),
         annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
     }, async (args, ctx) => guard(ctx, config, async (options) => {
@@ -71,7 +88,7 @@ export function registerCrawlTools(server, client, config) {
     }, 'task'));
     server.registerTool('nstdata_crawl_scrape_result', {
         description: 'Resume a submitted single-page task. Processing is not completion; a failed or expired task is reported explicitly.',
-        inputSchema: z.strictObject({ taskId: identifier }),
+        inputSchema: z.strictObject({ taskId: identifier.describe('Actual id returned by an existing single-page submission; not a site crawl id or a storage reference.') }),
         annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
     }, async (args, ctx) => guard(ctx, config, async (options) => {
         const result = await client.getScrapeTaskResult(args.taskId, options);

package/dist/modules/proxy.js

@@ -27,10 +27,10 @@ export function registerProxyTools(server, config) {
     server.registerTool('nstdata_proxy_fetch', {
         description: 'Read an HTTP(S) page through the configured proxy. Does not follow redirects or retry; may consume billable traffic.',
         inputSchema: z.strictObject({
-            url: z.url().max(8192).refine(value => { const url = new URL(value); return ['http:', 'https:'].includes(url.protocol) && !url.username && !url.password; }),
-            method: z.enum(['GET', 'HEAD']).default('GET'),
-            format: z.enum(['text', 'base64']).default('text'),
-            headers: targetHeaders.optional(),
+            url: z.url().max(8192).refine(value => { const url = new URL(value); return ['http:', 'https:'].includes(url.protocol) && !url.username && !url.password; }).describe('HTTP(S) target accessed through the configured proxy; no embedded credentials.'),
+            method: z.enum(['GET', 'HEAD']).default('GET').describe('GET returns content; HEAD requests response headers without a body.'),
+            format: z.enum(['text', 'base64']).default('text').describe('text requires UTF-8; base64 preserves binary bytes.'),
+            headers: targetHeaders.optional().describe('Optional target request headers. Send Authorization or Cookie only to trusted targets; proxy and connection headers are reserved.'),
         }),
         annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
     }, async (args, ctx) => guard(ctx, config, async (options) => {
@@ -44,7 +44,7 @@ export function registerProxyTools(server, config) {
             isError: response.statusCode < 200 || response.statusCode >= 300 };
     }));
     server.registerTool('nstdata_proxy_check', {
-        description: 'Check the operator-configured target through the proxy, once.',
+        description: 'Check the proxy once against NSTDATA_PROXY_CHECK_URL, or https://example.com/ by default. Returns observedIp only when the target echoes a valid IP. Startup does not run this check.',
         inputSchema: z.strictObject({}),
         annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
     }, async (_args, ctx) => guard(ctx, config, async (options) => {

package/dist/shared/output.js

@@ -50,21 +50,54 @@ export function boundResult(result, config) {
         return { ...result, content: [{ type: 'text', text }], structuredContent: data };
     }
     const recovery = {};
-    const error = { code: 'OUTPUT_LIMIT', message: 'Result exceeds the local output limit. Reduce source content or use a supported smaller page/chunk/reference. Do not automatically repeat a task submission.', recovery };
+    const pageList = Array.isArray(data.data);
+    const error = { code: 'OUTPUT_LIMIT', message: pageList
+            ? 'Page output exceeds the local limit. Retry with the same input cursor and a smaller limit. If recovery.page has the required references, read them before using recovery.continuation, which skips that page. Do not automatically repeat a task submission.'
+            : 'Result exceeds the local output limit. Reduce source content or use a supported smaller page/chunk/reference. Do not automatically repeat a task submission.', recovery };
     const add = (key, value) => {
-        if (typeof value !== 'string' && typeof value !== 'number' && typeof value !== 'boolean')
-            return;
+        if (value === undefined)
+            return false;
         const candidate = { ...recovery, [key]: value };
-        if (JSON.stringify({ error: { ...error, recovery: candidate } }).length <= config.maxOutputChars)
-            Object.assign(recovery, candidate);
+        if (JSON.stringify({ error: { ...error, recovery: candidate } }).length > config.maxOutputChars)
+            return false;
+        Object.assign(recovery, candidate);
+        return true;
     };
-    for (const key of ['statusCode', 'id', 'taskId', 'crawlId', 'ref', 'format', 'offset', 'nextCursor', 'prevCursor'])
-        add(key, data[key]);
-    if (data.data && typeof data.data === 'object' && !Array.isArray(data.data)) {
+    const scalar = (value) => typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean';
+    for (const key of ['statusCode', 'id', 'taskId', 'crawlId', 'ref', 'format', 'offset']) {
+        if (scalar(data[key]))
+            add(key, data[key]);
+    }
+    if (Array.isArray(data.data)) {
+        if (data.data.length === 1 && data.data[0] && typeof data.data[0] === 'object') {
+            const page = data.data[0];
+            const summary = {};
+            for (const key of ['id', 'taskId', 'url', 'status', 'success', 'errorCode']) {
+                if (scalar(page[key]) && add('page', { ...summary, [key]: page[key] }))
+                    summary[key] = page[key];
+            }
+            const content = page.data;
+            const references = {};
+            for (const key of ['markdownRef', 'htmlRef', 'pdfRef', 'screenshotRef', 'rawDataRef']) {
+                if (typeof content?.[key] === 'string' && content[key] && add('page', { ...summary, data: { ...references, [key]: content[key] } }))
+                    references[key] = content[key];
+            }
+            if (Object.keys(references).length) {
+                if (typeof content?.truncated === 'boolean')
+                    add('page', { ...summary, data: { ...references, truncated: content.truncated } });
+                const continuation = Object.fromEntries(['nextCursor', 'prevCursor']
+                    .filter(key => typeof data[key] === 'string' && data[key]).map(key => [key, data[key]]));
+                if (Object.keys(continuation).length)
+                    add('continuation', continuation);
+            }
+        }
+    }
+    else if (data.data && typeof data.data === 'object') {
         const page = data.data;
-        for (const key of ['markdownRef', 'htmlRef', 'pdfRef', 'screenshotRef', 'rawDataRef'])
-            add(key, page[key]);
-        add('truncated', page.truncated);
+        for (const key of ['markdownRef', 'htmlRef', 'pdfRef', 'screenshotRef', 'rawDataRef', 'truncated']) {
+            if (scalar(page[key]))
+                add(key, page[key]);
+        }
     }
     const output = { error };
     return { isError: true, content: [{ type: 'text', text: JSON.stringify(output) }], structuredContent: output };

package/dist/stdio.js

@@ -1,35 +1,59 @@
 #!/usr/bin/env node
 import { serveStdio } from '@modelcontextprotocol/server/stdio';
 import { ProxyTransportError } from '@nstdata-ai/proxy-checker/transport';
+import { createRequire } from 'node:module';
 import { createServer, loadConfig } from './server.js';
-import { EnvironmentConfigError } from './config.js';
-try {
-    const config = loadConfig();
-    // Validate module resources before the lazy stdio negotiation receives input.
-    let initialServer;
+import { DEFAULT_PROXY_CHECK_URL, EnvironmentConfigError } from './config.js';
+const args = process.argv.slice(2);
+if (args.length === 1 && args[0] === '--help') {
+    console.log(`Usage: nstdata-mcp-server [--help | --version]
+
+With no arguments, start a local stdio MCP server.
+Set environment variables in your MCP client configuration:
+  NSTDATA_MODULES          crawl (default), proxy, or crawl,proxy
+  NSTDATA_API_TOKEN        Required when Crawl is enabled
+  NSTDATA_PROXY_URL        Required when Proxy is enabled; HTTP(S) gateway URL
+  NSTDATA_PROXY_CHECK_URL  Optional check target; default ${DEFAULT_PROXY_CHECK_URL}
+
+Startup does not submit tasks or check the proxy. Calls may consume credits or traffic.
+Configuration reference: https://github.com/nstdata-ai/nstdata-mcp-server#readme`);
+}
+else if (args.length === 1 && args[0] === '--version') {
+    const { version } = createRequire(import.meta.url)('../package.json');
+    console.log(version);
+}
+else if (args.length) {
+    console.error('Unsupported arguments. Use --help for usage.');
+    process.exitCode = 1;
+}
+else
     try {
-        initialServer = createServer(config);
+        const config = loadConfig();
+        // Validate module resources before the lazy stdio negotiation receives input.
+        let initialServer;
+        try {
+            initialServer = createServer(config);
+        }
+        catch (error) {
+            if (config.proxyCAFile && error instanceof ProxyTransportError && error.code === 'INVALID_CONFIG') {
+                throw new EnvironmentConfigError(['proxyCAFile']);
+            }
+            throw error;
+        }
+        const handle = serveStdio(() => {
+            const server = initialServer ?? createServer(config);
+            initialServer = undefined;
+            return server;
+        }, {
+            onerror: () => { console.error('MCP protocol error.'); },
+        });
+        const shutdown = () => { void handle.close().catch(() => { process.exitCode = 1; }); };
+        process.once('SIGINT', shutdown);
+        process.once('SIGTERM', shutdown);
     }
     catch (error) {
-        if (config.proxyCAFile && error instanceof ProxyTransportError && error.code === 'INVALID_CONFIG') {
-            throw new EnvironmentConfigError(['proxyCAFile']);
-        }
-        throw error;
+        console.error(error instanceof EnvironmentConfigError
+            ? error.message
+            : 'Unable to start Nstdata MCP. Check the documented environment configuration.');
+        process.exitCode = 1;
     }
-    const handle = serveStdio(() => {
-        const server = initialServer ?? createServer(config);
-        initialServer = undefined;
-        return server;
-    }, {
-        onerror: () => { console.error('MCP protocol error.'); },
-    });
-    const shutdown = () => { void handle.close().catch(() => { process.exitCode = 1; }); };
-    process.once('SIGINT', shutdown);
-    process.once('SIGTERM', shutdown);
-}
-catch (error) {
-    console.error(error instanceof EnvironmentConfigError
-        ? error.message
-        : 'Unable to start Nstdata MCP. Check the documented environment configuration.');
-    process.exitCode = 1;
-}

package/docs/mcp.md

@@ -94,6 +94,8 @@ Use paths to select discovered links; submit the seed separately as `url`. Addin
 
 Page inputs accept `limit` (1–100, default 10) and one of `afterCursor`/`beforeCursor`. Copy `nextCursor` or `prevCursor` unchanged. An empty page with a cursor is not the end; stop on repeated cursors or the caller's page/call limit. Aggregate completion does not mean every page succeeded. If a page list exceeds the output limit, repeat that read from the same input cursor with a smaller `limit` (down to 1), then continue using the successful response's cursor. Advancing past a withheld page would skip unread results.
 
+If one row still exceeds the cap, `error.recovery.page` retains its identity, status and available storage references when they fit the output budget. It is a summary, not the full row. Read the required references before using `error.recovery.continuation.nextCursor` or `prevCursor` to move past that row. Those cursors are omitted for multi-row errors or when no reference fits. If the summary cannot satisfy the request, stop and report the limit; do not skip the page or submit another crawl.
+
 ### Read a reference
 
 Pass the value of `data.markdownRef` as **`ref`**, with `format: "markdown"`:

package/docs/mcp_zh.md

@@ -96,6 +96,8 @@ Proxy 专用变量见 [proxy_zh.md](proxy_zh.md)。未启用的模块不要求
 
 列表触发 `OUTPUT_LIMIT` 时，保持相同输入游标，减小 `limit` 至最小1后重新读取该页，再使用成功结果中的游标继续。不能跳过被隐藏的页面结果。
 
+若单条页面仍超限，`error.recovery.page` 会在输出预算允许时保留该行标识、状态及可用存储引用；它是摘要，不是完整页面结果。先读取所需引用，再用 `error.recovery.continuation.nextCursor` 或 `prevCursor` 移至该行之后或之前。多行超限或没有引用能放入预算时，不返回这些继续游标。摘要不能满足需求时，应停止并说明限制，不得跳过页面或重新提交整站任务。
+
 ### 引用读取
 
 把 `data.markdownRef` 的原值传给 **`ref`**，不是把 `markdownRef` 当作输入字段名：

package/docs/proxy.md

@@ -11,25 +11,26 @@ Proxy-only requires no Crawl token. Use this client entry and replace the genera
   "mcpServers": {
     "nstdata": {
       "command": "npx",
-      "args": ["--yes", "@nstdata-ai/mcp-server@1.0.1"],
+      "args": ["--yes", "@nstdata-ai/mcp-server@1.0.2"],
       "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_PROXY_URL": "http://PROXY_USER:PROXY_PASSWORD@PROXY_HOST:PROXY_PORT"
       }
     }
   }
 }
 ```
 
-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.
+For both modules, set `NSTDATA_MODULES=crawl,proxy` and add `NSTDATA_API_TOKEN` in this same entry. Startup sends no probe; only an explicit `nstdata_proxy_check` call accesses the check target.
 
 | 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_CHECK_URL` | Optional HTTP/HTTPS check target; defaults to `https://example.com/` |
 | `NSTDATA_PROXY_CA_FILE` | Optional absolute path to a PEM CA bundle for Proxy TLS only |
 
+The default target checks connectivity and does not echo the exit IP. To observe that IP, set `NSTDATA_PROXY_CHECK_URL` to `https://api.nstdata.io/api/v2/public/utility/client-ip` or an IP echo target you trust. The example domain offers no monitoring availability guarantee.
+
 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.

package/docs/proxy_zh.md

@@ -11,11 +11,10 @@
   "mcpServers": {
     "nstdata": {
       "command": "npx",
-      "args": ["--yes", "@nstdata-ai/mcp-server@1.0.1"],
+      "args": ["--yes", "@nstdata-ai/mcp-server@1.0.2"],
       "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_PROXY_URL": "http://PROXY_USER:PROXY_PASSWORD@PROXY_HOST:PROXY_PORT"
       }
     }
   }
@@ -23,14 +22,16 @@
 
 ```
 
-同时启用两模块时，在同一条目设置 `NSTDATA_MODULES=crawl,proxy` 并补充 `NSTDATA_API_TOKEN`。检测地址由操作者选择；上述 Nstdata 回显接口返回该次请求被观测到的 IP。
+同时启用两模块时，在同一条目设置 `NSTDATA_MODULES=crawl,proxy` 并补充 `NSTDATA_API_TOKEN`。启动不发检测请求；调用 `nstdata_proxy_check` 时才访问检测目标。
 
 | 变量 | 用途 |
 |---|---|
 | `NSTDATA_PROXY_URL` | 必填HTTP／HTTPS网关URL；需要时包含编码后的用户名密码 |
-| `NSTDATA_PROXY_CHECK_URL` | `nstdata_proxy_check` 的必填HTTP／HTTPS目标 |
+| `NSTDATA_PROXY_CHECK_URL` | 可选HTTP／HTTPS检测目标，默认为 `https://example.com/` |
 | `NSTDATA_PROXY_CA_FILE` | 可选PEM CA文件绝对路径，仅用于Proxy TLS |
 
+默认目标用于连通性检测，不返回出口 IP。需要出口 IP 时，将 `NSTDATA_PROXY_CHECK_URL` 设为 `https://api.nstdata.io/api/v2/public/utility/client-ip` 或你信任的 IP 回显目标。示例域名不提供监控可用性保证。
+
 使用完整的平台或PM Router连接，保留通道／地域／会话／任务的用户名语法。网关和目标各自可为HTTP或HTTPS；HTTPS目标使用CONNECT。不支持SOCKS代理。
 
 CA文件必须为普通文件、最多1 MiB，并包含可解析证书。信任追加到Node默认CA，网关／目标主机名校验保持开启，不改变Crawl信任设置。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nstdata-ai/mcp-server",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "MCP access to Nstdata web data capabilities",
   "type": "module",
   "main": "dist/server.js",