draftgo-cli 3.0.41 → 3.0.43

package/README.md

@@ -48,6 +48,7 @@ DraftGo Skill 不能被 MCP 替代。根 `SKILL.md` 会在 Skill 触发时自动
 ```
 
 `context` 先验证并逐字提取当前 CLI 随包 Reference 的固定任务章节，再用同一 MCP 会话并行查询项目、资源、API 和 `db_meta` 数据结构；它不做摘要，也不限制后续 MCP 调用。输出中的 `reference_bundle` 会报告 CLI bundle 与项目已安装 Skill 的版本及同步状态，不同步时先运行 `draftgo update`。页面或导航任务使用 `frontend`，数据、自定义服务、AIHub、正文和项目清点分别可用 `data`、`custom-service`、`aihub`、`content`、`project`。`mcp test` 是连接诊断，不是每次资源查询的前置步骤。
+当前 context JSON 使用 `schema_version: "1.1"`；`live.resources` 和 `live.api` 以带来源的 `pages` 序列保留批量原始响应，`live.data_structures` 保留 db_meta 的 registry、describe 契约及完整分页读取结果。
 
 只回答无需实时状态的本地规则问题，或需要 context 路由之外的专项资料时，Agent 继续按根 Skill 表格手工补读。静态资源须先区分：平台内置目录由 `frontend.md` 说明，指定页面依赖经 MCP 定位、checkout 后本地搜索，服务器全量文件不能凭现有 Skill、MCP 摘要或 checkout 声称已枚举。
 
@@ -69,6 +70,8 @@ draftgo connect codex        # 输入 server 和 SAT，验证 MCP，并配置 Co
 draftgo connect codex --server https://draftgo.example --token "$DRAFTGO_SAT"
 ```
 
+`--server` 始终表示 DraftGo 基础地址。直接连接 MCP endpoint 时使用 `--mcp-url https://draftgo.example/mcp`；CLI 会显式保存 `mcp_url`，若未同时传 `--server`，则从标准 `/mcp` 后缀推导基础地址，避免猜测已有 base URL 的语义。
+
 `connect` 会先验证 SAT、MCP `initialize`、`tools/list` 和关键 `tools/call`，成功后写入项目私有配置 `.draftgo/config.json`，并尝试为指定或自动检测到的宿主执行 MCP setup。它不会 pull 页面、导航、文档或任何其他业务资源。
 
 远端暂不可用时，只有显式传入 `--allow-offline` 才会保存配置；恢复后运行 `draftgo mcp test`。使用 `--no-mcp-setup` 可跳过宿主配置。
@@ -89,7 +92,7 @@ SAT 只从 `.draftgo/config.json` 读取。宿主 MCP 配置、命令输出和
 ```bash
 draftgo mcp setup [target...]   # 写入或合并项目级 MCP 配置
 draftgo mcp status [target...]  # 检查配置是否存在且不含敏感连接参数
-draftgo mcp test                # 验证 initialize、tools/list、关键 tools/call
+draftgo mcp test                # 验证 initialize、tools/list、项目/正文/API 三条调用路径
 draftgo mcp serve               # 启动 stdio -> 远端 Streamable HTTP bridge
 ```
 
@@ -198,7 +201,7 @@ draftgo changelog add "完成文档管理系统及角色权限"
 | 命令 | 说明 |
 |---|---|
 | `draftgo context --task <task> --output json` | 精确读取任务 Reference 章节，并复用一个 MCP 会话并行查询项目、资源、API 和数据结构；保留原始结果及来源。 |
-| `draftgo map` | 通过 MCP 读取远端项目概览和资源列表，再叠加本地 checkout 状态。 |
+| `draftgo map` | 并行读取 pages、navigations、docs/articles 元数据，再叠加本地 checkout 状态；`--type` 可限制一种类型。 |
 | `draftgo checkout <pages|nav|docs> <id...>` | 下载完整正文和 base，校验 hash 后原子落盘；`--force` 可显式覆盖已修改的本地正文。 |
 | `draftgo check` | 只检查 checkout manifest、worktree 文件、base/hash、扩展名、HTML 结构和已 checkout 导航引用。 |
 | `draftgo diff <pages|nav|docs> <id>` | 显示 checkout base 与当前本地正文的差异。 |
@@ -338,6 +341,7 @@ checkout 会通过 MCP 获取元数据和专用下载地址，流式写入临时
 - `--project <dir>`：操作指定项目目录，默认当前目录。
 - `--output json`：为 context、map、check、checkout、commit、diff、conflicts、conflict、api 或 delete 输出 JSON。
 - `--task <task>`：选择 context 路由；支持 frontend、data、custom-service、aihub、content、project。
+- `--type <type>`：限制 `map` 查询一种正文资源类型；支持 pages、nav/navigations、docs/articles 及其别名。
 - `--strict`：check/deploy/auto-push 将 warnings 视为失败。
 - `--force`：init 覆盖已有 Skill；checkout 显式覆盖已修改的本地正文。update 始终刷新目标 Skill。
 - `--purge`：uninstall 时同时删除整个 `.draftgo/` 运行时目录。
@@ -345,6 +349,7 @@ checkout 会通过 MCP 获取元数据和专用下载地址，流式写入临时
 - `--connect` / `--local-dev` / `--no-setup`：控制 init 安装 Skill 后的基座处理流程。
 - `--target <name,...>`：为 MCP setup/status 指定一个或多个宿主。
 - `--server <url>` / `--token <sat>`：非交互 connect；不传时安全提示输入。
+- `--mcp-url <url>`：为 connect 显式指定完整 MCP endpoint；标准 `/mcp` 可自动推导基础地址，自定义路径需同时传 `--server`。
 - `--allow-offline` / `--no-mcp-setup`：允许 connect 在 MCP 暂不可用时保存，或跳过宿主配置。
 - `--yes`：跳过支持该选项的交互确认。
 - `--mobile-check auto|always|never`：控制 `verify-ui` 是否执行。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "draftgo-cli",
-  "version": "3.0.41",
+  "version": "3.0.43",
   "description": "Install and manage the DraftGo skill across AI coding agents (Claude Code, Codex, Cursor, Windsurf, Antigravity, Copilot, Gemini, Kiro).",
   "bin": {
     "draftgo": "bin/draftgo.js"

package/resources/skill/manifest.json

@@ -2,7 +2,7 @@
   "schema_version": "1.0",
   "id": "draftgo",
   "name": "DraftGo 开发助手",
-  "version": "3.0.41",
+  "version": "3.0.43",
   "entry": "SKILL.md",
   "description": "以 context 聚合编排、Skill/reference 原文、MCP 实时发现、长正文 checkout/commit、统一验证和完成日志为边界的 DraftGo 工作流。",
   "license": "MIT",

package/resources/skill/references/mcp.md

@@ -38,10 +38,10 @@ draftgo mcp serve
 - `context` 是开发任务的一次性准备入口；不保存业务镜像，不传输完整正文。
 - `setup` 写入项目级宿主配置，只替换 `draftgo` MCP 条目并保留其他配置。
 - `status` 检查配置是否存在、格式是否有效，以及是否误写了凭据或远端 URL。
-- `test` 从 `.draftgo/config.json` 读取连接，验证 initialize、tools/list 和关键 tools/call。
+- `test` 从 `.draftgo/config.json` 读取连接，验证 initialize、tools/list、三类正文 resource_list，以及 db_meta 的 api_search、api_describe 和只读 api_call。
 - `serve` 启动 stdio bridge，把宿主请求代理到当前项目配置的远端 Streamable HTTP `/mcp`。
 
-`draftgo connect` 保存并验证 server/SAT、探测 `/mcp` 和关键工具，并可提示宿主 setup；它不下载业务资源，
+`draftgo connect` 保存并验证 server/SAT、探测 `/mcp` 和关键工具，并可提示宿主 setup；`--server` 表示基础地址，完整 MCP endpoint 使用 `--mcp-url` 显式传入。它不下载业务资源，
 也不创建 pages、navigation、docs、db_meta 等本地镜像。底座仍在开发或暂不可达时，报告诊断结果即可，
 不得回退到 `pull --all`。
 

package/src/cli.js

@@ -7,6 +7,7 @@ const VALUE_FLAGS = new Set([
   'project',
   'target',
   'server',
+  'mcp-url',
   'token',
   'output',
   'url',

package/src/commands/connect.js

@@ -2,9 +2,10 @@
 
 const log = require('../logger');
 const { ask, askPassword } = require('../prompt');
-const { normalizeServer, writeProjectConfig } = require('../projectConfig');
+const { normalizeConnection, normalizeServer, writeProjectConfig } = require('../projectConfig');
 const { testConnection } = require('../mcp/client');
 const { redactText } = require('../mcp/protocol');
+const { parseTimeout } = require('../timeout');
 
 async function promptServer(defaultValue) {
   while (true) {
@@ -28,19 +29,32 @@ async function promptToken() {
 
 async function connect(projectDir, positional, flags = {}) {
   log.title('draftgo connect');
-  const server = flags.server ? normalizeServer(flags.server) : await promptServer('https://');
+  const endpointConnection = flags['mcp-url']
+    ? normalizeConnection(flags['mcp-url'])
+    : null;
+  if (endpointConnection && !endpointConnection.server && !flags.server) {
+    throw new Error('--server is required when --mcp-url does not use the standard /mcp path.');
+  }
+  const connection = {
+    server: flags.server
+      ? normalizeServer(flags.server)
+      : endpointConnection && endpointConnection.server || await promptServer('https://'),
+    mcp_url: endpointConnection && endpointConnection.mcp_url || '',
+  };
+  const server = connection.server;
   const token = flags.token ? String(flags.token).trim() : await promptToken();
   if (!token) {
     log.err('A non-empty SAT is required.');
     return 1;
   }
+  const timeoutMs = parseTimeout(flags.timeout);
 
   log.step('Validating SAT and DraftGo MCP capabilities...');
   try {
-    const diagnostic = await testConnection({ server, token }, {
-      timeoutMs: flags.timeout ? Number(flags.timeout) : undefined,
+    const diagnostic = await testConnection({ ...connection, server, token }, {
+      timeoutMs,
     });
-    log.ok(`MCP ready (${diagnostic.tools.length} tools; tested ${diagnostic.testedTool}).`);
+    log.ok(`MCP ready (${diagnostic.tools.length} tools; tested ${diagnostic.testedCalls.join(', ')}).`);
   } catch (error) {
     const message = redactText(error && error.message ? error.message : error, [token]);
     if (!flags['allow-offline']) {
@@ -52,7 +66,7 @@ async function connect(projectDir, positional, flags = {}) {
     log.warn('Continuing only because --allow-offline was explicitly supplied.');
   }
 
-  const configFile = writeProjectConfig(projectDir, server, token);
+  const configFile = writeProjectConfig(projectDir, server, token, { mcp_url: connection.mcp_url });
   log.ok(`Project configuration written: ${configFile}`);
 
   if (!flags['no-mcp-setup']) {
@@ -66,6 +80,7 @@ async function connect(projectDir, positional, flags = {}) {
 
   log.title('Connected');
   log.plain(`  server: ${server}`);
+  if (connection.mcp_url) log.plain(`  mcp endpoint: ${connection.mcp_url}`);
   log.plain(`  config: ${configFile}`);
   log.dim('  No DraftGo business resources were downloaded. Use MCP discovery or checkout long content explicitly.');
   return 0;

package/src/commands/context.js

@@ -2,21 +2,7 @@
 
 const log = require('../logger');
 const { collectContext, TASK_PROFILES } = require('../context');
-
-const MAX_TIMEOUT_MS = 2_147_483_647;
-
-function parseTimeout(value) {
-  if (value == null) return undefined;
-  const text = String(value).trim();
-  if (!/^\d+$/.test(text)) {
-    throw new TypeError('--timeout must be a positive integer in milliseconds.');
-  }
-  const timeoutMs = Number(text);
-  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > MAX_TIMEOUT_MS) {
-    throw new TypeError(`--timeout must be between 1 and ${MAX_TIMEOUT_MS} milliseconds.`);
-  }
-  return timeoutMs;
-}
+const { parseTimeout } = require('../timeout');
 
 function printUsage() {
   log.err('Usage: draftgo context --task <task> --output json');

package/src/commands/help.js

@@ -34,7 +34,7 @@ Usage:
                                     downloads DraftGo business resources.
   draftgo mcp setup [<target>...]  Merge project-level stdio MCP configuration.
   draftgo mcp status [<target>...] Check host configuration and secret safety.
-  draftgo mcp test                 Test initialize, tools/list, and tools/call.
+  draftgo mcp test                 Test project, resource, and API MCP calls.
   draftgo mcp serve                Bridge local stdio to the remote /mcp endpoint.
 
   draftgo context --task <task>    Read exact task Reference sections, then reuse
@@ -88,6 +88,8 @@ Important flags:
   --project <dir>          Operate on <dir> instead of the current directory.
   --target <name,...>      Select one or more MCP setup/status targets.
   --server <url>           (connect) DraftGo base URL.
+  --mcp-url <url>          (connect) Explicit endpoint; standard /mcp derives the
+                           base URL; custom paths also need --server.
   --token <sat>            (connect) SAT for non-interactive use.
   --timeout <ms>           (connect/mcp test/context) Network timeout.
   --allow-offline          (connect) Save only after explicitly accepting a
@@ -102,6 +104,7 @@ Important flags:
   --output json            Print machine-readable output where supported.
   --task <task>            (context) frontend | data | custom-service | aihub |
                            content | project.
+  --type <type>            (map) pages | nav/navigations | docs/articles.
   --strict                 Treat check warnings as failures.
   --yes                    Skip supported confirmation prompts.
   --operation-id <id>      (delete) Select an operation explicitly.

package/src/commands/map.js

@@ -6,7 +6,16 @@ const log = require('../logger');
 const { loadProjectConfig } = require('../projectConfig');
 const { loadManifest, absolutePath } = require('../worktree/manifest');
 const { hashFile } = require('../worktree/streams');
+const { canonicalResourceType } = require('../worktree/types');
 const { TOOL_NAMES, openToolSession, callStructured } = require('../mcp/tools');
+const { allWithAbort } = require('../mcp/parallel');
+
+const REMOTE_RESOURCE_TYPES = Object.freeze({
+  pages: 'pages',
+  navigations: 'navigations',
+  docs: 'docs/articles',
+});
+const DEFAULT_REMOTE_RESOURCE_TYPES = Object.freeze(Object.values(REMOTE_RESOURCE_TYPES));
 
 function itemsFrom(value) {
   if (Array.isArray(value)) return value;
@@ -18,26 +27,59 @@ function itemsFrom(value) {
 }
 
 function nextCursor(value) {
-  return value && (value.next_cursor || value.nextCursor || value.cursor && value.has_more && value.cursor);
+  if (!value || typeof value !== 'object') return null;
+  if (Object.prototype.hasOwnProperty.call(value, 'next_cursor')) return value.next_cursor;
+  if (Object.prototype.hasOwnProperty.call(value, 'nextCursor')) return value.nextCursor;
+  return (value.has_more === true || value.hasMore === true)
+    && Object.prototype.hasOwnProperty.call(value, 'cursor')
+    ? value.cursor
+    : null;
+}
+
+function claimsMorePages(value) {
+  return !!value && typeof value === 'object'
+    && (value.has_more === true || value.hasMore === true);
+}
+
+function normalizeMapResourceType(value) {
+  return REMOTE_RESOURCE_TYPES[canonicalResourceType(value)];
 }
 
-async function listRemoteResources(session, flags) {
+function requestedResourceTypes(flags = {}) {
+  return flags.type == null
+    ? DEFAULT_REMOTE_RESOURCE_TYPES
+    : [normalizeMapResourceType(flags.type)];
+}
+
+async function listRemoteResourceType(session, resourceType, options = {}) {
   const resources = [];
   const seen = new Set();
   let cursor = null;
   for (let page = 0; page < 100; page += 1) {
-    const args = {};
-    if (cursor) args.cursor = cursor;
-    if (flags.type) args.resource_type = String(flags.type);
-    const payload = await callStructured(session, TOOL_NAMES.resourceList, args);
+    const args = { resource_type: resourceType, limit: 100 };
+    if (cursor != null && cursor !== '') args.cursor = cursor;
+    const payload = await callStructured(session, TOOL_NAMES.resourceList, args, options);
     resources.push(...itemsFrom(payload));
     cursor = nextCursor(payload);
-    if (!cursor) break;
-    if (seen.has(cursor)) throw new Error('DraftGo resource_list repeated a cursor.');
-    seen.add(cursor);
+    if (cursor == null || cursor === '') {
+      if (claimsMorePages(payload)) {
+        throw new Error(`DraftGo resource_list (${resourceType}) reported more pages without a cursor.`);
+      }
+      return resources;
+    }
+    const cursorKey = String(cursor);
+    if (seen.has(cursorKey)) {
+      throw new Error(`DraftGo resource_list (${resourceType}) repeated a cursor.`);
+    }
+    seen.add(cursorKey);
   }
-  if (cursor) throw new Error('DraftGo resource_list exceeded 100 pages.');
-  return resources;
+  throw new Error(`DraftGo resource_list (${resourceType}) exceeded 100 pages.`);
+}
+
+async function listRemoteResources(session, resourceTypes = DEFAULT_REMOTE_RESOURCE_TYPES, options = {}) {
+  const groups = await allWithAbort(resourceTypes.map((resourceType) =>
+    (queryOptions) => listRemoteResourceType(session, resourceType, queryOptions)), options);
+  return groups.flat();
 }
 
 async function localCheckouts(projectDir) {
@@ -63,13 +105,17 @@ function legacyCaches(projectDir) {
 }
 
 async function mapCommand(projectDir, flags = {}) {
+  const resourceTypes = requestedResourceTypes(flags);
   const config = loadProjectConfig(projectDir);
   const session = await openToolSession(config, [TOOL_NAMES.projectOverview, TOOL_NAMES.resourceList]);
-  const [overview, resources, checkouts] = await Promise.all([
-    callStructured(session, TOOL_NAMES.projectOverview, {}),
-    listRemoteResources(session, flags),
-    localCheckouts(projectDir),
+  const [remote, checkouts] = await allWithAbort([
+    (options) => allWithAbort([
+      (options) => callStructured(session, TOOL_NAMES.projectOverview, {}, options),
+      (options) => listRemoteResources(session, resourceTypes, options),
+    ], options),
+    () => localCheckouts(projectDir),
   ]);
+  const [overview, resources] = remote;
   const result = {
     server: config.server,
     overview,
@@ -103,3 +149,6 @@ async function mapCommand(projectDir, flags = {}) {
 
 module.exports = mapCommand;
 module.exports.itemsFrom = itemsFrom;
+module.exports.normalizeMapResourceType = normalizeMapResourceType;
+module.exports.requestedResourceTypes = requestedResourceTypes;
+module.exports.listRemoteResources = listRemoteResources;

package/src/commands/mcp.js

@@ -11,6 +11,7 @@ const {
   statusHosts,
 } = require('../mcp/hosts');
 const { serveStdio } = require('../mcp/stdio');
+const { parseTimeout } = require('../timeout');
 
 function targetArgs(positional, flags) {
   const values = positional.slice();
@@ -89,11 +90,11 @@ async function test(projectDir, _positional = [], flags = {}) {
   try {
     config = loadProjectConfig(projectDir);
     const result = await testConnection(config, {
-      timeoutMs: flags.timeout ? Number(flags.timeout) : undefined,
+      timeoutMs: parseTimeout(flags.timeout),
     });
     log.ok('DraftGo MCP initialize succeeded.');
     log.ok(`tools/list returned ${result.tools.length} tools.`);
-    log.ok(`tools/call succeeded: ${result.testedTool}`);
+    log.ok(`tools/call succeeded: ${result.testedCalls.join(', ')}`);
     log.dim(`  protocol: ${result.protocolVersion}`);
     return 0;
   } catch (error) {

package/src/context/index.js

@@ -11,6 +11,13 @@ const { readInstalledVersion } = require('../skill');
 
 const SKILL_ROOT = path.join(RESOURCES_DIR, 'skill');
 const MAX_STRUCTURED_TEXT_BYTES = 1024 * 1024;
+const LONG_CONTENT_RESOURCE_TYPES = Object.freeze([
+  'pages',
+  'navigations',
+  'docs/articles',
+]);
+const DB_META_LIST_PATH = '/api/db-meta';
+const DB_META_PAGE_SIZE = 100;
 const ROOT_SECTIONS = [
   '核心边界',
   '强制预读：Reference 优先于 MCP',
@@ -22,7 +29,11 @@ const ROOT_SECTIONS = [
 
 const TASK_PROFILES = Object.freeze({
   frontend: {
-    apiQuery: 'frontend pages navigation',
+    apiQueries: [
+      { resource_type: 'pages' },
+      { resource_type: 'navigations' },
+      { resource_type: 'db' },
+    ],
     references: [
       { file: 'SKILL.md', headings: ROOT_SECTIONS },
       { file: 'references/architecture.md' },
@@ -36,7 +47,7 @@ const TASK_PROFILES = Object.freeze({
     ],
   },
   data: {
-    apiQuery: 'db_meta schema data',
+    apiQueries: [{ resource_type: 'db' }],
     references: [
       { file: 'SKILL.md', headings: ROOT_SECTIONS },
       { file: 'references/modules.md' },
@@ -48,7 +59,7 @@ const TASK_PROFILES = Object.freeze({
     ],
   },
   'custom-service': {
-    apiQuery: 'custom services routes permissions',
+    apiQueries: [{ resource_type: 'custom_scripts' }],
     references: [
       { file: 'SKILL.md', headings: ROOT_SECTIONS },
       { file: 'references/modules.md' },
@@ -59,7 +70,10 @@ const TASK_PROFILES = Object.freeze({
     ],
   },
   aihub: {
-    apiQuery: 'AIHub agents chat',
+    apiQueries: [
+      { resource_type: 'aihub' },
+      { resource_type: 'agents' },
+    ],
     references: [
       { file: 'SKILL.md', headings: ROOT_SECTIONS },
       { file: 'references/aihub.md' },
@@ -69,7 +83,11 @@ const TASK_PROFILES = Object.freeze({
     ],
   },
   content: {
-    apiQuery: 'pages navigations docs',
+    apiQueries: [
+      { resource_type: 'pages' },
+      { resource_type: 'navigations' },
+      { resource_type: 'docs/articles' },
+    ],
     references: [
       { file: 'SKILL.md', headings: ROOT_SECTIONS },
       { file: 'references/architecture.md' },
@@ -80,7 +98,12 @@ const TASK_PROFILES = Object.freeze({
     ],
   },
   project: {
-    apiQuery: 'project resources',
+    apiQueries: [
+      { resource_type: 'pages' },
+      { resource_type: 'navigations' },
+      { resource_type: 'docs/articles' },
+      { resource_type: 'db' },
+    ],
     references: [
       { file: 'SKILL.md', headings: ROOT_SECTIONS },
       { file: 'references/architecture.md' },
@@ -204,7 +227,7 @@ function rawQuery(session, expectedName, args, server, options = {}) {
   }));
 }
 
-function nextCursorFromRaw(result) {
+function structuredValueFromRaw(result) {
   let value = result;
   if (value && value.result) value = value.result;
   if (value && value.structuredContent) value = value.structuredContent;
@@ -225,12 +248,112 @@ function nextCursorFromRaw(result) {
   }
   if (value && value.data) value = value.data;
   if (value && Object.prototype.hasOwnProperty.call(value, 'value')) value = value.value;
+  return value;
+}
+
+function nextCursorFromRaw(result) {
+  const value = structuredValueFromRaw(result);
   if (!value || typeof value !== 'object') return null;
-  if (Object.prototype.hasOwnProperty.call(value, 'next_cursor')) return value.next_cursor;
-  if (Object.prototype.hasOwnProperty.call(value, 'nextCursor')) return value.nextCursor;
-  return value.has_more && Object.prototype.hasOwnProperty.call(value, 'cursor')
-    ? value.cursor
-    : null;
+  const hasMore = value.has_more === true || value.hasMore === true;
+  let cursor = null;
+  let hasCursor = false;
+  if (Object.prototype.hasOwnProperty.call(value, 'next_cursor')) {
+    cursor = value.next_cursor;
+    hasCursor = true;
+  } else if (Object.prototype.hasOwnProperty.call(value, 'nextCursor')) {
+    cursor = value.nextCursor;
+    hasCursor = true;
+  } else if (hasMore && Object.prototype.hasOwnProperty.call(value, 'cursor')) {
+    cursor = value.cursor;
+    hasCursor = true;
+  }
+  if (hasMore && (!hasCursor || cursor == null || cursor === '')) {
+    throw new Error('DraftGo MCP pagination reported more results without a cursor.');
+  }
+  return hasCursor ? cursor : null;
+}
+
+async function collectLongContentResources(session, server, options = {}) {
+  const sequences = await Promise.all(LONG_CONTENT_RESOURCE_TYPES.map((resourceType) =>
+    rawPagedQuery(
+      session,
+      TOOL_NAMES.resourceList,
+      { resource_type: resourceType, limit: 100 },
+      server,
+      options,
+    )));
+  return {
+    source: {
+      kind: 'mcp_tool_batch',
+      server,
+      canonical_tool: TOOL_NAMES.resourceList,
+      arguments: LONG_CONTENT_RESOURCE_TYPES.map((resourceType) => ({
+        resource_type: resourceType,
+        limit: 100,
+      })),
+    },
+    pages: sequences.flatMap((sequence) => sequence.pages),
+  };
+}
+
+async function collectTaskAPIs(session, queries, server, options = {}) {
+  const argumentsList = queries.map((query) => ({ ...query, limit: 100 }));
+  const sequences = await Promise.all(argumentsList.map((args) =>
+    rawPagedQuery(session, TOOL_NAMES.apiSearch, args, server, options)));
+  return {
+    source: {
+      kind: 'mcp_tool_batch',
+      server,
+      canonical_tool: TOOL_NAMES.apiSearch,
+      arguments: argumentsList,
+    },
+    pages: sequences.flatMap((sequence) => sequence.pages),
+  };
+}
+
+function itemsFromRawSequence(sequence) {
+  if (!sequence || !Array.isArray(sequence.pages)) return [];
+  return sequence.pages.flatMap((page) => {
+    const value = structuredValueFromRaw(page);
+    if (Array.isArray(value)) return value;
+    if (value && Array.isArray(value.items)) return value.items;
+    if (value && Array.isArray(value.operations)) return value.operations;
+    return [];
+  });
+}
+
+function selectDBMetaListOperation(sequence) {
+  return itemsFromRawSequence(sequence).find((operation) => {
+    if (!operation || typeof operation !== 'object') return false;
+    const method = String(operation.method || '').trim().toUpperCase();
+    const resourceType = String(operation.resource_type || '').trim().toLowerCase();
+    const operationPath = String(operation.path || operation.path_template || '').trim();
+    return method === 'GET'
+      && resourceType === 'db_meta'
+      && operationPath === DB_META_LIST_PATH
+      && operation.destructive !== true;
+  }) || null;
+}
+
+function optionalPageInteger(value, field, minimum) {
+  if (value == null) return null;
+  if (!Number.isSafeInteger(value) || value < minimum) {
+    throw new Error(`DraftGo db_meta API returned invalid ${field}.`);
+  }
+  return value;
+}
+
+function dbMetaPageInfo(response) {
+  let value = structuredValueFromRaw(response);
+  if (value && value.response) value = value.response;
+  if (value && value.data) value = value.data;
+  if (!value || typeof value !== 'object' || !Array.isArray(value.items)) return null;
+  return {
+    items: value.items,
+    total: optionalPageInteger(value.total, 'total', 0),
+    page: optionalPageInteger(value.page, 'page', 1),
+    pageSize: optionalPageInteger(value.page_size, 'page_size', 1),
+  };
 }
 
 async function rawPagedQuery(session, expectedName, baseArgs, server, options = {}) {
@@ -266,24 +389,102 @@ async function rawPagedQuery(session, expectedName, baseArgs, server, options =
   throw new Error(expectedName + ' exceeded ' + maxPages + ' pages.');
 }
 
+async function collectDBMetaResources(session, operationID, server, options = {}) {
+  const pages = [];
+  let fetchedItems = 0;
+  let reportedTotal = null;
+  const maxPages = options.maxPages == null ? 100 : Number(options.maxPages);
+  if (!Number.isSafeInteger(maxPages) || maxPages < 1) {
+    throw new TypeError('maxPages must be a positive integer.');
+  }
+  for (let page = 1; page <= maxPages; page += 1) {
+    const args = {
+      operation_id: operationID,
+      query: { page, page_size: DB_META_PAGE_SIZE },
+    };
+    const response = await rawQuery(session, TOOL_NAMES.apiCall, args, server, options);
+    pages.push(response);
+    const info = dbMetaPageInfo(response);
+    if (!info) {
+      return {
+        source: {
+          kind: 'mcp_tool_sequence',
+          server,
+          canonical_tool: TOOL_NAMES.apiCall,
+          operation_id: operationID,
+        },
+        pages,
+        pagination: { complete: false, reason: 'response_shape_unavailable' },
+      };
+    }
+    const responsePage = info.page || page;
+    const responsePageSize = info.pageSize || DB_META_PAGE_SIZE;
+    if (responsePage !== page) {
+      throw new Error(`DraftGo db_meta API returned page ${responsePage} while page ${page} was requested.`);
+    }
+    fetchedItems += info.items.length;
+    if (info.total != null) {
+      if (reportedTotal != null && info.total !== reportedTotal) {
+        throw new Error(`DraftGo db_meta API changed total from ${reportedTotal} to ${info.total} during pagination.`);
+      }
+      reportedTotal = info.total;
+    }
+    if (reportedTotal != null) {
+      if (fetchedItems >= reportedTotal) {
+        return {
+          source: {
+            kind: 'mcp_tool_sequence',
+            server,
+            canonical_tool: TOOL_NAMES.apiCall,
+            operation_id: operationID,
+          },
+          pages,
+          pagination: { complete: true, total: reportedTotal },
+        };
+      }
+      if (!info.items.length) {
+        throw new Error('DraftGo db_meta API ended before the reported total was reached.');
+      }
+    } else if (info.items.length < responsePageSize) {
+      return {
+        source: {
+          kind: 'mcp_tool_sequence',
+          server,
+          canonical_tool: TOOL_NAMES.apiCall,
+          operation_id: operationID,
+        },
+        pages,
+        pagination: { complete: true, total: null },
+      };
+    }
+  }
+  throw new Error(`DraftGo db_meta API exceeded ${maxPages} pages.`);
+}
+
 async function collectDataStructures(session, server, options = {}) {
-  const [resources, api] = await Promise.all([
-    rawPagedQuery(
-      session,
-      TOOL_NAMES.resourceList,
-      { resource_type: 'db_meta' },
-      server,
-      options,
-    ),
+  const api = await rawPagedQuery(
+    session,
+    TOOL_NAMES.apiSearch,
+    { resource_type: 'db_meta', limit: 100 },
+    server,
+    options,
+  );
+  const operation = selectDBMetaListOperation(api);
+  if (!operation || !operation.operation_id) {
+    throw new Error('DraftGo MCP does not expose a read-only GET /api/db-meta operation.');
+  }
+  const operationID = String(operation.operation_id);
+  const [contract, resources] = await Promise.all([
     rawQuery(
       session,
-      TOOL_NAMES.apiSearch,
-      { query: 'db_meta schema' },
+      TOOL_NAMES.apiDescribe,
+      { operation_id: operationID },
       server,
       options,
     ),
+    collectDBMetaResources(session, operationID, server, options),
   ]);
-  return { resources, api };
+  return { api, contract, resources };
 }
 
 async function collectContext(projectDir, taskValue, options = {}) {
@@ -292,7 +493,13 @@ async function collectContext(projectDir, taskValue, options = {}) {
   const references = readTaskReferences(task, options);
   const installedSkillVersion = readInstalledSkillVersion(projectDir);
   const config = options.config || loadProjectConfig(projectDir);
-  const expected = [TOOL_NAMES.projectOverview, TOOL_NAMES.resourceList, TOOL_NAMES.apiSearch];
+  const expected = [
+    TOOL_NAMES.projectOverview,
+    TOOL_NAMES.resourceList,
+    TOOL_NAMES.apiSearch,
+    TOOL_NAMES.apiDescribe,
+    TOOL_NAMES.apiCall,
+  ];
   const openSession = options.openToolSession || openToolSession;
   const session = options.session || await openSession(config, expected, options);
   const controller = new AbortController();
@@ -311,14 +518,8 @@ async function collectContext(projectDir, taskValue, options = {}) {
     const queryOptions = { ...options, signal: controller.signal };
     [project, resources, api, dataStructures] = await Promise.all([
       rawQuery(session, TOOL_NAMES.projectOverview, {}, config.server, queryOptions),
-      rawPagedQuery(session, TOOL_NAMES.resourceList, {}, config.server, queryOptions),
-      rawQuery(
-        session,
-        TOOL_NAMES.apiSearch,
-        { query: profile.apiQuery },
-        config.server,
-        queryOptions,
-      ),
+      collectLongContentResources(session, config.server, queryOptions),
+      collectTaskAPIs(session, profile.apiQueries, config.server, queryOptions),
       collectDataStructures(session, config.server, queryOptions),
     ]);
   } catch (error) {
@@ -329,7 +530,7 @@ async function collectContext(projectDir, taskValue, options = {}) {
   }
 
   return {
-    schema_version: '1.0',
+    schema_version: '1.1',
     task,
     reference_bundle: {
       source: 'draftgo-cli',
@@ -360,8 +561,15 @@ module.exports = {
   normalizeTask,
   extractSections,
   readTaskReferences,
+  structuredValueFromRaw,
   nextCursorFromRaw,
   rawPagedQuery,
+  collectLongContentResources,
+  collectTaskAPIs,
+  itemsFromRawSequence,
+  selectDBMetaListOperation,
+  dbMetaPageInfo,
+  collectDBMetaResources,
   collectDataStructures,
   readInstalledSkillVersion,
   collectContext,

package/src/mcp/client.js

@@ -7,11 +7,14 @@ const {
   postJsonRpc,
   redactText,
 } = require('./protocol');
+const { allWithAbort } = require('./parallel');
 
 const SAFE_TEST_TOOLS = [
   'draftgo_project_overview',
   'draftgo_resource_list',
   'draftgo_api_search',
+  'draftgo_api_describe',
+  'draftgo_api_call',
 ];
 
 const REQUIRED_DRAFTGO_TOOLS = [
@@ -25,6 +28,33 @@ const REQUIRED_DRAFTGO_TOOLS = [
   'draftgo_api_call',
 ];
 
+function diagnosticArguments(canonicalName) {
+  if (canonicalName === 'draftgo_resource_list') {
+    return { resource_type: 'pages', limit: 1 };
+  }
+  if (canonicalName === 'draftgo_api_search') return { query: 'project', limit: 1 };
+  return {};
+}
+
+function diagnosticData(result) {
+  let value = result;
+  if (value && value.structuredContent) value = value.structuredContent;
+  else if (value && value.structured_content) value = value.structured_content;
+  if (value && value.data) value = value.data;
+  if (value && Object.prototype.hasOwnProperty.call(value, 'value')) value = value.value;
+  return value;
+}
+
+function findDBMetaListOperation(result) {
+  const value = diagnosticData(result);
+  const items = value && Array.isArray(value.items) ? value.items : [];
+  return items.find((operation) => operation
+    && String(operation.method || '').toUpperCase() === 'GET'
+    && String(operation.resource_type || '').toLowerCase() === 'db_meta'
+    && String(operation.path || operation.path_template || '') === '/api/db-meta'
+    && operation.destructive !== true) || null;
+}
+
 class McpRpcError extends Error {
   constructor(message, { code = -32000, data, id = null } = {}) {
     super(message);
@@ -35,6 +65,40 @@ class McpRpcError extends Error {
   }
 }
 
+function diagnosticNextCursor(result) {
+  const value = diagnosticData(result);
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const hasMore = value.has_more === true || value.hasMore === true;
+
+  let cursor;
+  let present = false;
+  if (Object.prototype.hasOwnProperty.call(value, 'next_cursor')) {
+    cursor = value.next_cursor;
+    present = true;
+  } else if (Object.prototype.hasOwnProperty.call(value, 'nextCursor')) {
+    cursor = value.nextCursor;
+    present = true;
+  } else if (hasMore) {
+    if (!Object.prototype.hasOwnProperty.call(value, 'cursor')) {
+      throw new McpRpcError('DraftGo api_search reported more pages without a cursor.');
+    }
+    cursor = value.cursor;
+    present = true;
+  }
+
+  if (!present) return null;
+  if (cursor == null || cursor === '') {
+    if (hasMore) {
+      throw new McpRpcError('DraftGo api_search reported more pages with an empty cursor.');
+    }
+    return null;
+  }
+  if (typeof cursor !== 'string' || !cursor.trim()) {
+    throw new McpRpcError('DraftGo api_search returned an invalid cursor.');
+  }
+  return cursor;
+}
+
 function redactValue(value, secrets = [], seen = new WeakMap()) {
   if (typeof value === 'string') return redactText(value, secrets);
   if (!value || typeof value !== 'object') return value;
@@ -222,30 +286,118 @@ class DraftGoMcpClient {
     if (missing.length) {
       throw new McpRpcError(`DraftGo MCP is missing required tools: ${missing.join(', ')}.`, { code: -32601 });
     }
-    const required = options.safeTools || SAFE_TEST_TOOLS;
-    const selected = tools.find((tool) => tool && typeof tool.name === 'string'
-      && required.some((candidate) => toolMatches(tool.name, candidate)));
-    if (!selected) {
+    const safeTools = options.safeTools || SAFE_TEST_TOOLS;
+    const hasDiagnosticOverrides = Boolean(options.requiredTools || options.safeTools);
+    const firstSafeTool = tools.find((tool) => tool && typeof tool.name === 'string'
+      && safeTools.some((canonical) => toolMatches(tool.name, canonical)));
+    if (!firstSafeTool) {
       throw new McpRpcError(
-        `DraftGo MCP exposes no safe diagnostic tool (${required.join(', ')}).`,
+        `DraftGo MCP exposes no safe diagnostic tool (${safeTools.join(', ')}).`,
         { code: -32601 },
       );
     }
 
-    const canonical = required.find((candidate) => toolMatches(selected.name, candidate));
-    const defaultArguments = canonical === 'draftgo_api_search' ? { query: 'project' } : {};
-    const toolResult = await this.toolsCall(
-      selected.name,
-      options.toolArguments || defaultArguments,
-      options,
-    );
+    const selected = safeTools.map((canonical) => ({
+      canonical,
+      tool: tools.find((candidate) => candidate && typeof candidate.name === 'string'
+        && toolMatches(candidate.name, canonical)),
+    })).filter((entry) => entry.tool);
+    const byCanonical = Object.fromEntries(selected.map((entry) => [entry.canonical, entry.tool]));
+    const overrideCanonical = safeTools.find((canonical) => toolMatches(firstSafeTool.name, canonical));
+    const defaultPlan = hasDiagnosticOverrides ? [{
+      label: overrideCanonical,
+      canonical: overrideCanonical,
+      tool: firstSafeTool,
+      args: diagnosticArguments(overrideCanonical),
+    }] : [
+      { label: 'project', canonical: 'draftgo_project_overview', tool: byCanonical.draftgo_project_overview, args: {} },
+      ...['pages', 'navigations', 'docs/articles'].map((resourceType) => ({
+        label: `resource:${resourceType}`,
+        canonical: 'draftgo_resource_list',
+        tool: byCanonical.draftgo_resource_list,
+        args: { resource_type: resourceType, limit: 1 },
+      })),
+      {
+        label: 'api:db_meta',
+        canonical: 'draftgo_api_search',
+        tool: byCanonical.draftgo_api_search,
+        args: { resource_type: 'db_meta', limit: 100 },
+      },
+    ];
+    const runPlan = (plan, startIndex = 0) => allWithAbort(plan.map((entry, offset) =>
+      async (queryOptions) => ({
+        label: entry.label,
+        canonical: entry.canonical,
+        name: entry.tool.name,
+        arguments: options.toolArguments && startIndex + offset === 0
+          ? options.toolArguments
+          : entry.args,
+        result: await this.toolsCall(
+          entry.tool.name,
+          options.toolArguments && startIndex + offset === 0
+            ? options.toolArguments
+            : entry.args,
+          queryOptions,
+        ),
+      })), options);
+    const tested = await runPlan(defaultPlan);
+    if (!hasDiagnosticOverrides) {
+      let discovery = tested.find((entry) => entry.label === 'api:db_meta');
+      let operation = discovery && findDBMetaListOperation(discovery.result);
+      const seenCursors = new Set();
+      const maxPages = Number(options.maxPages || 100);
+      let page = 1;
+      while (!operation) {
+        const cursor = diagnosticNextCursor(discovery && discovery.result);
+        if (cursor == null) break;
+        if (seenCursors.has(cursor)) {
+          throw new McpRpcError('DraftGo api_search repeated a db_meta cursor.');
+        }
+        seenCursors.add(cursor);
+        if (page >= maxPages) {
+          throw new McpRpcError(`DraftGo api_search exceeded ${maxPages} db_meta pages.`);
+        }
+        page += 1;
+        [discovery] = await runPlan([{
+          label: `api:db_meta:page-${page}`,
+          canonical: 'draftgo_api_search',
+          tool: byCanonical.draftgo_api_search,
+          args: { resource_type: 'db_meta', limit: 100, cursor },
+        }], tested.length);
+        tested.push(discovery);
+        operation = findDBMetaListOperation(discovery.result);
+      }
+      if (!operation || !operation.operation_id) {
+        throw new McpRpcError('DraftGo MCP exposes no read-only GET /api/db-meta operation.', {
+          code: -32601,
+        });
+      }
+      const operationID = String(operation.operation_id);
+      tested.push(...await runPlan([
+        {
+          label: 'api:describe-db_meta',
+          canonical: 'draftgo_api_describe',
+          tool: byCanonical.draftgo_api_describe,
+          args: { operation_id: operationID },
+        },
+        {
+          label: 'api:call-db_meta',
+          canonical: 'draftgo_api_call',
+          tool: byCanonical.draftgo_api_call,
+          args: { operation_id: operationID, query: { page: 1, page_size: 1 } },
+        },
+      ], tested.length));
+    }
     return {
       initialized,
       protocolVersion: this.protocolVersion,
       sessionId: this.sessionId,
       tools,
-      testedTool: selected.name,
-      toolResult,
+      testedTool: tested[0].name,
+      toolResult: tested[0].result,
+      testedTools: [...new Set(tested.map((entry) => entry.name))],
+      testedCalls: tested.map((entry) => entry.label),
+      diagnosticResults: tested,
     };
   }
 }
@@ -268,6 +420,10 @@ module.exports = {
   McpHttpError,
   SAFE_TEST_TOOLS,
   REQUIRED_DRAFTGO_TOOLS,
+  diagnosticArguments,
+  diagnosticData,
+  diagnosticNextCursor,
+  findDBMetaListOperation,
   redactValue,
   testConnection,
   callTool,

package/src/mcp/parallel.js

@@ -0,0 +1,31 @@
+'use strict';
+
+async function allWithAbort(taskFactories, options = {}) {
+  if (!Array.isArray(taskFactories) || taskFactories.some((task) => typeof task !== 'function')) {
+    throw new TypeError('Parallel MCP tasks must be functions.');
+  }
+  const externalSignal = options.signal;
+  if (externalSignal && externalSignal.aborted) {
+    if (typeof externalSignal.throwIfAborted === 'function') externalSignal.throwIfAborted();
+    const error = new Error('Parallel MCP tasks were aborted before they started.');
+    error.name = 'AbortError';
+    throw error;
+  }
+
+  const controller = new AbortController();
+  const forwardAbort = () => controller.abort(externalSignal.reason);
+  if (externalSignal) {
+    externalSignal.addEventListener('abort', forwardAbort, { once: true });
+  }
+  try {
+    const taskOptions = { ...options, signal: controller.signal };
+    return await Promise.all(taskFactories.map((task) => task(taskOptions)));
+  } catch (error) {
+    if (!controller.signal.aborted) controller.abort(error);
+    throw error;
+  } finally {
+    if (externalSignal) externalSignal.removeEventListener('abort', forwardAbort);
+  }
+}
+
+module.exports = { allWithAbort };

package/src/mcp/protocol.js

@@ -22,9 +22,10 @@ function redactText(value, secrets = []) {
 
 function endpointFor(config) {
   const server = new URL(String(config.server || config.mcp_url));
+  const serverPath = server.pathname.replace(/\/+$/, '');
   const endpoint = config.mcp_url
     ? new URL(String(config.mcp_url), server)
-    : new URL(`${server.pathname.replace(/\/+$/, '')}/mcp`, server);
+    : new URL(`${serverPath}/mcp`, server);
   if (!['http:', 'https:'].includes(endpoint.protocol) || endpoint.username || endpoint.password) {
     throw new McpHttpError('DraftGo MCP endpoint must be a credential-free HTTP(S) URL.');
   }

package/src/projectConfig.js

@@ -11,16 +11,42 @@ const IGNORE_ENTRIES = [
   '.draftgo/conflicts/',
 ];
 
-function normalizeServer(raw) {
+function parseHttpUrl(raw) {
   let value = String(raw || '').trim();
-  if (!value) return '';
+  if (!value) return null;
   if (!/^https?:\/\//i.test(value)) value = `http://${value}`;
   const parsed = new URL(value);
   if (!['http:', 'https:'].includes(parsed.protocol) || parsed.username || parsed.password
       || parsed.search || parsed.hash) {
     throw new Error('DraftGo server must be an absolute HTTP(S) URL without credentials, query, or fragment.');
   }
-  return value.replace(/\/+$/, '');
+  return parsed;
+}
+
+function normalizeServer(raw) {
+  const parsed = parseHttpUrl(raw);
+  if (!parsed) return '';
+  return parsed.toString().replace(/\/+$/, '');
+}
+
+function normalizeMcpEndpoint(raw) {
+  const parsed = parseHttpUrl(raw);
+  return parsed ? parsed.toString() : '';
+}
+
+function normalizeConnection(raw) {
+  const value = normalizeMcpEndpoint(raw);
+  if (!value) return { server: '', mcp_url: '' };
+  const parsed = new URL(value);
+  const pathname = parsed.pathname.replace(/\/+$/, '');
+  if (!pathname.toLowerCase().endsWith('/mcp')) {
+    return { server: '', mcp_url: value };
+  }
+  parsed.pathname = pathname.slice(0, -4) || '/';
+  return {
+    server: parsed.toString().replace(/\/+$/, ''),
+    mcp_url: value,
+  };
 }
 
 function configPath(projectDir) {
@@ -65,7 +91,7 @@ function writePrivateJson(file, value) {
   try { fs.chmodSync(file, 0o600); } catch { /* Windows ACLs are inherited. */ }
 }
 
-function writeProjectConfig(projectDir, server, token) {
+function writeProjectConfig(projectDir, server, token, options = {}) {
   const normalizedServer = normalizeServer(server);
   const sat = String(token || '').trim();
   if (!normalizedServer) throw new Error('DraftGo server is required.');
@@ -77,6 +103,8 @@ function writeProjectConfig(projectDir, server, token) {
     token: sat,
     auto_push: existing.auto_push === true,
   };
+  if (options.mcp_url) config.mcp_url = normalizeMcpEndpoint(options.mcp_url);
+  else delete config.mcp_url;
   const file = configPath(projectDir);
   writePrivateJson(file, config);
   ensureProjectIgnores(projectDir);
@@ -88,16 +116,22 @@ function loadProjectConfig(projectDir, { requireToken = true } = {}) {
   if (!exists(file)) throw new Error('Missing .draftgo/config.json; run `draftgo connect` first.');
   const config = readExisting(projectDir);
   const server = normalizeServer(config.server);
+  const mcpUrl = config.mcp_url ? normalizeMcpEndpoint(config.mcp_url) : '';
   const token = String(config.token || config.sat || '').trim();
   if (!server) throw new Error('DraftGo project config is missing server.');
   if (requireToken && !token) throw new Error('DraftGo project config is missing SAT.');
-  return { ...config, server, token, path: file };
+  const result = { ...config, server, token, path: file };
+  if (mcpUrl) result.mcp_url = mcpUrl;
+  else delete result.mcp_url;
+  return result;
 }
 
 module.exports = {
   IGNORE_ENTRIES,
   configPath,
   normalizeServer,
+  normalizeMcpEndpoint,
+  normalizeConnection,
   ensureProjectIgnores,
   writeProjectConfig,
   loadProjectConfig,

package/src/timeout.js

@@ -0,0 +1,18 @@
+'use strict';
+
+const MAX_TIMEOUT_MS = 2_147_483_647;
+
+function parseTimeout(value) {
+  if (value == null) return undefined;
+  const text = String(value).trim();
+  if (!/^\d+$/.test(text)) {
+    throw new TypeError('--timeout must be a positive integer in milliseconds.');
+  }
+  const timeoutMs = Number(text);
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > MAX_TIMEOUT_MS) {
+    throw new TypeError(`--timeout must be between 1 and ${MAX_TIMEOUT_MS} milliseconds.`);
+  }
+  return timeoutMs;
+}
+
+module.exports = { MAX_TIMEOUT_MS, parseTimeout };