dingtalk-dws-mcp 1.0.0

package/dist/src/server.js

@@ -0,0 +1,126 @@
+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 { loadConfig } from "./config.js";
+import { IdempotencyStore } from "./notify/idempotency-store.js";
+import { getPromptMessages, listPromptDefinitions } from "./prompts.js";
+import { DingtalkDwsService } from "./service.js";
+import { buildInstructions, callTool, createToolDefinitions, resolveToolSurface } from "./tools/registry.js";
+import { readPackageVersion } from "./version.js";
+export const MCP_SERVER_NAME = "dingtalk-dws";
+export const MCP_SERVER_VERSION = readPackageVersion();
+export function createMcpServer(service, store) {
+    let resolvedStore = store;
+    let resolvedService = service;
+    let adapter = service?.adapterKind() ?? null;
+    if (!resolvedService) {
+        const config = loadConfig();
+        adapter = config.adapter;
+        resolvedStore = resolvedStore ?? new IdempotencyStore(config.idempotencyPath);
+        resolvedService = new DingtalkDwsService(config, resolvedStore);
+    }
+    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 tools = createToolDefinitions(surface);
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [...tools] }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => (callTool(resolvedService, request.params.name, request.params.arguments ?? {}, surface)));
+    server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+        prompts: listPromptDefinitions(surface),
+    }));
+    server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+        try {
+            return getPromptMessages(request.params.name);
+        }
+        catch {
+            throw new Error(`Unknown prompt: ${request.params.name}`);
+        }
+    });
+    return { server, service: resolvedService, store: resolvedStore };
+}
+export async function runStdioServer() {
+    const { server, store } = createMcpServer();
+    const transport = new StdioServerTransport();
+    let storeClosed = false;
+    let connected = false;
+    let connectionSettled = false;
+    let shutdownPromise;
+    let resolveStopped;
+    let resolveConnectionSettled;
+    const stopped = new Promise((resolve) => {
+        resolveStopped = resolve;
+    });
+    const connectionReady = new Promise((resolve) => {
+        resolveConnectionSettled = resolve;
+    });
+    const markConnectionSettled = () => {
+        if (!connectionSettled) {
+            connectionSettled = true;
+            resolveConnectionSettled?.();
+        }
+    };
+    const closeStore = () => {
+        if (!storeClosed) {
+            store.close();
+            storeClosed = true;
+        }
+    };
+    const shutdown = (closeServer = true) => {
+        if (!shutdownPromise) {
+            shutdownPromise = (async () => {
+                try {
+                    await connectionReady;
+                    if (closeServer && connected) {
+                        await server.close();
+                    }
+                }
+                finally {
+                    closeStore();
+                    resolveStopped?.();
+                }
+            })();
+        }
+        return shutdownPromise;
+    };
+    const onInputEnd = () => {
+        void shutdown();
+    };
+    const onSignal = () => {
+        process.exitCode = 0;
+        void shutdown();
+    };
+    const onExit = () => {
+        closeStore();
+    };
+    transport.onclose = () => {
+        void shutdown(false);
+    };
+    process.stdin.once("end", onInputEnd);
+    process.stdin.once("close", onInputEnd);
+    process.once("SIGINT", onSignal);
+    process.once("SIGTERM", onSignal);
+    process.once("exit", onExit);
+    try {
+        process.stdin.resume();
+        await server.connect(transport);
+        connected = true;
+        markConnectionSettled();
+        await stopped;
+        await shutdownPromise;
+    }
+    catch (error) {
+        markConnectionSettled();
+        await shutdown(false);
+        throw error;
+    }
+    finally {
+        markConnectionSettled();
+        process.stdin.off("end", onInputEnd);
+        process.stdin.off("close", onInputEnd);
+        process.off("SIGINT", onSignal);
+        process.off("SIGTERM", onSignal);
+        process.off("exit", onExit);
+        closeStore();
+    }
+}

package/dist/src/service.d.ts

@@ -0,0 +1,33 @@
+import type { CommandRunner } from "./internal/exec.js";
+import type { AdapterKind, AppConfig, RouteName, RouteType, SendInput } from "./types.js";
+import { IdempotencyStore } from "./notify/idempotency-store.js";
+import { type PatrolSetupInput } from "./patrol/setup.js";
+export declare class DingtalkDwsService {
+    private readonly config;
+    private readonly store;
+    private readonly runner?;
+    private readonly env;
+    private readonly fetchImpl;
+    constructor(config: AppConfig, store: IdempotencyStore, runner?: CommandRunner | undefined, env?: NodeJS.ProcessEnv, fetchImpl?: typeof fetch);
+    doctor(): Promise<Record<string, unknown>>;
+    patrolSetup(input: PatrolSetupInput): Promise<Record<string, unknown>>;
+    authStatus(): Promise<Record<string, unknown>>;
+    authLogin(): Promise<Record<string, unknown>>;
+    listRoutes(): Record<string, unknown>;
+    /** Adapter used to shape the public MCP tool surface. */
+    adapterKind(): AdapterKind | null;
+    searchTargets(input: {
+        query: string;
+        type?: "all" | RouteType;
+        limit?: number;
+    }): Promise<Record<string, unknown>>;
+    configureRouteTarget(input: {
+        query: string;
+        route?: RouteName;
+        type?: RouteType;
+        candidate_ref?: string;
+    }): Promise<Record<string, unknown>>;
+    send(input: SendInput): Promise<Record<string, unknown>>;
+    private deliver;
+}
+export type { AppConfig };

package/dist/src/service.js

@@ -0,0 +1,276 @@
+import { assertAdapterConfigured, ensureStateDir } from "./config.js";
+import { searchTargets } from "./directory/search.js";
+import { sendWebhook, validateWebhookConfig } from "./delivery/webhook.js";
+import { DingtalkDwsError } from "./errors.js";
+import { dwsAuthLogin, dwsAuthStatus, probeDws } from "./internal/dws-auth-command.js";
+import { sendRobotMessage } from "./internal/dws-robot-command.js";
+import { candidateRef, isRouteConfigured, resolveRouteTarget, routeType, writeTarget } from "./notify/bind.js";
+import { validateSendContent } from "./notify/content.js";
+import { sha256 } from "./notify/idempotency-store.js";
+import { bundleFingerprintForDoctor, runPatrolSetup } from "./patrol/setup.js";
+import { readPackageVersion } from "./version.js";
+export class DingtalkDwsService {
+    config;
+    store;
+    runner;
+    env;
+    fetchImpl;
+    constructor(config, store, runner, env = process.env, fetchImpl = fetch) {
+        this.config = config;
+        this.store = store;
+        this.runner = runner;
+        this.env = env;
+        this.fetchImpl = fetchImpl;
+        ensureStateDir(config);
+    }
+    async doctor() {
+        const probe = await probeDws(this.config.dwsCommand, {
+            timeoutMs: this.config.timeoutMs,
+            maxOutputBytes: this.config.maxOutputBytes,
+            runner: this.runner,
+            env: this.env,
+        });
+        const auth = probe.installed
+            ? await dwsAuthStatus(this.config.dwsCommand, {
+                timeoutMs: this.config.timeoutMs,
+                maxOutputBytes: this.config.maxOutputBytes,
+                runner: this.runner,
+                env: this.env,
+            })
+            : { cli_available: false, authenticated: null, message: probe.message, next_action: "Install dws" };
+        const dwsReady = probe.installed && auth.authenticated === true;
+        let notifyReady = false;
+        let notifyMessage = this.config.adapterError ?? "Notify credentials are not configured";
+        if (this.config.adapter === "dws") {
+            notifyReady = Boolean(this.config.clientId && this.config.clientSecret)
+                && (isRouteConfigured(this.config, "notify_group") || isRouteConfigured(this.config, "notify_user"));
+            notifyMessage = notifyReady
+                ? "Managed notify is ready"
+                : "Configure robot credentials and bind at least one route";
+        }
+        else if (this.config.adapter === "webhook") {
+            const validation = validateWebhookConfig(this.config);
+            notifyReady = validation.valid;
+            notifyMessage = validation.message;
+        }
+        let next_action = null;
+        if (this.config.adapterError)
+            next_action = this.config.adapterError;
+        else if (!this.config.adapter)
+            next_action = "Set DINGTALK_CLIENT_ID/SECRET or DINGTALK_WEBHOOK_URL";
+        else if (this.config.adapter === "dws" && !dwsReady && !probe.installed)
+            next_action = probe.message;
+        else if (this.config.adapter === "dws" && auth.authenticated !== true) {
+            next_action = this.config.authLoginMode === "manual"
+                ? "Run `dws auth login` in a local terminal, then call dingtalk_auth_status"
+                : "Call dingtalk_auth_login";
+        }
+        else if (!notifyReady && this.config.adapter === "dws") {
+            next_action = "Call dingtalk_configure_route_target to bind notify_group or notify_user";
+        }
+        else if (!notifyReady)
+            next_action = notifyMessage;
+        else if (!dwsReady && this.config.adapter === "webhook") {
+            // Notify works; office readiness is informational only (no auth tools in webhook mode).
+            next_action = null;
+        }
+        else if (!dwsReady)
+            next_action = auth.next_action ?? probe.message;
+        return {
+            server_version: readPackageVersion(),
+            patrol_bundle: bundleFingerprintForDoctor(this.env),
+            dws: {
+                installed: probe.installed,
+                version: probe.version ?? null,
+                authenticated: auth.authenticated,
+                ready: dwsReady,
+                message: dwsReady ? "dws is ready for office tasks via Skill/shell" : auth.message,
+            },
+            notify: {
+                adapter: this.config.adapter,
+                credentials_configured: this.config.adapter === "webhook"
+                    ? Boolean(this.config.webhookUrl)
+                    : Boolean(this.config.clientId && this.config.clientSecret),
+                ready: notifyReady,
+                message: notifyMessage,
+                routes: this.config.adapter === "webhook"
+                    ? { notify_group: { configured: isRouteConfigured(this.config, "notify_group") } }
+                    : {
+                        notify_group: { configured: isRouteConfigured(this.config, "notify_group") },
+                        notify_user: { configured: isRouteConfigured(this.config, "notify_user") },
+                    },
+            },
+            next_action,
+        };
+    }
+    async patrolSetup(input) {
+        return runPatrolSetup(this.config, input, this.env);
+    }
+    async authStatus() {
+        const status = await dwsAuthStatus(this.config.dwsCommand, {
+            timeoutMs: this.config.timeoutMs,
+            maxOutputBytes: this.config.maxOutputBytes,
+            runner: this.runner,
+            env: this.env,
+        });
+        return { ...status };
+    }
+    async authLogin() {
+        return dwsAuthLogin(this.config.dwsCommand, this.config.authLoginMode, {
+            timeoutMs: this.config.timeoutMs,
+            maxOutputBytes: this.config.maxOutputBytes,
+            runner: this.runner,
+            env: this.env,
+        });
+    }
+    listRoutes() {
+        assertAdapterConfigured(this.config);
+        const names = this.config.adapter === "webhook"
+            ? ["notify_group"]
+            : ["notify_group", "notify_user"];
+        const routes = names.map((name) => ({
+            name,
+            type: routeType(name),
+            configured: isRouteConfigured(this.config, name),
+            description: name === "notify_group" ? "Notify a DingTalk group" : "Notify a DingTalk user",
+        }));
+        return {
+            adapter: this.config.adapter,
+            routes,
+        };
+    }
+    /** Adapter used to shape the public MCP tool surface. */
+    adapterKind() {
+        return this.config.adapter;
+    }
+    async searchTargets(input) {
+        assertAdapterConfigured(this.config);
+        if (this.config.adapter === "webhook") {
+            throw new DingtalkDwsError("ADAPTER_UNSUPPORTED", "search_targets is not available for webhook adapter");
+        }
+        const types = !input.type || input.type === "all" ? ["group", "user"] : [input.type];
+        const candidates = [];
+        for (const type of types) {
+            candidates.push(...await searchTargets(this.config, type, input.query, input.limit ?? 10, this.runner, this.env));
+        }
+        return {
+            candidates: candidates.map((candidate) => ({
+                type: candidate.type,
+                name: candidate.name,
+                candidate_ref: candidateRef(candidate),
+            })),
+        };
+    }
+    async configureRouteTarget(input) {
+        assertAdapterConfigured(this.config);
+        if (this.config.adapter === "webhook") {
+            throw new DingtalkDwsError("ADAPTER_UNSUPPORTED", "configure_route_target is not available for webhook adapter");
+        }
+        const searchType = input.route ? routeType(input.route) : input.type ?? "all";
+        const types = searchType === "all" ? ["group", "user"] : [searchType];
+        const candidates = [];
+        for (const type of types) {
+            candidates.push(...await searchTargets(this.config, type, input.query, input.candidate_ref ? 20 : 2, this.runner, this.env));
+        }
+        const candidate = input.candidate_ref
+            ? candidates.find((item) => candidateRef(item) === input.candidate_ref)
+            : candidates.length === 1 ? candidates[0] : undefined;
+        if (!candidate) {
+            throw new DingtalkDwsError("INVALID_ARGUMENT", "Zero or multiple candidates; confirm one candidate_ref before binding");
+        }
+        const route = input.route ?? (candidate.type === "group" ? "notify_group" : "notify_user");
+        if (routeType(route) !== candidate.type) {
+            throw new DingtalkDwsError("INVALID_ARGUMENT", "candidate type does not match route");
+        }
+        writeTarget(this.config, route, candidate.target_id);
+        return {
+            route,
+            type: candidate.type,
+            name: candidate.name,
+            candidate_ref: candidateRef(candidate),
+        };
+    }
+    async send(input) {
+        assertAdapterConfigured(this.config);
+        if (input.route !== "notify_group" && input.route !== "notify_user") {
+            throw new DingtalkDwsError("ROUTE_NOT_FOUND", "Unknown route");
+        }
+        validateSendContent(input, this.config);
+        const title = input.title.trim();
+        const content = input.content.trim();
+        if (input.dedupe_key) {
+            const key = sha256(`${input.route}\n${input.dedupe_key}`);
+            const claim = this.store.claim(key, Date.now(), this.config.suppressionWindowSeconds);
+            if (!claim.claimed) {
+                return {
+                    status: "suppressed",
+                    route: input.route,
+                    message_id: claim.messageId ?? null,
+                    deduplicated: true,
+                };
+            }
+            let recorded = false;
+            try {
+                const result = await this.deliver(input.route, title, content);
+                if (result.status !== "sent") {
+                    this.store.mark(key, result.status);
+                    recorded = true;
+                    throw deliveryError(result);
+                }
+                this.store.mark(key, result.status, result.messageId);
+                recorded = true;
+                return {
+                    status: "sent",
+                    route: input.route,
+                    message_id: result.messageId ?? null,
+                    deduplicated: false,
+                    sent_at: new Date().toISOString(),
+                };
+            }
+            catch (error) {
+                if (!recorded) {
+                    this.store.mark(key, error instanceof DingtalkDwsError && error.code !== "DELIVERY_UNKNOWN" ? "failed" : "unknown");
+                }
+                throw error;
+            }
+        }
+        const result = await this.deliver(input.route, title, content);
+        if (result.status !== "sent")
+            throw deliveryError(result);
+        return {
+            status: "sent",
+            route: input.route,
+            message_id: result.messageId ?? null,
+            deduplicated: false,
+            sent_at: new Date().toISOString(),
+        };
+    }
+    async deliver(route, title, content) {
+        const targetId = resolveRouteTarget(this.config, route);
+        const request = {
+            routeType: routeType(route),
+            targetId,
+            title,
+            content,
+        };
+        if (this.config.adapter === "webhook") {
+            return sendWebhook(this.config, request, this.fetchImpl);
+        }
+        return sendRobotMessage(this.config, request, this.runner, this.env);
+    }
+}
+const DELIVERY_CODES = [
+    "ADAPTER_UNAVAILABLE",
+    "ADAPTER_UNAUTHORIZED",
+    "ADAPTER_REJECTED",
+    "ADAPTER_UNSUPPORTED",
+    "DELIVERY_FAILED",
+    "DELIVERY_UNKNOWN",
+];
+function deliveryError(result) {
+    const code = DELIVERY_CODES.includes(result.errorCode)
+        ? result.errorCode
+        : result.status === "unknown" ? "DELIVERY_UNKNOWN" : "DELIVERY_FAILED";
+    const message = result.status === "failed" ? result.error : result.reason;
+    return new DingtalkDwsError(code, message);
+}

package/dist/src/tools/registry.d.ts

@@ -0,0 +1,49 @@
+import type { DingtalkDwsService } from "../service.js";
+import type { AdapterKind } from "../types.js";
+export type ToolSurface = {
+    adapter: AdapterKind | null;
+    authTools: boolean;
+    directoryTools: boolean;
+    listRoutes: boolean;
+    send: boolean;
+};
+export declare function resolveToolSurface(adapter: AdapterKind | null): ToolSurface;
+export declare function buildInstructions(surface: ToolSurface): string;
+type ToolDefinition = {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+};
+export declare function createToolDefinitions(surface: ToolSurface): ToolDefinition[];
+export declare function callTool(service: DingtalkDwsService, name: string, args: unknown, surface?: ToolSurface): Promise<{
+    isError: boolean;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: Record<string, unknown>;
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: Record<string, unknown>;
+    isError?: undefined;
+} | {
+    isError: boolean;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: {
+        code: import("../errors.js").DingtalkDwsErrorCode;
+        message: string;
+    };
+}>;
+export {};