bitfire-lark-mcp 1.0.0

package/dist/mcp-tool/document-tool/read-full-content/whiteboard.js

@@ -0,0 +1,174 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchWhiteboardNodes = fetchWhiteboardNodes;
+exports.formatWhiteboardNodes = formatWhiteboardNodes;
+const lark = __importStar(require("@larksuiteoapi/node-sdk"));
+const BOARD_NODES_PAGE_SIZE = 100;
+/**
+ * 拉取画板内所有节点（分页）
+ */
+async function fetchWhiteboardNodes(client, whiteboardId, options) {
+    var _a, _b, _c, _d;
+    const items = [];
+    let pageToken;
+    const baseUrl = `/open-apis/board/v1/whiteboards/${encodeURIComponent(whiteboardId)}/nodes`;
+    const doRequest = (token) => {
+        const query = new URLSearchParams({ page_size: String(BOARD_NODES_PAGE_SIZE) });
+        if (token)
+            query.set('page_token', token);
+        const url = `${baseUrl}?${query.toString()}`;
+        const params = { method: 'GET', url };
+        return options.useUAT && options.userAccessToken
+            ? client.request(params, lark.withUserAccessToken(options.userAccessToken))
+            : client.request(params);
+    };
+    try {
+        do {
+            const res = await doRequest(pageToken);
+            const data = (_a = res === null || res === void 0 ? void 0 : res.data) !== null && _a !== void 0 ? _a : res;
+            const batch = (_d = (_c = (_b = data.items) !== null && _b !== void 0 ? _b : data.nodes) !== null && _c !== void 0 ? _c : data.node_list) !== null && _d !== void 0 ? _d : [];
+            if (batch === null || batch === void 0 ? void 0 : batch.length)
+                items.push(...batch);
+            pageToken = data.has_more ? data.page_token : undefined;
+        } while (pageToken);
+    }
+    catch (_e) {
+        return items;
+    }
+    return items;
+}
+/** 从节点中提取可读文本（多字段 + 深度扫描，便于流程图/状态图） */
+function nodeToText(node) {
+    var _a, _b, _c, _d;
+    const parts = [];
+    if ((_b = (_a = node.text) === null || _a === void 0 ? void 0 : _a.elements) === null || _b === void 0 ? void 0 : _b.length) {
+        parts.push(node.text.elements.map((el) => { var _a; return (_a = el.content) !== null && _a !== void 0 ? _a : ''; }).join(''));
+    }
+    if (typeof node.content === 'string' && node.content.trim())
+        parts.push(node.content.trim());
+    if (typeof node.label === 'string' && node.label.trim())
+        parts.push(node.label.trim());
+    if (typeof node.title === 'string' && node.title.trim())
+        parts.push(node.title.trim());
+    if (typeof node.name === 'string' && node.name.trim())
+        parts.push(node.name.trim());
+    if (typeof node.body === 'string' && node.body.trim())
+        parts.push(node.body.trim());
+    if (typeof node.description === 'string' && node.description.trim())
+        parts.push(node.description.trim());
+    if (node.shape) {
+        if (typeof node.shape.text === 'string' && node.shape.text.trim())
+            parts.push(node.shape.text.trim());
+        if (typeof node.shape.label === 'string' && node.shape.label.trim())
+            parts.push(node.shape.label.trim());
+    }
+    if (Array.isArray(node.nodes)) {
+        for (const n of node.nodes) {
+            const t = oneLineText((_d = (_c = n.label) !== null && _c !== void 0 ? _c : n.text) !== null && _d !== void 0 ? _d : n.content);
+            if (t)
+                parts.push(t);
+        }
+    }
+    if (Array.isArray(node.edges)) {
+        for (const e of node.edges) {
+            const t = typeof e.label === 'string' ? e.label.trim() : '';
+            if (t)
+                parts.push(t);
+        }
+    }
+    if (parts.length)
+        return parts.join(' ');
+    const deep = deepCollectStrings(node, 4);
+    if (deep.length)
+        return deep.join(' ').slice(0, 500);
+    return '';
+}
+function oneLineText(v) {
+    if (typeof v === 'string')
+        return v.trim();
+    if (v && typeof v === 'object' && 'content' in v && typeof v.content === 'string')
+        return v.content.trim();
+    return '';
+}
+/** 深度收集对象中的短文本（跳过 ID、token 等），用于未知结构 */
+function deepCollectStrings(obj, maxDepth, depth = 0) {
+    if (depth > maxDepth || obj == null)
+        return [];
+    const out = [];
+    const skipKeys = new Set(['id', 'block_id', 'parent_id', 'token', 'node_id', 'whiteboard_id']);
+    if (typeof obj === 'string') {
+        const s = obj.trim();
+        if (s.length > 0 && s.length < 500 && !/^[\d\s\-_:.]+$/.test(s))
+            out.push(s);
+        return out;
+    }
+    if (Array.isArray(obj)) {
+        for (const v of obj)
+            out.push(...deepCollectStrings(v, maxDepth, depth + 1));
+        return out;
+    }
+    if (typeof obj === 'object') {
+        for (const [k, v] of Object.entries(obj)) {
+            if (skipKeys.has(k))
+                continue;
+            out.push(...deepCollectStrings(v, maxDepth, depth + 1));
+        }
+    }
+    return out;
+}
+/** 将画板节点列表格式化为可读文本（含类型标注，便于状态流转图） */
+function formatWhiteboardNodes(nodes) {
+    var _a, _b;
+    if (!nodes.length)
+        return '（画板无节点）';
+    const lines = [];
+    let hasAny = false;
+    for (const node of nodes) {
+        const text = nodeToText(node).trim();
+        const type = String((_b = (_a = node.resource_type) !== null && _a !== void 0 ? _a : node.node_type) !== null && _b !== void 0 ? _b : '').trim();
+        const tag = type ? `[${type}]` : '节点';
+        if (text) {
+            lines.push(`- ${tag} ${text}`);
+            hasAny = true;
+        }
+        else {
+            lines.push(`- ${tag} （无文本）`);
+        }
+    }
+    if (!hasAny)
+        lines.push('（以上节点未解析出文本，可能为图形/连线；若为流程图可尝试在画板中为形状添加文字说明）');
+    return lines.join('\n');
+}

package/dist/mcp-tool/document-tool/recall/index.d.ts

@@ -0,0 +1,2 @@
+import { DocumentRecallTool } from "./type";
+export declare const RecallTool: DocumentRecallTool;

package/dist/mcp-tool/document-tool/recall/index.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RecallTool = void 0;
+const zod_1 = require("zod");
+const request_1 = require("./request");
+const searchParamsSchema = {
+    query: zod_1.z.string().describe("user input"),
+};
+exports.RecallTool = {
+    name: "openplatform_developer_document_recall",
+    description: "Recall for relevant documents in all of the Feishu/Lark Open Platform Developer Documents based on user input.",
+    schema: searchParamsSchema,
+    handler: async (params, options) => {
+        const { query } = params;
+        try {
+            const results = await (0, request_1.recallDeveloperDocument)(query, options);
+            // Return results
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: results.length ? `Find ${results.length} results:\n${results.join("\n\n")}` : "No results found",
+                    }
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `Search failed:${error instanceof Error ? error.message : 'Unknown error'}`,
+                    },
+                ],
+            };
+        }
+    }
+};

package/dist/mcp-tool/document-tool/recall/request.d.ts

@@ -0,0 +1,2 @@
+import { DocumentRecallToolOptions } from './type';
+export declare const recallDeveloperDocument: (query: string, options: DocumentRecallToolOptions) => Promise<any>;

package/dist/mcp-tool/document-tool/recall/request.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recallDeveloperDocument = void 0;
+const http_instance_1 = require("../../../utils/http-instance");
+const recallDeveloperDocument = async (query, options) => {
+    try {
+        const { domain, count = 3 } = options;
+        // Get Feishu search API endpoint
+        const searchEndpoint = `${domain}/document_portal/v1/recall`;
+        const payload = {
+            question: query,
+        };
+        // Send network request to Feishu search API
+        const response = await http_instance_1.commonHttpInstance.post(searchEndpoint, payload, {
+            timeout: 10000,
+        });
+        // Process search results
+        let results = response.data.chunks || [];
+        return results.slice(0, count);
+    }
+    catch (error) {
+        throw error;
+    }
+};
+exports.recallDeveloperDocument = recallDeveloperDocument;

package/dist/mcp-tool/document-tool/recall/type.d.ts

@@ -0,0 +1,19 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types";
+import type { z } from "zod";
+export interface DocumentRecallToolOptions {
+    domain?: string;
+    smallToBig?: boolean;
+    count?: number;
+    multiQuery?: boolean;
+    timeout?: number;
+}
+export interface DocumentRecallTool {
+    name: string;
+    description: string;
+    schema: {
+        query: z.ZodType<string>;
+    };
+    handler: (params: {
+        query: string;
+    }, options: DocumentRecallToolOptions) => Promise<CallToolResult>;
+}

package/dist/mcp-tool/document-tool/recall/type.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/mcp-tool/index.d.ts

@@ -0,0 +1,5 @@
+export * from './mcp-tool';
+export * from './tools';
+export * from './types';
+export * from './constants';
+export * from './document-tool';

package/dist/mcp-tool/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./mcp-tool"), exports);
+__exportStar(require("./tools"), exports);
+__exportStar(require("./types"), exports);
+__exportStar(require("./constants"), exports);
+__exportStar(require("./document-tool"), exports);

package/dist/mcp-tool/mcp-tool.d.ts

@@ -0,0 +1,52 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { LarkMcpToolOptions, McpTool, SettableValue, ToolNameCase } from './types';
+import { LarkAuthHandler } from '../auth';
+/**
+ * Feishu/Lark MCP
+ */
+export declare class LarkMcpTool {
+    private client;
+    private userAccessToken;
+    private auth;
+    private options;
+    private allTools;
+    /**
+     * Feishu/Lark MCP
+     * @param options Feishu/Lark Client Options
+     */
+    constructor(options: LarkMcpToolOptions, auth?: LarkAuthHandler);
+    /**
+     * Get MCP Tools
+     * @returns MCP Tool Definition Array
+     */
+    getTools(): McpTool[];
+    /**
+     * Update User Access Token
+     * @param userAccessToken User Access Token
+     */
+    updateUserAccessToken(userAccessToken: string | SettableValue): void;
+    private getUserAccessToken;
+    private setUserAccessToken;
+    reAuthorize(): Promise<{
+        userAccessToken?: string;
+        authorizeUrl?: string;
+    }>;
+    ensureGetUserAccessToken(): Promise<{
+        userAccessToken?: string;
+        authorizeUrl?: string;
+    }>;
+    getReAuthorizeMessage(authorizeUrl?: string, errorCode?: number, errorText?: string): {
+        isError: boolean;
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    };
+    /**
+     * Register Tools to MCP Server
+     * @param server MCP Server Instance
+     */
+    registerMcpServer(server: McpServer, options?: {
+        toolNameCase?: ToolNameCase;
+    }): void;
+}

package/dist/mcp-tool/mcp-tool.js

@@ -0,0 +1,198 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LarkMcpTool = void 0;
+const node_sdk_1 = require("@larksuiteoapi/node-sdk");
+const types_1 = require("./types");
+const tools_1 = require("./tools");
+const constants_1 = require("./constants");
+const utils_1 = require("./utils");
+const auth_1 = require("../auth");
+const safe_json_parse_1 = require("../utils/safe-json-parse");
+const constants_2 = require("../utils/constants");
+const logger_1 = require("../utils/logger");
+/**
+ * Feishu/Lark MCP
+ */
+class LarkMcpTool {
+    /**
+     * Feishu/Lark MCP
+     * @param options Feishu/Lark Client Options
+     */
+    constructor(options, auth) {
+        var _a;
+        // Lark Client
+        this.client = null;
+        // User Access Token
+        this.userAccessToken = {};
+        // All Tools
+        this.allTools = [];
+        this.options = options;
+        this.auth = auth;
+        if (options.client) {
+            this.client = options.client;
+        }
+        else if (options.appId && options.appSecret) {
+            this.client = new node_sdk_1.Client({ appId: options.appId, appSecret: options.appSecret, ...options });
+        }
+        const isZH = ((_a = options.toolsOptions) === null || _a === void 0 ? void 0 : _a.language) === 'zh';
+        const filterOptions = {
+            allowTools: constants_1.defaultToolNames,
+            tokenMode: this.options.tokenMode || types_1.TokenMode.AUTO,
+            ...options.toolsOptions,
+        };
+        this.allTools = (0, utils_1.filterTools)(isZH ? tools_1.AllToolsZh : tools_1.AllTools, filterOptions);
+        logger_1.logger.info(`[LarkMcpTool] Initialized with ${this.allTools.length} tools, tokenMode: ${this.options.tokenMode}`);
+    }
+    /**
+     * Get MCP Tools
+     * @returns MCP Tool Definition Array
+     */
+    getTools() {
+        return this.allTools;
+    }
+    /**
+     * Update User Access Token
+     * @param userAccessToken User Access Token
+     */
+    updateUserAccessToken(userAccessToken) {
+        if (typeof userAccessToken === 'string') {
+            this.userAccessToken.value = userAccessToken;
+        }
+        else {
+            this.userAccessToken = userAccessToken;
+        }
+    }
+    async getUserAccessToken() {
+        if (this.userAccessToken.getter) {
+            return await this.userAccessToken.getter();
+        }
+        return this.userAccessToken.value;
+    }
+    async setUserAccessToken(userAccessToken) {
+        this.userAccessToken.value = userAccessToken;
+        if (this.userAccessToken.setter) {
+            await this.userAccessToken.setter(userAccessToken);
+        }
+    }
+    async reAuthorize() {
+        const userAccessToken = await this.getUserAccessToken();
+        // if not enable oauth mode, return empty object
+        if (!this.auth || !this.options.oauth) {
+            return {};
+        }
+        logger_1.logger.info(`[LarkMcpTool] Re-authorizing user access token`);
+        const { authorizeUrl, accessToken } = await this.auth.reAuthorize(userAccessToken);
+        if (accessToken) {
+            logger_1.logger.info(`[LarkMcpTool] Successfully re-authorized user access token`);
+            this.setUserAccessToken(accessToken);
+            return { userAccessToken: accessToken };
+        }
+        return { authorizeUrl };
+    }
+    async ensureGetUserAccessToken() {
+        var _a;
+        const userAccessToken = await this.getUserAccessToken();
+        if (!this.auth) {
+            return { userAccessToken };
+        }
+        const { valid, isExpired, token } = await (0, auth_1.isTokenValid)(userAccessToken);
+        if (valid) {
+            return { userAccessToken };
+        }
+        logger_1.logger.info(`[LarkMcpTool] UserAccessToken is invalid or expired, trying to get new token...`);
+        try {
+            if (isExpired && ((_a = token === null || token === void 0 ? void 0 : token.extra) === null || _a === void 0 ? void 0 : _a.refreshToken)) {
+                logger_1.logger.info(`[LarkMcpTool] UserAccessToken is expired, trying to use refreshToken to refresh...`);
+                const newToken = await this.auth.refreshToken(token.token);
+                if (newToken === null || newToken === void 0 ? void 0 : newToken.access_token) {
+                    this.setUserAccessToken(newToken.access_token);
+                    return { userAccessToken: newToken.access_token };
+                }
+            }
+        }
+        catch (error) {
+            logger_1.logger.error(`[LarkMcpTool] Failed to refreshToken: ${error}`);
+        }
+        // reAuthorize
+        return await this.reAuthorize();
+    }
+    getReAuthorizeMessage(authorizeUrl, errorCode, errorText) {
+        var _a;
+        const errorMessage = errorCode === constants_2.OAPI_MCP_ERROR_CODE.USER_ACCESS_TOKEN_UNAUTHORIZED
+            ? 'Current user_access_token lacks required permissions. Please ensure the corresponding permissions are enabled in the developer console, then re-authorize using the following Authorization URL or login command.'
+            : 'Current user_access_token is invalid or expired';
+        const instruction = authorizeUrl
+            ? [
+                'Please open the following URL in your browser to complete the authorization:',
+                `Note: Ensure the redirect URL (${(_a = this.auth) === null || _a === void 0 ? void 0 : _a.callbackUrl}) is configured in your app's security settings.`,
+                `   If not configured, go to: ${this.options.domain}/app/${this.options.appId}/safe`,
+                'Authorization URL:',
+                authorizeUrl,
+                'This authorization link expires in 60 seconds. Generating a new link will immediately invalidate this one.',
+            ]
+                .join('\n')
+                .trim()
+            : '';
+        const reAuthorizeMessage = {
+            errorCode,
+            errorMessage,
+            instruction,
+            rawErrorText: errorText,
+        };
+        return {
+            isError: true,
+            content: [{ type: 'text', text: JSON.stringify(reAuthorizeMessage) }],
+        };
+    }
+    /**
+     * Register Tools to MCP Server
+     * @param server MCP Server Instance
+     */
+    registerMcpServer(server, options) {
+        for (const tool of this.allTools) {
+            server.tool((0, utils_1.caseTransf)(tool.name, options === null || options === void 0 ? void 0 : options.toolNameCase), tool.description, tool.schema, async (params) => {
+                var _a, _b, _c, _d, _e;
+                try {
+                    if (!this.client) {
+                        return {
+                            isError: true,
+                            content: [{ type: 'text', text: JSON.stringify({ msg: 'Client not initialized' }) }],
+                        };
+                    }
+                    const handler = tool.customHandler || utils_1.larkOapiHandler;
+                    const shouldUseUAT = (0, utils_1.getShouldUseUAT)(this.options.tokenMode, (_a = params === null || params === void 0 ? void 0 : params.useUAT) !== null && _a !== void 0 ? _a : false);
+                    if (shouldUseUAT) {
+                        const { userAccessToken, authorizeUrl } = await this.ensureGetUserAccessToken();
+                        if (!userAccessToken) {
+                            return this.getReAuthorizeMessage(authorizeUrl);
+                        }
+                        logger_1.logger.info(`[LarkMcpTool] Calling tool: ${tool.name}`);
+                        const result = await handler(this.client, { ...params, useUAT: shouldUseUAT }, { userAccessToken, tool });
+                        const errorCode = (0, safe_json_parse_1.safeJsonParse)((_c = (_b = result.content) === null || _b === void 0 ? void 0 : _b[0]) === null || _c === void 0 ? void 0 : _c.text, { code: 0 }).code;
+                        if (result.isError &&
+                            [
+                                constants_2.OAPI_MCP_ERROR_CODE.USER_ACCESS_TOKEN_UNAUTHORIZED,
+                                constants_2.OAPI_MCP_ERROR_CODE.USER_ACCESS_TOKEN_INVALID,
+                            ].includes(errorCode)) {
+                            logger_1.logger.info(`[LarkMcpTool] User access token unauthorized the scope or invalid, reAuthorize, errorCode: ${errorCode}`);
+                            // user access token unauthorized the scope or invalid, reAuthorize
+                            const { authorizeUrl } = await this.reAuthorize();
+                            return this.getReAuthorizeMessage(authorizeUrl, errorCode, (_e = (_d = result.content) === null || _d === void 0 ? void 0 : _d[0]) === null || _e === void 0 ? void 0 : _e.text);
+                        }
+                        return result;
+                    }
+                    logger_1.logger.info(`[LarkMcpTool] Calling tool: ${tool.name}`);
+                    return handler(this.client, { ...params, useUAT: shouldUseUAT }, { tool });
+                }
+                catch (error) {
+                    logger_1.logger.error(`[LarkMcpTool] Failed to call tool: ${tool.name}, error: ${error}`);
+                    return {
+                        isError: true,
+                        content: [{ type: 'text', text: JSON.stringify(error === null || error === void 0 ? void 0 : error.message) }],
+                    };
+                }
+            });
+        }
+    }
+}
+exports.LarkMcpTool = LarkMcpTool;

package/dist/mcp-tool/tools/en/builtin-tools/docx/builtin.d.ts

@@ -0,0 +1,6 @@
+import { McpTool } from '../../../../types';
+export type docxBuiltinToolName = 'docx.builtin.search' | 'docx.builtin.import' | 'docx.builtin.readFullContent';
+export declare const larkDocxBuiltinSearchTool: McpTool;
+export declare const larkDocxBuiltinImportTool: McpTool;
+export declare const larkDocxBuiltinReadFullContentTool: McpTool;
+export declare const docxBuiltinTools: McpTool[];