Batch Master

Intelligent batch processing MCP service - converts API definitions to Excel templates for batch data construction and upload.

Features

• 🎯 Smart Template Generation: Generate Excel templates from TypeScript interfaces, Swagger definitions, or SQL DDL
• 📊 Rich Excel Functionality: Data validation (dropdown menus), field descriptions (comments), style formatting
• 🚀 Concurrency Control: Smart control of API call concurrency to avoid service overload
• 🔄 Result Feedback: Execution results written back to Excel for easy review and analysis
• 🌳 Nested Object Support: Automatic handling of dot notation (e.g., user.address.city)

Tech Stack

• Runtime: Node.js 18+ / Bun
• Language: TypeScript
• MCP SDK: @modelcontextprotocol/sdk (Latest version, using McpServer API)
• Excel: exceljs
• HTTP: axios
• Concurrency: p-limit
• Validation: zod

Installation

# Using pnpm
pnpm install

# Or using bun
bun install

Quick Start

1. Build the Project

# Using pnpm
pnpm run build

# Or using bun
bun run build

2. Test Excel Generation

# Using pnpm
pnpm run test

# Or using bun
bun run test

This will generate a test_users_template.xlsx file containing:

• Styled headers
• Required field markers (red)
• Field descriptions (cell comments)
• Dropdown menus for enum fields
• Sample data row

3. Configure MCP Server

Add to your MCP client configuration file:

{
  "mcpServers": {
    "batch-master": {
      "command": "node",
      "args": ["/path/to/batch-master/dist/index.js"]
    }
  }
}

Or using bun:

{
  "mcpServers": {
    "batch-master": {
      "command": "bun",
      "args": ["/path/to/batch-master/src/index.ts"]
    }
  }
}

MCP Tools

1. generate_template

Generate an Excel template with data validation and formatting.

Parameters:

• filename: Output file path
• columns: Array of column definitions
  • key: Field key (supports dot notation)
  • title: Column header
  • type: Data type (string, number, boolean, enum, date)
  • required: Whether the field is required
  • description: Field description
  • options: Enum options (for dropdown menus)
  • width: Column width

**Example:**le:**

{
  "filename": "./users_template.xlsx",
  "columns": [
    {
      "key": "user.name",
      "title": "User Name",
      "type": "string",
      "required": true,
      "description": "User's full name"
    },
    {
      "key": "user.city",
      "title": "City",
      "type": "enum",
      "options": ["Beijing", "Shanghai", "Guangzhou", "Shenzhen"],
      "required": true
    }
  ]
}

2. batch_execute

Execute batch API calls from an Excel file.

Parameters:

• filename: Excel file path
• config: API configuration
  • apiUrl: API endpoint URL
  • method: HTTP method (default: POST)
  • headers: Request headers
  • concurrency: Concurrency limit (default: 5, max: 50)
  • timeout: Timeout in milliseconds (default: 30000)
• columns: Column definitions (must match the template)

Example:

{
  "filename": "./users_template.xlsx",
  "config": {
    "apiUrl": "https://api.example.com/users",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer your-token"
    },
    "concurrency": 10
  },
  "columns": [...]
}

Usage Workflow

1. Parse API Definition

   • AI parses user-provided TypeScript interfaces, Swagger JSON, or SQL DDL
   • Converts to standardized column definition format

2. Generate Excel Template

   • Call the generate_template tool
   • Generate Excel file with validation rules

3. Fill Data

   • User fills in batch data in Excel
   • Use dropdown menus and comments for input assistance

4. Batch Execute

   • Call the batch_execute tool
   • System reads Excel data and executes API calls
   • Generate result file (_result.xlsx)

5. Review Results

   • Check execution status and response information in result file
   • Handle failed records

Project Structureect Structure

batch-master/
├── src/
│   ├── types.ts                 # Core type definitions
│   ├── schemas.ts               # Zod validation schemas
│   ├── template-generator.ts   # Excel template generator
│   ├── batch-executor.ts        # Batch executor
│   ├── index.ts                 # MCP Server entry point
│   └── test-excel.ts            # Test script
├── package.json
├── tsconfig.json
└── README.md

Development

# Type checking
pnpm run type-check

# Development mode (with watch)
pnpm run dev

# Test Excel generation
pnpm run test

Example Scenarios

Scenario 1: Batch Create Users

1. AI parses user management API documentation
2. Generate template with fields like name, email, role, etc.
3. Administrator fills in 100 user records
4. Batch execute creation with concurrency limited to 10 requests
5. Review results and handle failed records

Scenario 2: Batch Update Order Status

1. Generate template from order API schema
2. Export pending orders to Excel
3. Modify status field (using dropdown menu)
4. Batch execute PUT requests for updates
5. Verify update results

Important Notes

• Row 1 of the Excel template is the header, row 2 is sample data, actual data starts from row 3
• Nested objects use dot notation (e.g., user.address.city)
• Enum fields automatically generate dropdown menus (applied to first 1000 rows)
• Concurrency should not be too high; adjust based on target API capacity
• Result file saves all request responses for troubleshooting

License

MIT

Contributing

Issues and Pull Requests are welcome!