architecture.md•6.89 kB
# Nexus MCP Calculator - Architecture Diagram
## File Relationships
```mermaid
graph TB
%% External Systems
Claude[Claude Desktop<br/>MCP Client]
Temporal[Temporal Server<br/>localhost:7233]
%% Configuration & Setup
pyproject[pyproject.toml<br/>📝 Dependencies & Config]
setup[scripts/setup_temporal.sh<br/>🔧 Infrastructure Setup]
cleanup[scripts/cleanup_temporal.sh<br/>🗑️ Infrastructure Cleanup]
%% Core Application Files
service[service.py<br/>📋 Nexus Service Definition]
handler[service_handler.py<br/>⚙️ Business Logic & Handlers]
worker[worker.py<br/>👷 Temporal Worker]
server[mcp_server.py<br/>🌐 MCP Gateway Server]
demo[demo_workflow.py<br/>🎯 Demo Workflow]
%% Documentation
readme[README.md<br/>📖 User Guide]
claude_md[CLAUDE.md<br/>🛠️ Developer Guide]
%% Package Structure
init[__init__.py<br/>📦 Package Init]
gitignore[.gitignore<br/>🚫 Git Exclusions]
%% External Dependencies
nexus_mcp[https://github.com/bergundy/nexus-mcp-python<br/>📚 Core Library (MCP fork)]
%% Relationships - Configuration
pyproject -.-> nexus_mcp
pyproject -.-> service
pyproject -.-> handler
pyproject -.-> worker
pyproject -.-> server
pyproject -.-> demo
%% Relationships - Setup Scripts
setup --> Temporal
cleanup --> Temporal
setup -.-> worker
setup -.-> server
%% Relationships - Core Logic Flow
service --> handler
handler --> worker
handler -.-> nexus_mcp
server -.-> nexus_mcp
server --> Temporal
demo -.-> nexus_mcp
demo --> Temporal
%% Relationships - External Connections
Claude --> server
worker --> Temporal
%% Relationships - Runtime Flow
Claude -.->|MCP Protocol| server
server -.->|Temporal Client| Temporal
Temporal -.->|Nexus RPC| worker
worker -.->|Service Handlers| handler
demo -.->|Workflow Transport| Temporal
Temporal -.->|MCP Gateway| server
server -.->|Tool Calls| handler
%% Documentation relationships
readme -.-> service
readme -.-> handler
readme -.-> worker
readme -.-> server
readme -.-> demo
readme -.-> setup
claude_md -.-> service
claude_md -.-> handler
claude_md -.-> worker
claude_md -.-> server
claude_md -.-> demo
%% Styling
classDef external fill:#e1f5fe,stroke:#01579b,stroke-width:2px
classDef config fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
classDef core fill:#e8f5e8,stroke:#1b5e20,stroke-width:2px
classDef docs fill:#fff3e0,stroke:#e65100,stroke-width:2px
classDef scripts fill:#fce4ec,stroke:#880e4f,stroke-width:2px
class Claude,Temporal external
class pyproject,gitignore,init config
class service,handler,worker,server,demo,nexus_mcp core
class readme,claude_md docs
class setup,cleanup scripts
```
## Component Interactions
### 1. Development Setup Flow
```mermaid
sequenceDiagram
participant Dev as Developer
participant Setup as setup_temporal.sh
participant Temporal as Temporal Server
Dev->>Setup: ./scripts/setup_temporal.sh
Setup->>Temporal: Create handler namespace
Setup->>Temporal: Create caller namespace
Setup->>Temporal: Create nexus endpoint
Setup-->>Dev: Infrastructure ready
```
### 2. Runtime Execution Flow
```mermaid
sequenceDiagram
participant Client as MCP Client
participant Server as mcp_server.py
participant Temporal as Temporal Server
participant Worker as worker.py
participant Handler as service_handler.py
Worker->>Temporal: Register service handlers
Server->>Temporal: Connect as MCP gateway
Client->>Server: List tools (MCP)
Server->>Temporal: Discover operations (Nexus)
Temporal-->>Server: Available operations
Server-->>Client: Tool definitions
Client->>Server: Call tool (MCP)
Server->>Temporal: Execute operation (Nexus)
Temporal->>Worker: Route to handler
Worker->>Handler: Process request
Handler-->>Worker: Return result
Worker-->>Temporal: Operation complete
Temporal-->>Server: Result
Server-->>Client: Tool response
```
### 3. File Dependencies
```mermaid
graph LR
%% Service Layer
service[service.py] --> handler[service_handler.py]
%% Infrastructure Layer
handler --> worker[worker.py]
handler --> server[mcp_server.py]
handler --> demo[demo_workflow.py]
%% External Dependencies
service -.-> pydantic[Pydantic Models]
service -.-> nexusrpc[Nexus RPC]
handler -.-> nexusmcp[nexus-mcp Library]
worker -.-> temporalio[Temporal SDK]
server -.-> mcp[MCP Library]
demo -.-> temporalio
%% Configuration
pyproject[pyproject.toml] -.-> service
pyproject -.-> handler
pyproject -.-> worker
pyproject -.-> server
pyproject -.-> demo
classDef app fill:#e8f5e8,stroke:#1b5e20,stroke-width:2px
classDef lib fill:#e1f5fe,stroke:#01579b,stroke-width:2px
classDef config fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
class service,handler,worker,server,demo app
class pydantic,nexusrpc,nexusmcp,temporalio,mcp lib
class pyproject config
```
## Key Design Patterns
### Service Registration Pattern
```mermaid
graph TB
MCPServiceHandler[MCPServiceHandler<br/>Registry]
CalculatorHandler[CalculatorHandler<br/>@register decorator]
NexusOperations[Nexus Operations<br/>Auto-discovered]
MCPTools[MCP Tools<br/>Auto-exposed]
CalculatorHandler --> MCPServiceHandler
MCPServiceHandler --> NexusOperations
NexusOperations --> MCPTools
```
### Safe Expression Evaluation
```mermaid
graph TB
UserInput[Mathematical Expression] --> ASTParse[AST Parser]
ASTParse --> Validator{Valid?}
Validator -->|Yes| SafeEval[Safe Evaluation]
Validator -->|No| Error[Validation Error]
SafeEval --> Result[Calculation Result]
AllowedOps[Allowed Operators<br/>+, -, *, /, **, %] -.-> Validator
AllowedFuncs[Allowed Functions<br/>abs, round, max, min, sum] -.-> Validator
```
## File Purpose Summary
| File | Purpose | Key Responsibilities |
|------|---------|---------------------|
| `service.py` | Service Definition | Pydantic models, Nexus service schema |
| `service_handler.py` | Business Logic | Calculator operations, MCP registration |
| `worker.py` | Temporal Worker | Service handler execution, task processing |
| `mcp_server.py` | MCP Gateway | Client communication, tool discovery |
| `demo_workflow.py` | Demonstration | Workflow-based tool consumption |
| `setup_temporal.sh` | Infrastructure | Namespace and endpoint creation |
| `cleanup_temporal.sh` | Maintenance | Infrastructure removal |
| `pyproject.toml` | Configuration | Dependencies and project metadata |