systemPatterns.md•3.95 kB
# ClickUp MCP Server System Patterns
## Architecture Overview
```mermaid
flowchart TD
A[AI Assistant] --> B[MCP Server]
B --> C[API Client Layer]
C --> D[ClickUp API]
subgraph MCP Server
E[Tools] --> F[API Clients]
G[Resources] --> F
H[Error Handling] --> F
end
```
## Core Patterns
### 1. API Client Layer
```mermaid
flowchart LR
A[Base Client] --> B[Auth Client]
A --> C[Tasks Client]
A --> D[Lists Client]
A --> E[Spaces Client]
A --> F[Folders Client]
A --> G[Docs Client]
A --> H[Comments Client]
A --> I[Checklists Client]
```
Pattern:
- Each entity has dedicated client
- Clients inherit from base client
- Consistent error handling
- Standard response formatting
### 2. Tool Implementation
```mermaid
flowchart TD
A[Tool Registration] --> B[Input Validation]
B --> C[API Call]
C --> D[Response Formatting]
D --> E[Error Handling]
```
Pattern:
- Clear tool naming
- Strong parameter typing
- Comprehensive descriptions
- Consistent error patterns
### 3. Resource Structure
```mermaid
flowchart TD
A[Resource Template] --> B[URI Pattern]
B --> C[Parameter Extraction]
C --> D[Data Retrieval]
D --> E[Response Formatting]
```
Pattern:
- URI-based access
- Clear parameter patterns
- Consistent data format
- Resource relationships
## Design Decisions
### 1. Authentication
- API Token based
- Optional OAuth support
- Token security measures
- Rate limiting handling
### 2. Error Handling
```typescript
try {
// API call
} catch (error: any) {
console.error('[Error] API call failed:', error);
return {
content: [{ type: 'text', text: `Error: ${error.message}` }],
isError: true
};
}
```
Pattern:
- Consistent error format
- Detailed error messages
- Error type identification
- Recovery suggestions
### 3. Response Formatting
```typescript
return {
content: [{
type: 'text',
text: JSON.stringify(result, null, 2)
}]
};
```
Pattern:
- Consistent structure
- Pretty formatting
- Type identification
- Complete data
## Component Relationships
### 1. Tool to Client
```mermaid
flowchart LR
A[Tool Layer] --> B[Parameter Validation]
B --> C[API Client]
C --> D[ClickUp API]
D --> E[Response]
E --> F[Formatting]
```
### 2. Resource to Client
```mermaid
flowchart LR
A[Resource Request] --> B[URI Processing]
B --> C[Parameter Extraction]
C --> D[API Client]
D --> E[Data Retrieval]
```
### 3. Error Flow
```mermaid
flowchart TD
A[API Call] --> B{Error?}
B -->|Yes| C[Error Handler]
C --> D[Format Error]
D --> E[Return Response]
B -->|No| F[Format Success]
```
## Implementation Guidelines
### 1. Tool Creation
```typescript
server.tool(
'tool_name',
{ description: 'Tool purpose and usage' },
{
param: z.string().describe('Parameter description')
},
async (params) => {
// Implementation
}
);
```
### 2. Resource Definition
```typescript
server.resource(
'resource_name',
new ResourceTemplate('scheme://{param}'),
async (uri, params) => {
// Implementation
}
);
```
### 3. Error Handling
```typescript
try {
const result = await apiCall();
return formatSuccess(result);
} catch (error) {
return formatError(error);
}
```
## Testing Patterns
### 1. Tool Testing
- Verify registration
- Check descriptions
- Validate parameters
- Test error cases
### 2. Resource Testing
- Verify URI patterns
- Check data access
- Validate formatting
- Test relationships
### 3. Integration Testing
- End-to-end flows
- Error scenarios
- Performance checks
- Security validation
## Best Practices
### 1. Code Organization
- Modular structure
- Clear separation
- Consistent patterns
- Strong typing
### 2. Documentation
- Clear descriptions
- Usage examples
- Error guidance
- Relationship documentation
### 3. Error Management
- Consistent handling
- Clear messages
- Recovery paths
- Logging standards