dingtalk-dws-mcp 1.0.0 → 1.0.2

package/README.md

@@ -2,7 +2,7 @@
 
 源码包。用户能力与接入见 [`mcp/dingtalk-dws-mcp/GUIDE.md`](../../../mcp/dingtalk-dws-mcp/GUIDE.md)。
 
-Agent：`instructions` / tool `description` / `prompts`。长期巡检：`dingtalk_patrol_setup` 备料 → 传装到主机 → 停。
+Agent：`instructions` / tool `description` / `prompts` / **Resources（`guides/*.md`）**。长期巡检：`dingtalk_patrol_setup` 备料 → 传装到主机 → 停。
 
 ## 构建
 
@@ -16,6 +16,6 @@ npm run pack:deploy
 可选：`DINGTALK_PATROL_INCLUDE_NODE=0`、`DINGTALK_PATROL_NODE_URL`、`DINGTALK_PATROL_INCLUDE_DWS=0`（默认尝试打入 linux ELF dws；Windows 打包机需 `DINGTALK_PATROL_DWS_PATH` 指向 ELF）。  
 `dingtalk_patrol_setup` 只写 staging（含本机已验证投递凭据）；传装用 host-execution 或 SSH，目标机跑 `install.sh`。可选 `deploy.sh` 为直连 SSH helper。  
 
-配置示例：[`mcp/dingtalk-dws-mcp/mcp.example.json`](../../../mcp/dingtalk-dws-mcp/mcp.example.json)。
+配置示例（npx）：[`mcp/dingtalk-dws-mcp/mcp.example.json`](../../../mcp/dingtalk-dws-mcp/mcp.example.json)。npm：`dingtalk-dws-mcp@1.0.2`。
 
 规格（开发者）：[RFC-0007](../../../docs/rfc/RFC-0007-dingtalk-dws-mcp.md)、[RFC-0008](../../../docs/rfc/RFC-0008-dingtalk-notify-patrol.md)。

package/dist/src/delivery/webhook.d.ts

@@ -1,4 +1,4 @@
-import { type DeliveryResult } from "agent-compose-notify-delivery";
+import { type DeliveryResult } from "../notify-delivery/index.js";
 import type { AppConfig, DeliveryRequest } from "../types.js";
 export declare function validateWebhookConfig(config: AppConfig): {
     valid: boolean;

package/dist/src/delivery/webhook.js

@@ -1,4 +1,4 @@
-import { sendWebhook as libSendWebhook, validateWebhookUrl, } from "agent-compose-notify-delivery";
+import { sendWebhook as libSendWebhook, validateWebhookUrl, } from "../notify-delivery/index.js";
 export function validateWebhookConfig(config) {
     return validateWebhookUrl(config.webhookUrl);
 }

package/dist/src/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { redact } from "agent-compose-notify-delivery";
+import { redact } from "./notify-delivery/index.js";
 import { runStdioServer } from "./server.js";
 runStdioServer().catch((error) => {
     const message = error instanceof Error ? error.message : String(error);

package/dist/src/internal/dws-robot-command.d.ts

@@ -1,4 +1,4 @@
-import { type CommandRunner, type DeliveryResult } from "agent-compose-notify-delivery";
+import { type CommandRunner, type DeliveryResult } from "../notify-delivery/index.js";
 import type { AppConfig, DeliveryRequest } from "../types.js";
 export type { CommandRunner };
 export declare function sendRobotMessage(config: AppConfig, request: DeliveryRequest, runner?: CommandRunner, env?: NodeJS.ProcessEnv): Promise<DeliveryResult>;

package/dist/src/internal/dws-robot-command.js

@@ -1,5 +1,5 @@
 import * as path from "node:path";
-import { sendRobotMessage as libSendRobotMessage, } from "agent-compose-notify-delivery";
+import { sendRobotMessage as libSendRobotMessage, } from "../notify-delivery/index.js";
 export async function sendRobotMessage(config, request, runner, env = process.env) {
     if (!config.clientId || !config.clientSecret || !config.robotCode) {
         return {

package/dist/src/internal/exec.js

@@ -5,7 +5,7 @@
  */
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
-import { redact } from "agent-compose-notify-delivery";
+import { redact } from "../notify-delivery/index.js";
 const execFileAsync = promisify(execFile);
 const USER_DWS_ENV = [
     "HOME", "USERPROFILE", "PATH", "USER", "LOGNAME", "TMPDIR", "TEMP", "TMP",

package/dist/src/notify-delivery/dws-robot.d.ts

@@ -0,0 +1,24 @@
+import type { DeliveryMessage, DeliveryResult } from "./result.js";
+export type CommandRunner = (file: string, args: readonly string[], options: {
+    timeout: number;
+    maxBuffer: number;
+    env: NodeJS.ProcessEnv;
+    windowsHide: boolean;
+}) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+export declare function robotDwsEnv(configDir: string, clientId: string, clientSecret: string, env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function normalizeRobotResult(value: unknown): DeliveryResult;
+export interface RobotSendOptions {
+    dwsCommand: string;
+    clientId: string;
+    clientSecret: string;
+    robotCode: string;
+    configDir: string;
+    timeoutMs: number;
+    maxOutputBytes: number;
+    runner?: CommandRunner;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function sendRobotMessage(options: RobotSendOptions, message: DeliveryMessage): Promise<DeliveryResult>;

package/dist/src/notify-delivery/dws-robot.js

@@ -0,0 +1,129 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { redact } from "./redact.js";
+const execFileAsync = promisify(execFile);
+const GROUP_PATH = "/v1.0/robot/groupMessages/send";
+const USER_PATH = "/v1.0/robot/oToMessages/batchSend";
+const USER_DWS_ENV = [
+    "HOME", "USERPROFILE", "PATH", "USER", "LOGNAME", "TMPDIR", "TEMP", "TMP",
+    "XDG_CONFIG_HOME", "XDG_DATA_HOME", "BROWSER", "DISPLAY", "WAYLAND_DISPLAY",
+    "NODE_EXTRA_CA_CERTS", "DWS_CONFIG_DIR",
+];
+function pickEnv(names, env) {
+    const result = {};
+    for (const name of names) {
+        if (env[name] !== undefined)
+            result[name] = env[name];
+    }
+    return result;
+}
+export function robotDwsEnv(configDir, clientId, clientSecret, env = process.env) {
+    return {
+        ...pickEnv(USER_DWS_ENV, env),
+        DWS_CONFIG_DIR: configDir,
+        DWS_CLIENT_ID: clientId,
+        DWS_CLIENT_SECRET: clientSecret,
+    };
+}
+function nested(root) {
+    const values = [root];
+    for (const key of ["result", "body", "payload", "response", "data"]) {
+        const candidate = root[key];
+        if (candidate && typeof candidate === "object" && !Array.isArray(candidate)) {
+            values.push(candidate);
+        }
+    }
+    return values;
+}
+function stringField(records, keys) {
+    for (const record of records) {
+        for (const key of keys) {
+            if (typeof record[key] === "string" && record[key])
+                return record[key];
+        }
+    }
+    return undefined;
+}
+function parseJsonObject(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed)
+        throw new Error("Command produced no JSON output");
+    const value = JSON.parse(trimmed);
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Command returned non-object JSON");
+    }
+    return value;
+}
+export function normalizeRobotResult(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return { status: "unknown", errorCode: "DELIVERY_UNKNOWN", reason: "Non-object response" };
+    }
+    const root = value;
+    const records = nested(root);
+    const errorRecord = root.error && typeof root.error === "object" ? root.error : undefined;
+    const error = typeof errorRecord?.message === "string" ? errorRecord.message : undefined;
+    const explicitSuccess = records.find((item) => typeof item.success === "boolean")?.success;
+    if (explicitSuccess === false || error) {
+        return { status: "failed", errorCode: "ADAPTER_REJECTED", error: error ?? "Request rejected" };
+    }
+    const messageId = stringField(records, ["processQueryKey", "messageId", "taskId", "id"]);
+    if (explicitSuccess === true || messageId) {
+        return { status: "sent", messageId };
+    }
+    return { status: "unknown", errorCode: "DELIVERY_UNKNOWN", reason: "Delivery was not confirmed" };
+}
+export async function sendRobotMessage(options, message) {
+    if (!options.clientId || !options.clientSecret || !options.robotCode) {
+        return { status: "failed", errorCode: "ADAPTER_UNAUTHORIZED", error: "Robot application credentials are required" };
+    }
+    const apiPath = message.routeType === "group" ? GROUP_PATH : USER_PATH;
+    const payload = {
+        robotCode: options.robotCode,
+        msgKey: "sampleMarkdown",
+        msgParam: JSON.stringify({ title: message.title, text: message.content }),
+    };
+    if (message.routeType === "group")
+        payload.openConversationId = message.targetId;
+    else
+        payload.userIds = [message.targetId];
+    const runner = options.runner ?? execFileAsync;
+    const env = robotDwsEnv(options.configDir, options.clientId, options.clientSecret, options.env);
+    try {
+        const { stdout } = await runner(options.dwsCommand, ["api", "POST", apiPath, "--data", JSON.stringify(payload), "--format", "json", "--yes"], {
+            timeout: options.timeoutMs,
+            maxBuffer: options.maxOutputBytes,
+            env,
+            windowsHide: true,
+        });
+        return normalizeRobotResult(parseJsonObject(stdout));
+    }
+    catch (error) {
+        const text = error instanceof Error ? error.message : String(error);
+        if (/missing app credentials|APP_CREDENTIALS|client.?secret/i.test(text)) {
+            return { status: "failed", errorCode: "ADAPTER_UNAUTHORIZED", error: "Application credentials are required" };
+        }
+        if (/timed out|ETIMEDOUT|abort/i.test(text)) {
+            return {
+                status: "unknown",
+                errorCode: "DELIVERY_UNKNOWN",
+                reason: "Robot delivery timed out; delivery status is unknown",
+            };
+        }
+        if (/ENOENT|ECONNREFUSED/i.test(text)) {
+            return { status: "failed", errorCode: "ADAPTER_UNAVAILABLE", error: "dws is unavailable" };
+        }
+        try {
+            const stdout = error.stdout;
+            if (stdout)
+                return normalizeRobotResult(parseJsonObject(stdout));
+        }
+        catch {
+            // fall through
+        }
+        return {
+            status: "failed",
+            errorCode: "DELIVERY_FAILED",
+            error: redact(text) || "Robot delivery failed",
+        };
+    }
+}

package/dist/src/notify-delivery/index.d.ts

@@ -0,0 +1,5 @@
+export type { DeliveryResult, DeliveryMessage, RouteType } from "./result.js";
+export { normalizeWebhookResult, resolveWebhookUrl, sendWebhook, validateWebhookUrl, type WebhookSendOptions, } from "./webhook.js";
+export { normalizeRobotResult, robotDwsEnv, sendRobotMessage, type CommandRunner, type RobotSendOptions, } from "./dws-robot.js";
+export { DEFAULT_PATROL_MESSAGE_BODY, DEFAULT_PATROL_MESSAGE_TITLE, } from "./patrol-message.js";
+export { redact } from "./redact.js";

package/dist/src/notify-delivery/index.js

@@ -0,0 +1,4 @@
+export { normalizeWebhookResult, resolveWebhookUrl, sendWebhook, validateWebhookUrl, } from "./webhook.js";
+export { normalizeRobotResult, robotDwsEnv, sendRobotMessage, } from "./dws-robot.js";
+export { DEFAULT_PATROL_MESSAGE_BODY, DEFAULT_PATROL_MESSAGE_TITLE, } from "./patrol-message.js";
+export { redact } from "./redact.js";

package/dist/src/notify-delivery/patrol-message.d.ts

@@ -0,0 +1,3 @@
+/** Shared default DingTalk markdown shell for patrol (CLI + MCP setup). */
+export declare const DEFAULT_PATROL_MESSAGE_TITLE = "[{{status}}] {{name}}";
+export declare const DEFAULT_PATROL_MESSAGE_BODY = "### {{name}} \u00B7 {{status}}\n\n{{summary}}\n\n---\n\u4E3B\u673A\uFF1A{{hostname}}\n\u65F6\u95F4\uFF1A{{timestamp}}\n";

package/dist/src/notify-delivery/patrol-message.js

@@ -0,0 +1,10 @@
+/** Shared default DingTalk markdown shell for patrol (CLI + MCP setup). */
+export const DEFAULT_PATROL_MESSAGE_TITLE = "[{{status}}] {{name}}";
+export const DEFAULT_PATROL_MESSAGE_BODY = `### {{name}} · {{status}}
+
+{{summary}}
+
+---
+主机：{{hostname}}
+时间：{{timestamp}}
+`;

package/dist/src/notify-delivery/redact.d.ts

@@ -0,0 +1 @@
+export declare function redact(value: string): string;

package/dist/src/notify-delivery/redact.js

@@ -0,0 +1,12 @@
+const SECRET_PATTERNS = [
+    /Bearer\s+[A-Za-z0-9._~+/-]+=*/gi,
+    /access_token=[^&\s]+/gi,
+    /client[_-]?secret["'\s:=]+[^\s"',}]+/gi,
+];
+export function redact(value) {
+    let result = value;
+    for (const pattern of SECRET_PATTERNS) {
+        result = result.replace(pattern, "[REDACTED]");
+    }
+    return result;
+}

package/dist/src/notify-delivery/result.d.ts

@@ -0,0 +1,20 @@
+/** Discriminated delivery outcome. failed = safe to retry; unknown = do not auto-retry. */
+export type DeliveryResult = {
+    status: "sent";
+    messageId?: string;
+} | {
+    status: "failed";
+    error: string;
+    errorCode?: string;
+} | {
+    status: "unknown";
+    reason: string;
+    errorCode?: string;
+};
+export type RouteType = "group" | "user";
+export interface DeliveryMessage {
+    routeType: RouteType;
+    targetId: string;
+    title: string;
+    content: string;
+}

package/dist/src/notify-delivery/result.js

@@ -0,0 +1 @@
+export {};

package/dist/src/notify-delivery/webhook.d.ts

@@ -0,0 +1,14 @@
+import type { DeliveryMessage, DeliveryResult } from "./result.js";
+export declare function resolveWebhookUrl(value: string): URL | undefined;
+export declare function validateWebhookUrl(webhookUrl: string | undefined): {
+    valid: boolean;
+    message: string;
+};
+export interface WebhookSendOptions {
+    webhookUrl: string;
+    webhookSecret?: string;
+    timeoutMs: number;
+    fetchImpl?: typeof fetch;
+}
+export declare function sendWebhook(options: WebhookSendOptions, message: DeliveryMessage): Promise<DeliveryResult>;
+export declare function normalizeWebhookResult(httpStatus: number, value: unknown): DeliveryResult;

package/dist/src/notify-delivery/webhook.js

@@ -0,0 +1,126 @@
+import { createHmac } from "node:crypto";
+import { redact } from "./redact.js";
+const WEBHOOK_HOST = "oapi.dingtalk.com";
+const WEBHOOK_PATH = "/robot/send";
+export function resolveWebhookUrl(value) {
+    try {
+        const url = new URL(value);
+        if (url.protocol !== "https:"
+            || url.hostname !== WEBHOOK_HOST
+            || url.pathname !== WEBHOOK_PATH
+            || !url.searchParams.get("access_token")
+            || url.username
+            || url.password
+            || url.hash) {
+            return undefined;
+        }
+        return url;
+    }
+    catch {
+        return undefined;
+    }
+}
+function signedUrl(url, secret, timestamp) {
+    const result = new URL(url);
+    const timestampValue = String(timestamp);
+    const signature = createHmac("sha256", secret)
+        .update(`${timestampValue}\n${secret}`)
+        .digest("base64");
+    result.searchParams.set("timestamp", timestampValue);
+    result.searchParams.set("sign", signature);
+    return result;
+}
+export function validateWebhookUrl(webhookUrl) {
+    if (!webhookUrl)
+        return { valid: false, message: "DINGTALK_WEBHOOK_URL is not set" };
+    if (!resolveWebhookUrl(webhookUrl)) {
+        return { valid: false, message: "DINGTALK_WEBHOOK_URL must be an https://oapi.dingtalk.com/robot/send URL" };
+    }
+    return { valid: true, message: "Webhook URL is valid" };
+}
+export async function sendWebhook(options, message) {
+    if (message.routeType !== "group") {
+        return { status: "failed", errorCode: "ADAPTER_UNSUPPORTED", error: "Webhook only supports group routes" };
+    }
+    const base = resolveWebhookUrl(options.webhookUrl);
+    if (!base) {
+        return { status: "failed", errorCode: "ADAPTER_UNAUTHORIZED", error: "Webhook URL is invalid" };
+    }
+    const url = options.webhookSecret
+        ? signedUrl(base, options.webhookSecret, Date.now())
+        : base;
+    const fetchImpl = options.fetchImpl ?? fetch;
+    try {
+        const response = await fetchImpl(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                msgtype: "markdown",
+                markdown: { title: message.title, text: message.content },
+            }),
+            signal: AbortSignal.timeout(options.timeoutMs),
+        });
+        const text = await response.text();
+        let payload;
+        try {
+            payload = JSON.parse(text);
+        }
+        catch {
+            if (response.status === 401 || response.status === 403) {
+                return { status: "failed", errorCode: "ADAPTER_UNAUTHORIZED", error: "Webhook authorization failed" };
+            }
+            return { status: "unknown", errorCode: "DELIVERY_UNKNOWN", reason: "Webhook returned non-JSON" };
+        }
+        return normalizeWebhookResult(response.status, payload);
+    }
+    catch (error) {
+        if (isTimeout(error)) {
+            return {
+                status: "unknown",
+                errorCode: "DELIVERY_UNKNOWN",
+                reason: "Webhook delivery timed out; delivery status is unknown",
+            };
+        }
+        return {
+            status: "failed",
+            errorCode: "ADAPTER_UNAVAILABLE",
+            error: error instanceof Error ? redact(error.message) : "Webhook request failed",
+        };
+    }
+}
+function isTimeout(error) {
+    const name = error && typeof error === "object" && "name" in error ? String(error.name) : "";
+    const message = error instanceof Error ? error.message : String(error);
+    return name === "TimeoutError" || name === "AbortError" || /aborted due to timeout|The operation was aborted/i.test(message);
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+export function normalizeWebhookResult(httpStatus, value) {
+    if (httpStatus === 401 || httpStatus === 403) {
+        return { status: "failed", errorCode: "ADAPTER_UNAUTHORIZED", error: "Webhook authorization failed" };
+    }
+    if (!isRecord(value)) {
+        return { status: "unknown", errorCode: "DELIVERY_UNKNOWN", reason: "Webhook returned a non-object response" };
+    }
+    const errcode = typeof value.errcode === "number" ? value.errcode : undefined;
+    const errmsg = typeof value.errmsg === "string" ? redact(value.errmsg) : undefined;
+    if (errcode === 310000 || /sign not match|check sign|invalid sign|缺少timestamp|timestamp is expired|加签/i.test(errmsg ?? "")) {
+        return {
+            status: "failed",
+            errorCode: "ADAPTER_UNAUTHORIZED",
+            error: "Webhook signing failed; set DINGTALK_WEBHOOK_SECRET for a signed robot",
+        };
+    }
+    if (httpStatus < 200 || httpStatus >= 300 || (errcode !== undefined && errcode !== 0)) {
+        return {
+            status: "failed",
+            errorCode: "ADAPTER_REJECTED",
+            error: errmsg ? `Webhook rejected: ${errmsg}` : "Webhook rejected the request",
+        };
+    }
+    if (errcode === 0) {
+        return { status: "sent" };
+    }
+    return { status: "unknown", errorCode: "DELIVERY_UNKNOWN", reason: "Webhook response did not confirm delivery" };
+}

package/dist/src/patrol/setup.js

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { DEFAULT_PATROL_MESSAGE_BODY, DEFAULT_PATROL_MESSAGE_TITLE, } from "agent-compose-notify-delivery";
+import { DEFAULT_PATROL_MESSAGE_BODY, DEFAULT_PATROL_MESSAGE_TITLE, } from "../notify-delivery/index.js";
 import { DingtalkDwsError } from "../errors.js";
 import { isRouteConfigured, readTargets } from "../notify/bind.js";
 import { mcpPackageRoot, readPackageVersion } from "../version.js";

package/dist/src/resources/guides.d.ts

@@ -0,0 +1,24 @@
+export type GuideMeta = {
+    slug: string;
+    uri: string;
+    title: string;
+    description: string;
+};
+export declare function listMcpGuideResources(): Array<{
+    uri: string;
+    name: string;
+    title: string;
+    description: string;
+    mimeType: string;
+    annotations: {
+        audience: Array<"user" | "assistant">;
+        priority: number;
+    };
+}>;
+export declare function readMcpGuideResource(uri: string): {
+    contents: Array<{
+        uri: string;
+        mimeType: string;
+        text: string;
+    }>;
+};

package/dist/src/resources/guides.js

@@ -0,0 +1,36 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { mcpPackageRoot } from "../version.js";
+const GUIDES = [
+    {
+        slug: "doc-search",
+        uri: "dingtalk-dws://guides/doc-search",
+        title: "DingTalk cloud doc search",
+        description: "Agent overlay: drive search short path and stop-rules; prefer over upstream doc search recipes when they lag.",
+    },
+];
+function readMarkdown(slug) {
+    const filePath = path.join(mcpPackageRoot(), "guides", `${slug}.md`);
+    return fs.readFileSync(filePath, "utf8");
+}
+export function listMcpGuideResources() {
+    return GUIDES.map((g) => ({
+        uri: g.uri,
+        name: g.slug,
+        title: g.title,
+        description: g.description,
+        mimeType: "text/markdown",
+        annotations: { audience: ["assistant"], priority: 0.7 },
+    }));
+}
+export function readMcpGuideResource(uri) {
+    const guide = GUIDES.find((g) => g.uri === uri);
+    if (!guide) {
+        const err = new Error(`Resource not found: ${uri}`);
+        err.code = -32002;
+        throw err;
+    }
+    return {
+        contents: [{ uri, mimeType: "text/markdown", text: readMarkdown(guide.slug) }],
+    };
+}

package/dist/src/server.js

@@ -1,9 +1,10 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { loadConfig } from "./config.js";
 import { IdempotencyStore } from "./notify/idempotency-store.js";
 import { getPromptMessages, listPromptDefinitions } from "./prompts.js";
+import { listMcpGuideResources, readMcpGuideResource } from "./resources/guides.js";
 import { DingtalkDwsService } from "./service.js";
 import { buildInstructions, callTool, createToolDefinitions, resolveToolSurface } from "./tools/registry.js";
 import { readPackageVersion } from "./version.js";
@@ -22,7 +23,7 @@ export function createMcpServer(service, store) {
     if (!resolvedStore)
         throw new Error("store required");
     const surface = resolveToolSurface(adapter);
-    const server = new Server({ name: MCP_SERVER_NAME, version: MCP_SERVER_VERSION }, { capabilities: { tools: {}, prompts: {} }, instructions: buildInstructions(surface) });
+    const server = new Server({ name: MCP_SERVER_NAME, version: MCP_SERVER_VERSION }, { capabilities: { tools: {}, prompts: {}, resources: {} }, instructions: buildInstructions(surface) });
     const tools = createToolDefinitions(surface);
     server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [...tools] }));
     server.setRequestHandler(CallToolRequestSchema, async (request) => (callTool(resolvedService, request.params.name, request.params.arguments ?? {}, surface)));
@@ -37,6 +38,10 @@ export function createMcpServer(service, store) {
             throw new Error(`Unknown prompt: ${request.params.name}`);
         }
     });
+    server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+        resources: listMcpGuideResources(),
+    }));
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => (readMcpGuideResource(request.params.uri)));
     return { server, service: resolvedService, store: resolvedStore };
 }
 export async function runStdioServer() {

package/dist/src/tools/registry.js

@@ -15,6 +15,7 @@ export function buildInstructions(surface) {
     // User-selected recipes → prompts. Do not duplicate those here.
     const lines = [
         "DingTalk robot notify + dws readiness (Agent surface of the dws ecosystem). Office stays on local dws.",
+        "Office via local dws: before following upstream Skill recipes, read this server's MCP Resources overlays when they apply.",
         "Constraint: recurring/host patrol must not use session loops or repeated dingtalk_send — Agent derives host/cron/probe from conversation, calls dingtalk_patrol_setup once (stages bundle paths + delivery credentials), copies to host via host-execution or SSH, runs install.sh on the host, then stops. MCP env holds credentials only. Do not download Node in-session.",
         "Call dingtalk_doctor first; connected ≠ ready.",
     ];

package/guides/doc-search.md

@@ -0,0 +1,37 @@
+# DingTalk cloud doc search (Agent overlay)
+
+Use this when the user asks to find / list / summarize DingTalk cloud docs or knowledge-base pages.
+
+Upstream dws Skill recipes may still say `doc search` / `doc list`. Prefer this overlay when they conflict.
+
+## Short path
+
+1. One primary search:
+   ```bash
+   dws drive search --query "<user keywords>" --format json
+   ```
+2. From `documents[]`, keep **5–10** hits with `name` / `nodeId` / `docUrl` (or `url`) / type.
+3. Deliver a **table** (name + link + one-line why relevant). Stop here if that answers the user.
+4. Only if the user wants depth, or top hits need a title skim: read **at most 2–3** `adoc` nodes:
+   ```bash
+   dws doc read --node <nodeId> --content-format markdown --format json
+   ```
+   Use the JSON field **`markdown`** (not `content`). Prefer headings / first ~20 lines — not the whole body in chat.
+
+## Do not
+
+- Recurse `drive list` / wiki folder listing after search (folder child names are often opaque IDs).
+- Fire many overlapping queries (`性能优化` + `训练性能` + …) by default — one main query, optional one supplement.
+- Pull full document bodies by default.
+- Treat dlink / non-adoc hits as readable via `doc read` — give the link only.
+- Treat empty `doc read` as “try another format / write a helper script” — check the `markdown` field / `--help` once, then skip or try the next hit.
+
+## Knowledge-base scoped search
+
+If the user already named a workspace/knowledge base:
+
+```bash
+dws wiki node search --workspace <id> --query "<keywords>" --format json
+```
+
+Otherwise stay on global `drive search`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dingtalk-dws-mcp",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "DingTalk robot notification MCP with dws readiness handshake",
   "license": "Apache-2.0",
   "type": "module",
@@ -10,6 +10,7 @@
   "main": "dist/src/index.js",
   "files": [
     "dist/src",
+    "guides",
     "README.md",
     "LICENSE"
   ],
@@ -33,7 +34,6 @@
     "notification"
   ],
   "dependencies": {
-    "agent-compose-notify-delivery": "^1.0.0",
     "@modelcontextprotocol/sdk": "^1.29.0"
   },
   "devDependencies": {