ARCHITECTURE.md•8.38 kB
# Slack MCP Architecture
This document explains the architecture and design decisions of the Slack MCP server.
## Overview
The Slack MCP server follows **Clean Architecture** principles, ensuring separation of concerns, testability, and maintainability. The architecture is organized into distinct layers with clear boundaries and dependencies flowing inward.
## Layer Structure
```
┌─────────────────────────────────────────────────────────┐
│ Presentation Layer │
│ ┌─────────────────┐ ┌─────────────────────────────────┐ │
│ │ MCP Server │ │ Routes │ │
│ │ (server.ts) │ │ (future web API) │ │
│ └─────────────────┘ └─────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
│
┌─────────────────────────────────────────────────────────┐
│ Application Layer │
│ ┌─────────────────┐ ┌─────────────────────────────────┐ │
│ │ Use Cases │ │ Services │ │
│ │ - ListChannels │ │ - SlackService │ │
│ │ - PostMessage │ │ - Validation │ │
│ │ - GetHistory │ │ - Caching │ │
│ └─────────────────┘ └─────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
│
┌─────────────────────────────────────────────────────────┐
│ Core/Domain Layer │
│ ┌─────────────────┐ ┌─────────────────────────────────┐ │
│ │ Interfaces │ │ Types │ │
│ │ - ISlackClient │ │ - SlackChannel │ │
│ │ - ISlackService │ │ - SlackMessage │ │
│ │ - IStorage │ │ - SlackUser │ │
│ └─────────────────┘ └─────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
│
┌─────────────────────────────────────────────────────────┐
│ Infrastructure Layer │
│ ┌─────────────────┐ ┌─────────────────────────────────┐ │
│ │ Slack Client │ │ Storage │ │
│ │ - HTTP calls │ │ - InMemoryStorage │ │
│ │ - API mapping │ │ - Caching with TTL │ │
│ └─────────────────┘ └─────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
```
## Layers Explained
### 1. Core/Domain Layer (`src/core/`)
**Responsibility**: Contains business entities, interfaces, and types.
- **Types** (`types/`): Define data structures (SlackChannel, SlackMessage, etc.)
- **Interfaces** (`interfaces/`): Define contracts for services and clients
**Dependencies**: None (innermost layer)
### 2. Application Layer (`src/application/`)
**Responsibility**: Contains business logic and orchestrates the flow of data.
- **Services** (`services/`): Business logic, validation, caching
- **Use Cases** (`usecases/`): Specific application operations with formatted responses
**Dependencies**: Core layer only
### 3. Infrastructure Layer (`src/infrastructure/`)
**Responsibility**: Handles external concerns and implementation details.
- **Clients** (`clients/`): HTTP clients for external APIs (Slack API)
- **Storage** (`storage/`): Data persistence implementations
**Dependencies**: Core layer only
### 4. Presentation Layer (`src/presentation/`)
**Responsibility**: Handles user interface and external communication.
- **MCP Server** (`server.ts`): Model Context Protocol server implementation
- **Routes** (`routes/`): Future web API routes (if needed)
**Dependencies**: Application and Core layers
## Key Design Patterns
### Dependency Injection
The `Dependencies` class (`src/config/dependencies.ts`) acts as a dependency injection container:
```typescript
export class Dependencies {
public readonly cacheStorage = new InMemoryStorage(30);
public readonly slackClient = new SlackClient(token, teamId);
public readonly slackService = new SlackService(
this.slackClient,
this.cacheStorage
);
// ... use cases
}
```
### Repository Pattern
The `ISlackClient` interface abstracts the Slack API, making it easy to:
- Mock for testing
- Swap implementations
- Add retry logic or circuit breakers
### Use Case Pattern
Each operation is encapsulated in a use case:
- Single responsibility
- Consistent error handling
- Formatted responses for MCP
### Result Pattern
Operations return `SlackOperationResult<T>` for consistent error handling:
```typescript
interface SlackOperationResult<T = any> {
success: boolean;
data?: T;
error?: string;
}
```
## Benefits of This Architecture
### 1. **Testability**
- Each layer can be tested independently
- Easy to mock dependencies
- Clear boundaries make unit testing straightforward
### 2. **Maintainability**
- Changes to external APIs only affect the Infrastructure layer
- Business logic is isolated in the Application layer
- Clear separation of concerns
### 3. **Extensibility**
- Easy to add new Slack operations
- Can add different storage implementations
- Can add web API alongside MCP server
### 4. **Performance**
- Built-in caching at the service layer
- Efficient memory management with TTL
- Minimal overhead for MCP protocol
## Data Flow
1. **MCP Client** sends tool request
2. **MCP Server** (`server.ts`) receives and validates request
3. **Use Case** orchestrates the operation
4. **Service** applies business logic and caching
5. **Client** makes HTTP calls to Slack API
6. **Response** flows back through layers with proper formatting
## Configuration
Environment-based configuration with sensible defaults:
- `SLACK_TOKEN`: Bot or user token
- `SLACK_TEAM_ID`: Workspace ID
- Cache TTL: 30 minutes (configurable)
## Error Handling
Consistent error handling across all layers:
- Network errors caught at client layer
- Validation errors at service layer
- Formatted error responses for MCP
- Graceful degradation when cache fails
## Future Enhancements
The architecture supports easy addition of:
- Database storage (replace InMemoryStorage)
- Web API endpoints (add to presentation layer)
- Webhook handlers (new infrastructure component)
- Advanced caching strategies (Redis, etc.)
- Rate limiting and retry logic
- Metrics and monitoring