Cafe24 MCP Helper

This skill provides a systematic workflow for adding new Cafe24 Admin API functionalities to the MCP server.

Workflow

Follow these steps when implementing new tools based on a user's curl request or API documentation:

1. •Analyze the Request: Identify the resource name, HTTP method, endpoint, parameters, and response structure.
2. •Define Types: Create a new type file in src/types/{feature}.ts (kebab-case).
   • •Use interfaces for API responses and nested objects.
   • •Export everything and add an export statement to src/types/index.ts.
3. •Define Schemas: Create a new Zod schema file in src/schemas/{feature}.ts.
   • •Use .strict() for input schemas.
   • •Add descriptive strings to .describe().
   • •Follow established paging patterns (limit: 1-500, default 10/20).
4. •Implement Tools: Create a new tool file in src/tools/{feature}.ts.
   • •Use makeApiRequest and handleApiError from ../services/api-client.js.
   • •Return both content (Markdown string) and structuredContent (JSON).
5. •Register Tools: Update src/tools/index.ts.
   • •Import registerTools as register{Feature}Tools.
   • •Call register{Feature}Tools(server) in registerAllTools.
6. •Verify:
   • •Run bun lint && bun typecheck.
   • •Use bun biome check src --write to fix linting errors.

Implementation Details

See references/api_reference.md for code patterns and directory structure guidelines.

Best Practices

• •Naming: Use camelCase for function names (e.g., cafe24_list_orders) and PascalCase for schemas (e.g., OrdersSearchParamsSchema).
• •File Names: Always use kebab-case for filenames (e.g., order-control.ts instead of orderControl.ts).
• •Imports: Use relative imports for local files and @/types/index.js for types.
• •Error Handling: Always wrap tool logic in try-catch and use handleApiError.
• •Tool Structure: Separate handler functions from registration. Use server.registerTool() with annotations. See references/api_reference.md.