Excel MCP Server

Instructions

Implementation Reference

• src/handlers/excelHandlers.ts:333-364 (handler)

  The main handler function implementing the core logic of exporting Excel structure: analyzes source file, validates structure, converts to SheetData, and writes to target file.

  export async function exportExcelStructure(
      sourceFilePath: string,
      targetFilePath: string,
      headerRows: number = 1
  ): Promise<boolean> {
      try {
          // 1. 获取源文件的结构
          const structure = await analyzeExcelStructure(sourceFilePath, headerRows);
  
          // 校验结构数据
          if (!structure.sheetList || !Array.isArray(structure.sheetList) || structure.sheetList.length === 0) {
              throw new Error('Invalid Excel structure: sheetList is empty or invalid');
          }
  
          if (!structure.sheetField || !Array.isArray(structure.sheetField) || structure.sheetField.length === 0) {
              throw new Error('Invalid Excel structure: sheetField is empty or invalid');
          }
  
          // 2. 转换为 SheetData 格式
          const data: SheetData = {
              'sheetList': structure.sheetList,
              'sheetField': structure.sheetField
          };
  
          // 3. 使用 writeSheetData 写入文件
          return await writeSheetData(targetFilePath, data);
  
      } catch (error) {
          const errorMessage = error instanceof Error ? error.message : String(error);
          throw new Error(`Failed to export Excel structure: ${errorMessage}`);
      }
  }

• src/tools/structureTools.ts:63-154 (registration)

  MCP tool registration including description, Zod input schema, and wrapper handler that normalizes paths, validates files, and delegates to core exportExcelStructure function.

  server.tool("exportExcelStructure", 'Export Excel file structure (sheets and headers) to a new Excel template file',
      {
          sourceFilePath: z.string().describe("The source Excel file path to analyze"),
          targetFilePath: z.string().describe("The target Excel file path to save structure"),
          headerRows: z.number().default(1).describe("Number of header rows to analyze (default: 1)")
      },
      async (params: {
          sourceFilePath: string;
          targetFilePath: string;
          headerRows: number;
      }) => {
          try {
              // 验证源文件路径
              const normalizedSourcePath = await normalizePath(params.sourceFilePath);
              if (normalizedSourcePath === 'error') {
                  return {
                      content: [{
                          type: "text",
                          text: JSON.stringify({
                              error: `Invalid source file path: ${params.sourceFilePath}`,
                              suggestion: "Please verify the source file path"
                          })
                      }]
                  };
              }
  
              // 验证源文件是否存在
              if (!(await fileExists(normalizedSourcePath))) {
                  return {
                      content: [{
                          type: "text",
                          text: JSON.stringify({
                              error: `Source file not found: ${params.sourceFilePath}`,
                              suggestion: "Please verify the source file exists"
                          })
                      }]
                  };
              }
  
              // 验证目标文件路径
              const normalizedTargetPath = await normalizePath(params.targetFilePath);
              if (normalizedTargetPath === 'error') {
                  return {
                      content: [{
                          type: "text",
                          text: JSON.stringify({
                              error: `Invalid target file path: ${params.targetFilePath}`,
                              suggestion: "Please verify the target file path"
                          })
                      }]
                  };
              }
  
              // 验证目标文件是否已存在
              if (await fileExists(normalizedTargetPath)) {
                  return {
                      content: [{
                          type: "text",
                          text: JSON.stringify({
                              error: `Target file already exists: ${params.targetFilePath}`,
                              suggestion: "Please specify a different target file path"
                          })
                      }]
                  };
              }
  
              // 导出结构
              await exportExcelStructure(normalizedSourcePath, normalizedTargetPath, params.headerRows);
  
              return {
                  content: [{
                      type: "text",
                      text: JSON.stringify({
                          success: true,
                          message: `Excel structure exported successfully to: ${normalizedTargetPath}`
                      })
                  }]
              };
  
          } catch (error) {
              return {
                  content: [{
                      type: "text",
                      text: JSON.stringify({
                          error: `Failed to export Excel structure: ${error}`,
                          suggestion: "Please verify all parameters and try again"
                      })
                  }]
              };
          }
      }
  );

• src/tools/structureTools.ts:64-68 (schema)

  Zod schema defining input parameters for the tool.

  {
      sourceFilePath: z.string().describe("The source Excel file path to analyze"),
      targetFilePath: z.string().describe("The target Excel file path to save structure"),
      headerRows: z.number().default(1).describe("Number of header rows to analyze (default: 1)")
  },

• src/types/index.ts:32-41 (schema)

  TypeScript interface defining the ExcelStructure used for the exported data structure.

  export interface ExcelStructure {
      sheetList: Array<{
          SheetNo: number;
          SheetName: string;
      }>;
      sheetField: Array<{
          SheetName: string;
          [key: `Field${number}`]: string;
      }>;
  }