mcp_components_guide.md•6.91 kB
# Understanding the Clockify MCP Server Components
## 🏗️ High-Level Architecture
```
Claude Desktop ↔ MCP Protocol ↔ Our MCP Server ↔ Clockify API
```
Our MCP server acts as a **translator and bridge** between Claude and Clockify's API.
---
## 📦 Major Components Breakdown
### 1. **Core Server Setup**
```typescript
class ClockifyMCPServer {
private server: Server;
private config: ClockifyConfig;
}
```
**What it does:**
- Creates the main MCP server instance
- Manages configuration (API key, base URLs)
- Handles the connection with Claude Desktop
**Think of it as:** The main "control center" that coordinates everything
---
### 2. **Configuration Management**
```typescript
interface ClockifyConfig {
apiKey: string;
baseUrl: string;
}
```
**What it does:**
- Stores your Clockify API key securely
- Defines the base URL for Clockify's API (`https://api.clockify.me/api/v1`)
- Reads environment variables
**Think of it as:** Your "ID card" that proves you're allowed to access Clockify
---
### 3. **Tool Definitions (The Menu)**
```typescript
this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
tools: [
{
name: "create_time_entry",
description: "Create a new time entry",
inputSchema: { ... }
},
// ... 25+ other tools
]
}))
```
**What it does:**
- Tells Claude what functions are available
- Defines what parameters each function needs
- Provides descriptions so Claude knows when to use each tool
**Think of it as:** A restaurant menu that tells Claude what "dishes" (functions) are available and what "ingredients" (parameters) each needs
---
### 4. **Request Router (The Waiter)**
```typescript
this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
const { name, arguments: args } = request.params;
switch (name) {
case "create_time_entry":
return await this.createTimeEntry(args);
case "get_projects":
return await this.getProjects(args);
// ... handle all other tools
}
});
```
**What it does:**
- Receives requests from Claude
- Routes them to the correct function
- Handles errors and validation
**Think of it as:** A waiter who takes Claude's order and makes sure it gets to the right "kitchen" (function)
---
### 5. **HTTP Client (The Messenger)**
```typescript
private async makeRequest(
endpoint: string,
method: "GET" | "POST" | "PUT" | "DELETE" = "GET",
data?: any
): Promise<any>
```
**What it does:**
- Handles all communication with Clockify's API
- Adds authentication headers
- Converts data to/from JSON
- Handles errors and retries
**Think of it as:** A messenger who speaks Clockify's language and knows the secret handshake (API key)
---
### 6. **Data Models (The Vocabulary)**
```typescript
interface TimeEntry {
id?: string;
description?: string;
start: string;
end?: string;
projectId?: string;
// ...
}
interface Project {
id?: string;
name: string;
clientId?: string;
// ...
}
```
**What it does:**
- Defines the structure of data we work with
- Ensures type safety in TypeScript
- Documents what fields are available
**Think of it as:** A dictionary that defines what words (data fields) mean in our system
---
### 7. **Business Logic Methods (The Workers)**
#### Time Entry Management
```typescript
private async createTimeEntry(args: any) {
// Validate and format dates
// Make API call to Clockify
// Return formatted response to Claude
}
```
#### Project Management
```typescript
private async getProjects(args: any) {
// Build query parameters
// Fetch from Clockify API
// Format response for Claude
}
```
**What they do:**
- Implement the actual functionality
- Validate input data
- Transform data between Claude's format and Clockify's format
- Handle business logic and edge cases
**Think of them as:** Specialized workers who know how to do specific jobs (create entries, manage projects, etc.)
---
## 🔄 How It All Works Together
### Example: Creating a Time Entry
1. **Claude receives user request:** "Create a time entry for 2 hours on Project X"
2. **Claude calls MCP server:** Sends `create_time_entry` tool request with parameters
3. **Request Router:** Routes the request to `createTimeEntry()` method
4. **Business Logic:**
- Validates the data
- Converts dates to ISO format
- Prepares API payload
5. **HTTP Client:**
- Adds authentication headers
- Sends POST request to Clockify API
- Receives response
6. **Response Formatting:**
- Converts Clockify's response to user-friendly text
- Returns to Claude
7. **Claude responds:** "Time entry created successfully! Duration: 2:00:00"
---
## 🛡️ Key Features Built In
### **Error Handling**
```typescript
if (!this.config.apiKey) {
throw new McpError(ErrorCode.InvalidParams, "API key not configured");
}
```
- Validates API keys
- Handles network errors
- Provides meaningful error messages
### **Data Validation**
```typescript
if (!timeEntryData.start.includes("T")) {
timeEntryData.start = new Date(timeEntryData.start).toISOString();
}
```
- Ensures dates are in correct format
- Validates required fields
- Sanitizes input data
### **Pagination Support**
```typescript
const queryParams = new URLSearchParams();
queryParams.append("page", String(page));
queryParams.append("pageSize", String(pageSize));
```
- Handles large datasets
- Supports filtering and sorting
- Efficient data retrieval
### **Flexible API Support**
- Supports both regular API and reports API
- Handles different authentication methods
- Adapts to various endpoint patterns
---
## 🎯 Why This Architecture Works
### **Separation of Concerns**
- Each component has a single responsibility
- Easy to test and maintain
- Clear boundaries between layers
### **Type Safety**
- TypeScript catches errors at compile time
- Clear contracts between components
- Better IDE support and documentation
### **Extensibility**
- Easy to add new tools/functions
- Modular design allows for easy modifications
- Can be adapted for other APIs
### **Production Ready**
- Comprehensive error handling
- Robust validation
- Follows MCP best practices
---
## 🚀 The Magic
The real magic happens in how all these components work together seamlessly:
- **Claude** understands what tools are available through our tool definitions
- **Our server** translates between Claude's requests and Clockify's API
- **Clockify** processes the requests and returns data
- **Everything flows back** to provide Claude with the information it needs
It's like having a universal translator that lets Claude and Clockify have a conversation, even though they speak completely different "languages"!
This architecture makes it possible for you to simply tell Claude "start tracking time" and have it automatically create entries in Clockify, without you ever leaving your conversation with Claude.