cc-lark 0.1.1

package/src/tools/doc/fetch.ts

@@ -0,0 +1,149 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * feishu_fetch_doc tool - Get document content.
+ *
+ * Fetches Feishu document content, returning title and Markdown content.
+ * Supports pagination for large documents.
+ *
+ * Adapted from openclaw-lark for MCP Server architecture.
+ */
+
+import { z } from 'zod';
+import type { ToolRegistry } from '../index.js';
+import { LarkClient } from '../../core/lark-client.js';
+import { getValidAccessToken, NeedAuthorizationError } from '../../core/uat-client.js';
+import { callMcpTool, json, jsonError, processMcpResult, type ToolResult } from './shared.js';
+import { logger } from '../../utils/logger.js';
+
+const log = logger('tools:doc:fetch');
+
+// ---------------------------------------------------------------------------
+// Input schema
+// ---------------------------------------------------------------------------
+
+const fetchDocSchema = {
+  doc_id: z.string().describe('Document ID or URL (supports auto-parsing)'),
+  offset: z
+    .number()
+    .int()
+    .min(0)
+    .optional()
+    .describe('Character offset (optional, default 0). Use for paginating large documents.'),
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .optional()
+    .describe('Maximum characters to return (optional). Use only when pagination is requested.'),
+};
+
+// ---------------------------------------------------------------------------
+// Tool registration
+// ---------------------------------------------------------------------------
+
+/**
+ * Register the feishu_fetch_doc tool.
+ */
+export function registerFetchDocTool(registry: ToolRegistry): void {
+  registry.register({
+    name: 'feishu_fetch_doc',
+    description: [
+      'Fetch Feishu document content, returning title and Markdown format.',
+      '',
+      'Usage:',
+      '- Provide doc_id (document ID or full URL)',
+      '- Use offset and limit for paginating large documents',
+      '',
+      'Parameters:',
+      '- doc_id: Document ID or URL (required)',
+      '- offset: Character offset for pagination (optional, default 0)',
+      '- limit: Maximum characters to return (optional)',
+      '',
+      'Returns:',
+      '- { title, content, has_more? } where content is Markdown text',
+      '',
+      'Requires OAuth authorization (use feishu_oauth tool first).',
+    ].join('\n'),
+    inputSchema: fetchDocSchema,
+    handler: async (args, context) => {
+      return handleFetchDoc(args, context);
+    },
+  });
+
+  log.debug('feishu_fetch_doc tool registered');
+}
+
+// ---------------------------------------------------------------------------
+// Handler
+// ---------------------------------------------------------------------------
+
+async function handleFetchDoc(
+  args: unknown,
+  context: { larkClient: LarkClient | null; config: import('../../core/types.js').FeishuConfig }
+): Promise<ToolResult> {
+  const p = args as Record<string, unknown>;
+  const { larkClient, config } = context;
+
+  if (!larkClient) {
+    return jsonError('LarkClient not initialized. Check FEISHU_APP_ID and FEISHU_APP_SECRET.');
+  }
+
+  const { appId, appSecret, brand } = config;
+  if (!appId || !appSecret) {
+    return jsonError('Missing FEISHU_APP_ID or FEISHU_APP_SECRET.');
+  }
+
+  // Get the first stored user token
+  const { listStoredTokens } = await import('../../core/token-store.js');
+  const tokens = await listStoredTokens(appId);
+  if (tokens.length === 0) {
+    return jsonError(
+      'No user authorization found. Please use the feishu_oauth tool with action="authorize" to authorize a user first.'
+    );
+  }
+
+  const userOpenId = tokens[0].userOpenId;
+
+  try {
+    const accessToken = await getValidAccessToken({
+      userOpenId,
+      appId,
+      appSecret,
+      domain: brand ?? 'feishu',
+    });
+
+    log.info('Fetching document', {
+      doc_id: p.doc_id,
+      offset: p.offset,
+      limit: p.limit,
+    });
+
+    // Build MCP tool arguments
+    const mcpArgs: Record<string, unknown> = {
+      doc_id: p.doc_id,
+    };
+    if (p.offset !== undefined) mcpArgs.offset = p.offset;
+    if (p.limit !== undefined) mcpArgs.limit = p.limit;
+
+    // Generate a unique tool call ID
+    const toolCallId = `fetch-doc-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+    // Call the MCP endpoint
+    const result = await callMcpTool('fetch-doc', mcpArgs, toolCallId, accessToken);
+
+    log.info('Document fetched');
+
+    return processMcpResult(result);
+  } catch (err) {
+    if (err instanceof NeedAuthorizationError) {
+      return jsonError(
+        `User authorization required or expired. Please use feishu_oauth tool with action="authorize" to re-authorize.`,
+        { userOpenId }
+      );
+    }
+    log.error('Fetch document failed', { error: err instanceof Error ? err.message : String(err) });
+    return jsonError(err instanceof Error ? err.message : String(err));
+  }
+}

package/src/tools/doc/index.ts

@@ -0,0 +1,38 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Doc Tools Index
+ *
+ * Document tools for Feishu/Lark.
+ * Adapted from openclaw-lark for MCP Server architecture.
+ *
+ * Tools:
+ * - feishu_create_doc: Create new docx document from Markdown
+ * - feishu_fetch_doc: Get document content
+ * - feishu_update_doc: Update document content
+ */
+
+import type { ToolRegistry } from '../index.js';
+import { registerCreateDocTool } from './create.js';
+import { registerFetchDocTool } from './fetch.js';
+import { registerUpdateDocTool } from './update.js';
+import { logger } from '../../utils/logger.js';
+
+const log = logger('tools:doc');
+
+// Re-export submodules for external use
+export * from './shared.js';
+
+/**
+ * Register all Doc tools with the given registry.
+ */
+export function registerDocTools(registry: ToolRegistry): void {
+  registerCreateDocTool(registry);
+  registerFetchDocTool(registry);
+  registerUpdateDocTool(registry);
+
+  log.info('Doc tools registered', {
+    tools: ['feishu_create_doc', 'feishu_fetch_doc', 'feishu_update_doc'].join(', '),
+  });
+}

package/src/tools/doc/shared.ts

@@ -0,0 +1,228 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Shared utilities for Doc tools.
+ *
+ * Adapted from openclaw-lark for MCP Server architecture.
+ * - Removed OpenClaw runtime dependencies
+ * - Uses direct MCP endpoint calls with user access token
+ */
+
+import { logger } from '../../utils/logger.js';
+import { getUserAgent } from '../../core/version.js';
+
+const log = logger('tools:doc:shared');
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** MCP JSON-RPC success response */
+export interface McpRpcSuccess {
+  jsonrpc: '2.0';
+  id: number | string;
+  result: unknown;
+}
+
+/** MCP JSON-RPC error response */
+export interface McpRpcError {
+  jsonrpc: '2.0';
+  id: number | string | null;
+  error: { code: number; message: string; data?: unknown };
+}
+
+export type McpRpcResponse = McpRpcSuccess | McpRpcError;
+
+/** Tool result type that matches MCP SDK expectations. */
+export type ToolResult = {
+  content: Array<{ type: 'text'; text: string }>;
+  isError?: boolean;
+};
+
+// ---------------------------------------------------------------------------
+// MCP endpoint configuration
+// ---------------------------------------------------------------------------
+
+/** Default MCP endpoint for Feishu */
+const DEFAULT_MCP_ENDPOINT = 'https://mcp.feishu.cn/mcp';
+
+/**
+ * Get the MCP endpoint URL.
+ * Priority: FEISHU_MCP_ENDPOINT env var > default
+ */
+export function getMcpEndpoint(): string {
+  return process.env.FEISHU_MCP_ENDPOINT?.trim() || DEFAULT_MCP_ENDPOINT;
+}
+
+/**
+ * Build authorization header for MCP requests.
+ */
+function buildAuthHeader(): string | undefined {
+  const token = process.env.FEISHU_MCP_BEARER_TOKEN?.trim() || process.env.FEISHU_MCP_TOKEN?.trim();
+
+  if (!token) return undefined;
+  return token.toLowerCase().startsWith('bearer ') ? token : `Bearer ${token}`;
+}
+
+// ---------------------------------------------------------------------------
+// JSON-RPC utilities
+// ---------------------------------------------------------------------------
+
+/**
+ * Check if a value is a plain object (not null, not array).
+ */
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null;
+}
+
+/**
+ * Recursively unwrap JSON-RPC result envelopes.
+ * Some MCP gateways wrap the result in additional JSON-RPC envelopes.
+ */
+export function unwrapJsonRpcResult(v: unknown): unknown {
+  if (!isRecord(v)) return v;
+
+  const hasJsonRpc = typeof v.jsonrpc === 'string';
+  const hasId = 'id' in v;
+  const hasResult = 'result' in v;
+  const hasError = 'error' in v;
+
+  if (hasJsonRpc && (hasResult || hasError)) {
+    if (hasError) {
+      const err = v.error;
+      if (isRecord(err) && typeof err.message === 'string') {
+        throw new Error(err.message);
+      }
+      throw new Error('MCP returned error, but could not parse message');
+    }
+    return unwrapJsonRpcResult(v.result);
+  }
+
+  // Some implementations wrap without jsonrpc field
+  if (!hasJsonRpc && !hasId && hasResult && !hasError) {
+    return unwrapJsonRpcResult(v.result);
+  }
+
+  return v;
+}
+
+// ---------------------------------------------------------------------------
+// MCP client
+// ---------------------------------------------------------------------------
+
+/**
+ * Call an MCP tool on the Feishu MCP endpoint.
+ *
+ * @param name - MCP tool name (e.g., 'create-doc', 'fetch-doc')
+ * @param args - Tool arguments
+ * @param toolCallId - Unique ID for this tool call
+ * @param uat - User access token
+ * @returns Tool result
+ */
+export async function callMcpTool(
+  name: string,
+  args: Record<string, unknown>,
+  toolCallId: string,
+  uat: string
+): Promise<unknown> {
+  const endpoint = getMcpEndpoint();
+  const auth = buildAuthHeader();
+
+  const body = {
+    jsonrpc: '2.0',
+    id: toolCallId,
+    method: 'tools/call',
+    params: {
+      name,
+      arguments: args,
+    },
+  };
+
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+    'X-Lark-MCP-UAT': uat,
+    'X-Lark-MCP-Allowed-Tools': name,
+    'User-Agent': getUserAgent(),
+  };
+  if (auth) headers.authorization = auth;
+
+  log.debug(`Calling MCP tool: ${name}`, { toolCallId, endpoint });
+
+  const res = await fetch(endpoint, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify(body),
+  });
+
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`MCP HTTP ${res.status} ${res.statusText}: ${text.slice(0, 4000)}`);
+  }
+
+  let data: McpRpcResponse;
+  try {
+    data = JSON.parse(text) as McpRpcResponse;
+  } catch {
+    throw new Error(`MCP returned non-JSON: ${text.slice(0, 4000)}`);
+  }
+
+  if ('error' in data) {
+    throw new Error(`MCP error ${data.error.code}: ${data.error.message}`);
+  }
+
+  return unwrapJsonRpcResult(data.result);
+}
+
+// ---------------------------------------------------------------------------
+// Result formatting
+// ---------------------------------------------------------------------------
+
+/**
+ * Format a successful tool result.
+ */
+export function json(data: unknown): ToolResult {
+  return {
+    content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+  };
+}
+
+/**
+ * Format an error tool result.
+ */
+export function jsonError(message: string, details?: unknown): ToolResult {
+  return {
+    content: [{ type: 'text', text: JSON.stringify({ error: message, details }, null, 2) }],
+    isError: true,
+  };
+}
+
+/**
+ * Process MCP tool result into MCP content format.
+ * Handles the { content: [{ type, text }] } format from MCP tools/call.
+ */
+export function processMcpResult(result: unknown): ToolResult {
+  // MCP tools/call returns { content: [{ type, text }] } format
+  // Extract the text content and parse if JSON
+  if (isRecord(result) && Array.isArray((result as Record<string, unknown>).content)) {
+    const mcpContent = (result as Record<string, unknown>).content as Array<{
+      type: string;
+      text: string;
+    }>;
+    let details: unknown = result;
+    if (mcpContent.length === 1 && mcpContent[0]?.type === 'text') {
+      try {
+        details = JSON.parse(mcpContent[0].text);
+      } catch {
+        // text is not JSON, keep original result
+      }
+    }
+    return {
+      content: mcpContent.map((c) => ({
+        type: 'text' as const,
+        text: c.text,
+      })),
+    };
+  }
+  return json(result);
+}

package/src/tools/doc/update.ts

@@ -0,0 +1,240 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * feishu_update_doc tool - Update document content.
+ *
+ * Updates Feishu document with various modes:
+ * - overwrite: Replace entire document
+ * - append: Add content at the end
+ * - replace_range: Replace a selected range
+ * - replace_all: Replace all occurrences of text
+ * - insert_before: Insert content before a selection
+ * - insert_after: Insert content after a selection
+ * - delete_range: Delete a selected range
+ *
+ * Supports async task status checking via task_id.
+ *
+ * Adapted from openclaw-lark for MCP Server architecture.
+ */
+
+import { z } from 'zod';
+import type { ToolRegistry } from '../index.js';
+import { LarkClient } from '../../core/lark-client.js';
+import { getValidAccessToken, NeedAuthorizationError } from '../../core/uat-client.js';
+import { callMcpTool, json, jsonError, processMcpResult, type ToolResult } from './shared.js';
+import { logger } from '../../utils/logger.js';
+
+const log = logger('tools:doc:update');
+
+// ---------------------------------------------------------------------------
+// Input schema
+// ---------------------------------------------------------------------------
+
+const updateModeSchema = z.enum([
+  'overwrite',
+  'append',
+  'replace_range',
+  'replace_all',
+  'insert_before',
+  'insert_after',
+  'delete_range',
+]);
+
+const updateDocSchema = {
+  doc_id: z.string().optional().describe('Document ID or URL'),
+  markdown: z.string().optional().describe('Markdown content'),
+  mode: updateModeSchema.describe(
+    'Update mode: overwrite, append, replace_range, replace_all, insert_before, insert_after, delete_range (required)'
+  ),
+  selection_with_ellipsis: z
+    .string()
+    .optional()
+    .describe('Selection expression: start_content...end_content (mutually exclusive with selection_by_title)'),
+  selection_by_title: z
+    .string()
+    .optional()
+    .describe('Title selection: e.g., ## Section Title (mutually exclusive with selection_with_ellipsis)'),
+  new_title: z.string().optional().describe('New document title (optional)'),
+  task_id: z
+    .string()
+    .optional()
+    .describe('Async task ID for checking task status (optional)'),
+};
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+function validateUpdateDocParams(p: Record<string, unknown>): void {
+  // If task_id is provided, we're just querying status
+  if (p.task_id) return;
+
+  // For update operations, doc_id is required
+  if (!p.doc_id) {
+    throw new Error('update-doc: doc_id is required when not providing task_id');
+  }
+
+  // Mode is required
+  if (!p.mode) {
+    throw new Error('update-doc: mode is required');
+  }
+
+  const mode = p.mode as string;
+
+  // Selection modes require exactly one selection parameter
+  const selectionModes = ['replace_range', 'insert_before', 'insert_after', 'delete_range'];
+  if (selectionModes.includes(mode)) {
+    const hasEllipsis = Boolean(p.selection_with_ellipsis);
+    const hasTitle = Boolean(p.selection_by_title);
+    if ((hasEllipsis && hasTitle) || (!hasEllipsis && !hasTitle)) {
+      throw new Error(
+        'update-doc: For modes replace_range/insert_before/insert_after/delete_range, ' +
+          'exactly one of selection_with_ellipsis or selection_by_title must be provided'
+      );
+    }
+  }
+
+  // delete_range doesn't need markdown
+  const needsMarkdown = mode !== 'delete_range';
+  if (needsMarkdown && !p.markdown) {
+    throw new Error(`update-doc: markdown is required for mode=${mode}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Tool registration
+// ---------------------------------------------------------------------------
+
+/**
+ * Register the feishu_update_doc tool.
+ */
+export function registerUpdateDocTool(registry: ToolRegistry): void {
+  registry.register({
+    name: 'feishu_update_doc',
+    description: [
+      'Update a Feishu document with various modes.',
+      '',
+      'Modes:',
+      '- overwrite: Replace entire document content',
+      '- append: Add content at the end',
+      '- replace_range: Replace selected text range',
+      '- replace_all: Replace all occurrences of text',
+      '- insert_before: Insert content before selection',
+      '- insert_after: Insert content after selection',
+      '- delete_range: Delete selected range',
+      '',
+      'Selection methods (for range-based modes):',
+      '- selection_with_ellipsis: "start_text...end_text" pattern',
+      '- selection_by_title: "## Section Title" to select by heading',
+      '',
+      'Parameters:',
+      '- doc_id: Document ID or URL (required for update)',
+      '- mode: Update mode (required)',
+      '- markdown: New content (required for most modes)',
+      '- selection_with_ellipsis: Range selection pattern',
+      '- selection_by_title: Title-based selection',
+      '- new_title: New document title (optional)',
+      '- task_id: Async task ID for status check',
+      '',
+      'Returns:',
+      '- { task_id } for async operations',
+      '- { status, result? } for task_id queries',
+      '',
+      'Requires OAuth authorization (use feishu_oauth tool first).',
+    ].join('\n'),
+    inputSchema: updateDocSchema,
+    handler: async (args, context) => {
+      return handleUpdateDoc(args, context);
+    },
+  });
+
+  log.debug('feishu_update_doc tool registered');
+}
+
+// ---------------------------------------------------------------------------
+// Handler
+// ---------------------------------------------------------------------------
+
+async function handleUpdateDoc(
+  args: unknown,
+  context: { larkClient: LarkClient | null; config: import('../../core/types.js').FeishuConfig }
+): Promise<ToolResult> {
+  const p = args as Record<string, unknown>;
+  const { larkClient, config } = context;
+
+  if (!larkClient) {
+    return jsonError('LarkClient not initialized. Check FEISHU_APP_ID and FEISHU_APP_SECRET.');
+  }
+
+  const { appId, appSecret, brand } = config;
+  if (!appId || !appSecret) {
+    return jsonError('Missing FEISHU_APP_ID or FEISHU_APP_SECRET.');
+  }
+
+  // Validate parameters
+  try {
+    validateUpdateDocParams(p);
+  } catch (err) {
+    return jsonError(err instanceof Error ? err.message : String(err));
+  }
+
+  // Get the first stored user token
+  const { listStoredTokens } = await import('../../core/token-store.js');
+  const tokens = await listStoredTokens(appId);
+  if (tokens.length === 0) {
+    return jsonError(
+      'No user authorization found. Please use the feishu_oauth tool with action="authorize" to authorize a user first.'
+    );
+  }
+
+  const userOpenId = tokens[0].userOpenId;
+
+  try {
+    const accessToken = await getValidAccessToken({
+      userOpenId,
+      appId,
+      appSecret,
+      domain: brand ?? 'feishu',
+    });
+
+    log.info('Updating document', {
+      doc_id: p.doc_id,
+      mode: p.mode,
+      has_markdown: !!p.markdown,
+      selection_with_ellipsis: p.selection_with_ellipsis ? '(provided)' : undefined,
+      selection_by_title: p.selection_by_title,
+      new_title: p.new_title,
+      task_id: p.task_id,
+    });
+
+    // Build MCP tool arguments
+    const mcpArgs: Record<string, unknown> = {};
+    if (p.doc_id) mcpArgs.doc_id = p.doc_id;
+    if (p.markdown) mcpArgs.markdown = p.markdown;
+    if (p.mode) mcpArgs.mode = p.mode;
+    if (p.selection_with_ellipsis) mcpArgs.selection_with_ellipsis = p.selection_with_ellipsis;
+    if (p.selection_by_title) mcpArgs.selection_by_title = p.selection_by_title;
+    if (p.new_title) mcpArgs.new_title = p.new_title;
+    if (p.task_id) mcpArgs.task_id = p.task_id;
+
+    // Generate a unique tool call ID
+    const toolCallId = `update-doc-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+    // Call the MCP endpoint
+    const result = await callMcpTool('update-doc', mcpArgs, toolCallId, accessToken);
+
+    log.info('Document updated/task queried');
+
+    return processMcpResult(result);
+  } catch (err) {
+    if (err instanceof NeedAuthorizationError) {
+      return jsonError(
+        `User authorization required or expired. Please use feishu_oauth tool with action="authorize" to re-authorize.`,
+        { userOpenId }
+      );
+    }
+    log.error('Update document failed', { error: err instanceof Error ? err.message : String(err) });
+    return jsonError(err instanceof Error ? err.message : String(err));
+  }
+}