GitHub Copilot Instructions for Zenbooker MCP Server

Project Overview

This is a Zenbooker MCP (Model Context Protocol) Server built on Cloudflare Workers. It provides comprehensive API access to Zenbooker's home service business management platform.

Project Type

Framework: Cloudflare Workers with TypeScript
MCP SDK:
```
@modelcontextprotocol/sdk
```
Agents: Using
```
agents
```
package for MCP implementation
Validation: Zod for type-safe parameter validation
Deployment: Cloudflare Workers (serverless)

Key Technologies

TypeScript - Primary language
Cloudflare Workers - Runtime environment
Model Context Protocol (MCP) - Protocol for AI agent tool integration
Zenbooker API - Third-party REST API integration
Zod - Runtime type validation

Architecture Patterns

MCP Agent Structure

export class ZenbookerMCP extends McpAgent {
  server = new McpServer({ name: "Zenbooker API", version: "1.0.0" });
  
  async init() {
    // Tool definitions with Zod schemas
    this.server.tool("tool_name", schema, handler);
  }
}

API Integration Pattern

Authentication: Bearer token via
```
Authorization
```
header
Base URL:
```
https://api.zenbooker.com/v1
```
Error Handling: Structured error responses with HTTP status codes
Pagination: Cursor-based with
```
limit
```
,
```
cursor
```
,
```
has_more
```
,
```
next_cursor
```

Tool Categories Implemented

Jobs Management -
```
list_jobs
```
,
```
get_job
```

Customer Management -

list_customers

get_customer

create_customer

update_customer

Financial Operations -

list_invoices

get_invoice

list_transactions

Team Management -
```
list_team_members
```
Scheduling -
```
list_recurring_bookings
```
Service Areas -
```
list_territories
```
Marketing -
```
create_coupon
```

Code Patterns

Tool Definition Pattern

this.server.tool(
  "tool_name",
  {
    required_param: z.string(),
    optional_param: z.string().optional(),
    enum_param: z.enum(["option1", "option2"]),
    number_param: z.number().min(1).max(100)
  },
  async (params) => {
    const result = await makeZenbookerRequest(endpoint, method, body, globalApiKey);
    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
  }
);

Query Parameter Building

const queryParams = new URLSearchParams();
Object.entries(params).forEach(([key, value]) => {
  if (value !== undefined) {
    queryParams.append(key, String(value));
  }
});
const endpoint = `/resource${queryParams.toString() ? `?${queryParams.toString()}` : ""}`;

Environment Variable Handling

API key injection via
```
env.ZENBOOKER_API_KEY
```
Global storage pattern for stateless functions
Cloudflare Workers environment binding

Development Guidelines

When Adding New Tools

Follow Zenbooker API docs exactly - Parameter names, types, and validation rules
Use descriptive tool names -
```
action_resource
```
format (e.g.,
```
list_customers
```
,
```
create_job
```
)
Include all optional parameters - Mark with
```
.optional()
```
in Zod schema
Handle pagination consistently - Always include
```
cursor
```
and
```
limit
```
for list endpoints
Validate enums strictly - Use
```
z.enum()
```
for restricted values
Return structured JSON - Always format with
```
JSON.stringify(result, null, 2)
```

Error Handling Standards

API key validation - Check for presence before requests
HTTP error responses - Include status codes and error messages
Type validation - Let Zod handle parameter validation
Network error handling - Graceful degradation for API unavailability

Testing Approach

Local development: Use
```
wrangler dev
```
with environment variables
API validation: Test against Zenbooker sandbox/staging environment
MCP client testing: Use Cloudflare AI Playground or Claude Desktop

File Structure

src/
  index.ts          # Main MCP server implementation
README.md           # Main project documentation  
ZENBOOKER_README.md # Detailed API tool documentation
.env.example        # Environment variable template
wrangler.jsonc      # Cloudflare Workers configuration
package.json        # Dependencies and scripts

Common Patterns to Follow

Resource ID Parameters

Always use

z.string().describe("The {resource} ID")

for ID fields

Parameter name should be
```
id
```
for single resource endpoints

Date Parameters

Use
```
z.string()
```
for date inputs (API expects ISO 8601 strings)
Common date filters:
```
start_date
```
,
```
end_date
```

List Pagination Parameters

```
cursor: z.number().optional()
```

limit: z.number().min(1).max(100).optional()

(max 40 for recurring bookings)

Search/Filter Parameters

Use descriptive names:
```
customer_id
```
,
```
status
```
,
```
search
```
,
```
email
```
,
```
phone
```
All filters should be optional unless specified in API docs

Zenbooker API Specifics

Authentication

Bearer token in Authorization header
API key from Zenbooker admin: Settings > Developers > API

Data Format Notes

All datetimes in ISO 8601 UTC format
Jobs/bookings include timezone fields for local conversion
Pagination uses cursor-based system, not page numbers
Maximum 100 results per request (40 for recurring bookings)

API Limitations

API is in beta - endpoints may change
Rate limiting may apply based on plan
Some endpoints may be read-only

Best Practices for Future Development

Stay Updated with Zenbooker API Changes - Monitor API documentation
Maintain Parameter Consistency - Follow existing naming conventions
Add Comprehensive Documentation - Update both README files for new tools
Test Thoroughly - Validate against real Zenbooker accounts
Handle Edge Cases - Empty results, API timeouts, invalid parameters
Security First - Never expose API keys in logs or client-side code

Integration Points

Cloudflare Workers Integration

Environment variables via
```
env
```
parameter
Serverless execution context
Global fetch API for HTTP requests

MCP Protocol Compliance

Tool discovery via server metadata
Structured parameter schemas
Consistent response formatting
Error handling per MCP specification

Claude Desktop Integration

Remote MCP proxy via
```
mcp-remote
```
package
SSE (Server-Sent Events) endpoint for real-time communication
Tool availability in AI chat interface

This server enables AI agents to perform comprehensive home service business operations through Zenbooker's platform, including customer management, job scheduling, invoicing, and team coordination.

Last Updated: August 16, 2025 Project: Zenbooker MCP Server Copilot Instructions Version: 2.0.0

GitHub Copilot Instructions for Zenbooker MCP Server

Project Overview

This is a Zenbooker MCP (Model Context Protocol) Server built on Cloudflare Workers. It provides comprehensive API access to Zenbooker's home service business management platform.

Project Type

Framework: Cloudflare Workers with TypeScript
MCP SDK:
```
@modelcontextprotocol/sdk
```
Agents: Using
```
agents
```
package for MCP implementation
Validation: Zod for type-safe parameter validation
Deployment: Cloudflare Workers (serverless)

Key Technologies

TypeScript - Primary language
Cloudflare Workers - Runtime environment
Model Context Protocol (MCP) - Protocol for AI agent tool integration
Zenbooker API - Third-party REST API integration
Zod - Runtime type validation

Architecture Patterns

MCP Agent Structure

export class ZenbookerMCP extends McpAgent {
  server = new McpServer({ name: "Zenbooker API", version: "1.0.0" });
  
  async init() {
    // Tool definitions with Zod schemas
    this.server.tool("tool_name", schema, handler);
  }
}

API Integration Pattern

Authentication: Bearer token via
```
Authorization
```
header
Base URL:
```
https://api.zenbooker.com/v1
```
Error Handling: Structured error responses with HTTP status codes
Pagination: Cursor-based with
```
limit
```
,
```
cursor
```
,
```
has_more
```
,
```
next_cursor
```

Tool Categories Implemented

Jobs Management -
```
list_jobs
```
,
```
get_job
```

Customer Management -

list_customers

get_customer

create_customer

update_customer

Financial Operations -

list_invoices

get_invoice

list_transactions

Team Management -
```
list_team_members
```
Scheduling -
```
list_recurring_bookings
```
Service Areas -
```
list_territories
```
Marketing -
```
create_coupon
```

Code Patterns

Tool Definition Pattern

this.server.tool(
  "tool_name",
  {
    required_param: z.string(),
    optional_param: z.string().optional(),
    enum_param: z.enum(["option1", "option2"]),
    number_param: z.number().min(1).max(100)
  },
  async (params) => {
    const result = await makeZenbookerRequest(endpoint, method, body, globalApiKey);
    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
  }
);

Query Parameter Building

const queryParams = new URLSearchParams();
Object.entries(params).forEach(([key, value]) => {
  if (value !== undefined) {
    queryParams.append(key, String(value));
  }
});
const endpoint = `/resource${queryParams.toString() ? `?${queryParams.toString()}` : ""}`;

Environment Variable Handling

API key injection via
```
env.ZENBOOKER_API_KEY
```
Global storage pattern for stateless functions
Cloudflare Workers environment binding

Development Guidelines

When Adding New Tools

Follow Zenbooker API docs exactly - Parameter names, types, and validation rules
Use descriptive tool names -
```
action_resource
```
format (e.g.,
```
list_customers
```
,
```
create_job
```
)
Include all optional parameters - Mark with
```
.optional()
```
in Zod schema
Handle pagination consistently - Always include
```
cursor
```
and
```
limit
```
for list endpoints
Validate enums strictly - Use
```
z.enum()
```
for restricted values
Return structured JSON - Always format with
```
JSON.stringify(result, null, 2)
```

Error Handling Standards

API key validation - Check for presence before requests
HTTP error responses - Include status codes and error messages
Type validation - Let Zod handle parameter validation
Network error handling - Graceful degradation for API unavailability

Testing Approach

Local development: Use
```
wrangler dev
```
with environment variables
API validation: Test against Zenbooker sandbox/staging environment
MCP client testing: Use Cloudflare AI Playground or Claude Desktop

File Structure

src/
  index.ts          # Main MCP server implementation
README.md           # Main project documentation  
ZENBOOKER_README.md # Detailed API tool documentation
.env.example        # Environment variable template
wrangler.jsonc      # Cloudflare Workers configuration
package.json        # Dependencies and scripts

Common Patterns to Follow

Resource ID Parameters

Always use

z.string().describe("The {resource} ID")

for ID fields

Parameter name should be
```
id
```
for single resource endpoints

Date Parameters

Use
```
z.string()
```
for date inputs (API expects ISO 8601 strings)
Common date filters:
```
start_date
```
,
```
end_date
```

List Pagination Parameters

```
cursor: z.number().optional()
```

limit: z.number().min(1).max(100).optional()

(max 40 for recurring bookings)

Search/Filter Parameters

Use descriptive names:
```
customer_id
```
,
```
status
```
,
```
search
```
,
```
email
```
,
```
phone
```
All filters should be optional unless specified in API docs

Zenbooker API Specifics

Authentication

Bearer token in Authorization header
API key from Zenbooker admin: Settings > Developers > API

Data Format Notes

All datetimes in ISO 8601 UTC format
Jobs/bookings include timezone fields for local conversion
Pagination uses cursor-based system, not page numbers
Maximum 100 results per request (40 for recurring bookings)

API Limitations

API is in beta - endpoints may change
Rate limiting may apply based on plan
Some endpoints may be read-only

Best Practices for Future Development

Stay Updated with Zenbooker API Changes - Monitor API documentation
Maintain Parameter Consistency - Follow existing naming conventions
Add Comprehensive Documentation - Update both README files for new tools
Test Thoroughly - Validate against real Zenbooker accounts
Handle Edge Cases - Empty results, API timeouts, invalid parameters
Security First - Never expose API keys in logs or client-side code

Integration Points

Cloudflare Workers Integration

Environment variables via
```
env
```
parameter
Serverless execution context
Global fetch API for HTTP requests

MCP Protocol Compliance

Tool discovery via server metadata
Structured parameter schemas
Consistent response formatting
Error handling per MCP specification

Claude Desktop Integration

Remote MCP proxy via
```
mcp-remote
```
package
SSE (Server-Sent Events) endpoint for real-time communication
Tool availability in AI chat interface

This server enables AI agents to perform comprehensive home service business operations through Zenbooker's platform, including customer management, job scheduling, invoicing, and team coordination.

Last Updated: August 16, 2025 Project: Zenbooker MCP Server Copilot Instructions Version: 2.0.0

GitHub Copilot Instructions for Zenbooker MCP Server

Related Skills

Nano Banana Pro

Markdown Converter

1password