dingtalk-dws-mcp 1.0.0

package/dist/src/tools/registry.js

@@ -0,0 +1,275 @@
+import { DingtalkDwsError, asDingtalkDwsError } from "../errors.js";
+const emptySchema = { type: "object", properties: {}, additionalProperties: false };
+export function resolveToolSurface(adapter) {
+    if (adapter === "webhook") {
+        return { adapter, authTools: false, directoryTools: false, listRoutes: false, send: true };
+    }
+    if (adapter === "dws") {
+        return { adapter, authTools: true, directoryTools: true, listRoutes: true, send: true };
+    }
+    // Unconfigured or config conflict: handshake only until delivery is chosen.
+    return { adapter, authTools: true, directoryTools: false, listRoutes: false, send: false };
+}
+export function buildInstructions(surface) {
+    // Cross-tool constraints only. Per-tool when/when-not → tool descriptions.
+    // 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.",
+        "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.",
+    ];
+    if (surface.adapter === null) {
+        lines.push("Delivery unset: configure Managed robot credentials (default) or optional webhook, then restart.");
+    }
+    else if (surface.adapter === "webhook") {
+        lines.push("Webhook tools: doctor + send (notify_group only).");
+    }
+    else {
+        lines.push("Managed tools: search → bind → send. Bind targets are for this server only.");
+    }
+    lines.push("Never put credentials or secrets in message content.");
+    if (surface.authTools) {
+        lines.push("Manual/headless login: run `dws auth login` in a local terminal when doctor asks.");
+    }
+    return lines.join(" ");
+}
+export function createToolDefinitions(surface) {
+    const tools = [];
+    tools.push({
+        name: "dingtalk_doctor",
+        description: "Check whether local dws and notify delivery are ready; returns next_action.",
+        inputSchema: emptySchema,
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    });
+    if (surface.authTools) {
+        tools.push({
+            name: "dingtalk_auth_status",
+            description: "Check local dws login (needed for directory search).",
+            inputSchema: emptySchema,
+            annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+        }, {
+            name: "dingtalk_auth_login",
+            description: "Start controlled dws login. Manual mode: user runs `dws auth login` locally.",
+            inputSchema: emptySchema,
+            annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+        });
+    }
+    if (surface.directoryTools) {
+        tools.push({
+            name: "dingtalk_search_targets",
+            description: "Find groups/users by display name; returns opaque candidate_ref for bind.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: { type: "string", minLength: 1 },
+                    type: { type: "string", enum: ["all", "group", "user"] },
+                    limit: { type: "integer", minimum: 1, maximum: 20 },
+                },
+                required: ["query"],
+                additionalProperties: false,
+            },
+            annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+        }, {
+            name: "dingtalk_configure_route_target",
+            description: "Bind one search result to notify_group or notify_user for later send.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: { type: "string", minLength: 1 },
+                    route: { type: "string", enum: ["notify_group", "notify_user"] },
+                    type: { type: "string", enum: ["group", "user"] },
+                    candidate_ref: { type: "string", minLength: 1 },
+                },
+                required: ["query"],
+                additionalProperties: false,
+            },
+            annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+        });
+    }
+    if (surface.listRoutes) {
+        tools.push({
+            name: "dingtalk_list_routes",
+            description: "List whether notify_group / notify_user are bound.",
+            inputSchema: emptySchema,
+            annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        });
+    }
+    if (surface.send) {
+        const routeEnum = surface.adapter === "webhook" ? ["notify_group"] : ["notify_group", "notify_user"];
+        tools.push({
+            name: "dingtalk_send",
+            description: surface.adapter === "webhook"
+                ? "Send one group message now (route=notify_group, title, content). Do not use for recurring, polling, or long-running host checks."
+                : "Send one message now (route, title, content). Do not use for recurring, polling, or long-running host checks.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    route: { type: "string", enum: routeEnum },
+                    title: { type: "string", minLength: 1 },
+                    content: { type: "string", minLength: 1 },
+                    dedupe_key: { type: "string" },
+                },
+                required: ["route", "title", "content"],
+                additionalProperties: false,
+            },
+            annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+        });
+    }
+    // Always available: stage host patrol materials (Agent transfers + remote install).
+    tools.push({
+        name: "dingtalk_patrol_setup",
+        description: "Stage offline patrol materials only (patrol.yaml, env.sh with local delivery credentials, probe). Does not SSH. Agent fills name/cron/probe from conversation; prefer bound notify target (omit route). Then copy bundle_root + staging_dir to the host (host-execution or SSH) and run install.sh there. Call once for staging, finish install, then stop. Never returns secrets.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: { type: "string", minLength: 1 },
+                cron: { type: "string", description: "Crontab expression; Agent derives from user intent (default */15)" },
+                route: { type: "string", enum: ["notify_group", "notify_user"] },
+                probe_command: { type: "string" },
+                probe_script: { type: "string" },
+                dry_run: { type: "boolean", description: "Allow missing bind/bundle (preview/tests); still writes staging" },
+            },
+            required: ["name"],
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    });
+    return tools;
+}
+function asRecord(args) {
+    return args && typeof args === "object" && !Array.isArray(args) ? args : {};
+}
+function requireNonEmptyString(input, key) {
+    const value = input[key];
+    if (typeof value !== "string" || !value.trim()) {
+        throw new DingtalkDwsError("INVALID_ARGUMENT", `${key} is required`);
+    }
+    return value.trim();
+}
+function optionalPositiveInt(value, key) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
+        throw new DingtalkDwsError("INVALID_ARGUMENT", `${key} must be a positive integer`);
+    }
+    return value;
+}
+function parseSearchType(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === "all" || value === "group" || value === "user")
+        return value;
+    throw new DingtalkDwsError("INVALID_ARGUMENT", "type must be all, group, or user");
+}
+function parseRouteName(value, allowed) {
+    if (typeof value !== "string" || !allowed.includes(value)) {
+        throw new DingtalkDwsError("INVALID_ARGUMENT", `route must be one of: ${allowed.join(", ")}`);
+    }
+    return value;
+}
+function parseSendInput(input, allowedRoutes) {
+    const route = parseRouteName(input.route, allowedRoutes);
+    const title = requireNonEmptyString(input, "title");
+    const content = requireNonEmptyString(input, "content");
+    const dedupeRaw = input.dedupe_key;
+    let dedupe_key;
+    if (dedupeRaw !== undefined) {
+        if (typeof dedupeRaw !== "string")
+            throw new DingtalkDwsError("INVALID_ARGUMENT", "dedupe_key must be a string");
+        dedupe_key = dedupeRaw;
+    }
+    return { route, title, content, dedupe_key };
+}
+function assertToolAllowed(surface, name) {
+    const allowed = new Set(createToolDefinitions(surface).map((tool) => tool.name));
+    if (!allowed.has(name)) {
+        throw new DingtalkDwsError("ADAPTER_UNSUPPORTED", `Tool ${name} is not available for this adapter`);
+    }
+}
+export async function callTool(service, name, args, surface) {
+    const resolvedSurface = surface ?? resolveToolSurface(service.adapterKind());
+    try {
+        assertToolAllowed(resolvedSurface, name);
+        let result;
+        const input = asRecord(args);
+        if (name === "dingtalk_doctor")
+            result = await service.doctor();
+        else if (name === "dingtalk_auth_status")
+            result = await service.authStatus();
+        else if (name === "dingtalk_auth_login")
+            result = await service.authLogin();
+        else if (name === "dingtalk_list_routes")
+            result = service.listRoutes();
+        else if (name === "dingtalk_search_targets") {
+            result = await service.searchTargets({
+                query: requireNonEmptyString(input, "query"),
+                type: parseSearchType(input.type),
+                limit: optionalPositiveInt(input.limit, "limit"),
+            });
+        }
+        else if (name === "dingtalk_configure_route_target") {
+            const route = input.route === undefined
+                ? undefined
+                : parseRouteName(input.route, ["notify_group", "notify_user"]);
+            let type;
+            if (input.type !== undefined) {
+                if (input.type !== "group" && input.type !== "user") {
+                    throw new DingtalkDwsError("INVALID_ARGUMENT", "type must be group or user");
+                }
+                type = input.type;
+            }
+            result = await service.configureRouteTarget({
+                query: requireNonEmptyString(input, "query"),
+                route,
+                type,
+                candidate_ref: input.candidate_ref === undefined
+                    ? undefined
+                    : requireNonEmptyString(input, "candidate_ref"),
+            });
+        }
+        else if (name === "dingtalk_send") {
+            const allowed = resolvedSurface.adapter === "webhook"
+                ? ["notify_group"]
+                : ["notify_group", "notify_user"];
+            result = await service.send(parseSendInput(input, allowed));
+        }
+        else if (name === "dingtalk_patrol_setup") {
+            const optionalString = (key) => {
+                const value = input[key];
+                if (value === undefined)
+                    return undefined;
+                if (typeof value !== "string")
+                    throw new DingtalkDwsError("INVALID_ARGUMENT", `${key} must be a string`);
+                return value;
+            };
+            const optionalBool = (key) => {
+                const value = input[key];
+                if (value === undefined)
+                    return undefined;
+                if (typeof value !== "boolean")
+                    throw new DingtalkDwsError("INVALID_ARGUMENT", `${key} must be a boolean`);
+                return value;
+            };
+            result = await service.patrolSetup({
+                name: requireNonEmptyString(input, "name"),
+                cron: optionalString("cron"),
+                route: input.route === undefined
+                    ? undefined
+                    : parseRouteName(input.route, ["notify_group", "notify_user"]),
+                probe_command: optionalString("probe_command"),
+                probe_script: optionalString("probe_script"),
+                dry_run: optionalBool("dry_run"),
+            });
+        }
+        else {
+            result = { code: "INVALID_ARGUMENT", message: `Unknown tool: ${name}` };
+            return { isError: true, content: [{ type: "text", text: JSON.stringify(result) }], structuredContent: result };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(result) }], structuredContent: result };
+    }
+    catch (error) {
+        const err = asDingtalkDwsError(error);
+        const result = { code: err.code, message: err.message };
+        return { isError: true, content: [{ type: "text", text: JSON.stringify(result) }], structuredContent: result };
+    }
+}

package/dist/src/types.d.ts

@@ -0,0 +1,40 @@
+export type AdapterKind = "dws" | "webhook";
+export type RouteName = "notify_group" | "notify_user";
+export type RouteType = "group" | "user";
+export interface AppConfig {
+    adapter: AdapterKind | null;
+    adapterError?: string;
+    dwsCommand: string;
+    clientId?: string;
+    clientSecret?: string;
+    robotCode?: string;
+    webhookUrl?: string;
+    webhookSecret?: string;
+    authLoginMode: "interactive" | "manual";
+    stateDir: string;
+    targetsPath: string;
+    idempotencyPath: string;
+    timeoutMs: number;
+    maxOutputBytes: number;
+    maxTitleLength: number;
+    maxContentLength: number;
+    suppressionWindowSeconds: number;
+}
+export interface DeliveryRequest {
+    routeType: RouteType;
+    targetId: string;
+    title: string;
+    content: string;
+}
+export interface TargetCandidate {
+    type: RouteType;
+    name: string;
+    target_id: string;
+}
+/** Minimal send: route + title + content; optional dedupe_key only. */
+export interface SendInput {
+    route: RouteName;
+    title: string;
+    content: string;
+    dedupe_key?: string;
+}

package/dist/src/types.js

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

package/dist/src/version.d.ts

@@ -0,0 +1,2 @@
+export declare function mcpPackageRoot(): string;
+export declare function readPackageVersion(): string;

package/dist/src/version.js

@@ -0,0 +1,30 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+export function mcpPackageRoot() {
+    let dir = path.dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 6; i++) {
+        const pkgPath = path.join(dir, "package.json");
+        if (fs.existsSync(pkgPath)) {
+            try {
+                const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+                if (pkg.name === "dingtalk-dws-mcp")
+                    return dir;
+            }
+            catch {
+                // continue
+            }
+        }
+        dir = path.dirname(dir);
+    }
+    throw new Error("cannot locate dingtalk-dws-mcp package root");
+}
+export function readPackageVersion() {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(mcpPackageRoot(), "package.json"), "utf8"));
+        return pkg.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "dingtalk-dws-mcp",
+  "version": "1.0.0",
+  "description": "DingTalk robot notification MCP with dws readiness handshake",
+  "license": "Apache-2.0",
+  "type": "module",
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "main": "dist/src/index.js",
+  "files": [
+    "dist/src",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "dingtalk-dws-mcp": "dist/src/index.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run build && npm test",
+    "start": "node dist/src/index.js",
+    "pack:deploy": "node scripts/pack-deploy.mjs",
+    "test": "npm run build && vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "keywords": [
+    "mcp",
+    "dingtalk",
+    "dws",
+    "notification"
+  ],
+  "dependencies": {
+    "agent-compose-notify-delivery": "^1.0.0",
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  }
+}