MCP Server Architecture

System Overview

Supernal Coding provides a comprehensive MCP (Model Context Protocol) server architecture that enables seamless connection between Claude Code, local development workflows, and compliance management systems.

graph TB
    subgraph "User Interface"
        User[User/Developer]
        Claude[Claude Code Interface]
    end

    subgraph "MCP Protocol Layer"
        MCP[MCP Server<br/>stdio/JSON-RPC]
    end

    subgraph "Tool Layer"
        ReqMgr[Requirement<br/>Manager]
        KanbanMgr[Kanban<br/>Manager]
        GitMgr[Git<br/>Manager]
        AgentMgr[Agent<br/>Manager]
        ValidationMgr[Validation<br/>Manager]
        RulesMgr[Rules<br/>Manager]
        SyncMgr[Sync<br/>Manager]
    end

    subgraph "Synchronization Layer"
        ChangeDetect[Change Detection]
        ConflictRes[Conflict Resolution]
        EventEmit[Event Emission]
    end

    subgraph "Data Layer"
        LocalFS[Local File System]
        GitRepo[Git Repository]
        ConfigFiles[Configuration Files]
    end

    User --> Claude
    Claude --> MCP
    MCP --> ReqMgr
    MCP --> KanbanMgr
    MCP --> GitMgr
    MCP --> AgentMgr
    MCP --> ValidationMgr
    MCP --> RulesMgr
    MCP --> SyncMgr

    ReqMgr --> ChangeDetect
    KanbanMgr --> ChangeDetect
    GitMgr --> ChangeDetect

    ChangeDetect --> ConflictRes
    ConflictRes --> EventEmit

    EventEmit --> LocalFS
    EventEmit --> GitRepo
    EventEmit --> ConfigFiles

Backend Integration Options

graph TB
    subgraph "MCP Server"
        Sync[Synchronization Layer]
        Webhook[Webhook Integration]
    end

    subgraph "Backend Options"
        REST[REST Backend]
        GraphQL[GraphQL Backend]
        WebSocket[WebSocket Backend]
    end

    subgraph "Data Storage"
        API[REST API Server]
        DB[Database Direct]
    end

    Sync --> REST
    Sync --> GraphQL
    Sync --> WebSocket
    Webhook --> REST
    Webhook --> GraphQL
    Webhook --> WebSocket

    REST --> API
    GraphQL --> API
    WebSocket --> API

    REST --> DB
    GraphQL --> DB
    WebSocket --> DB

Higher-Level System Integration

graph TB
    subgraph "MCP Server Layer"
        MCP[MCP Server]
    end

    subgraph "Higher-Level Systems"
        Enterprise[Enterprise Systems]
        Cloud[Cloud Platforms]
        CICD[CI/CD Pipelines]
        Monitoring[Monitoring Systems]
    end

    MCP --> Enterprise
    MCP --> Cloud
    MCP --> CICD
    MCP --> Monitoring

Integration Capabilities

Project Management (Jira, Asana, Linear)
Quality Systems (QMS platforms)
Compliance Tracking (GRC systems)
Analytics/Metrics (Business Intelligence)
Team Collaboration (Slack, Teams, Discord)

Integration Layers

Layer 1: Claude Code ↔ MCP Server

Protocol: Model Context Protocol (MCP) over stdio/JSON-RPC

Capabilities:

Tool-based operations (requirements, kanban, git, etc.)
Resource access (bulk data retrieval)
Real-time context awareness
Structured error handling

Benefits:

Native integration with Claude Code
No HTTP overhead
Type-safe communication
Bidirectional streaming

Layer 2: MCP Server ↔ Local System

Integration Points:

File system operations
Git repository access
Shell command execution
Configuration management

Managers:

RequirementsManager - Requirements CRUD operations
KanbanManager - Task board management
ValidationManager - Quality gate enforcement
GitManager - Git workflow automation
AgentManager - Agent handoff/collaboration
RulesManager - Context-aware rule application

Layer 3: Local System ↔ Higher-Level Systems

Synchronization:

Bidirectional change propagation
Conflict detection and resolution
Event-driven webhooks
Metrics collection

Backends:

REST API - Standard HTTP/HTTPS
GraphQL - Query-based API
WebSocket - Real-time bidirectional
Custom - User-defined implementations

Data Flow

Read Operations

Claude Code → Tool Request → MCP Server
MCP Server → Manager → Local Files
Local Files → Parse/Validate → Manager
Manager → Structured Data → MCP Server
MCP Server → JSON Response → Claude Code

Example:

User: "Show critical requirements"
→ sc_req_list(priority="Critical")
→ RequirementsManager.list({priority: "Critical"})
→ Read from supernal-coding/requirements/**/*.md
→ Parse YAML frontmatter + Gherkin scenarios
→ Return filtered list

Write Operations

Claude Code → Tool Request → MCP Server
MCP Server → Manager → Validation
Validation OK → Local Files Updated
Update Detection → Sync Manager
Sync Manager → Change Queue
[Auto-sync enabled] → Backend.push()
Backend → Higher-Level System

Example:

User: "Create authentication requirement"
→ sc_req_new(title="User Auth", epic="security")
→ RequirementsManager.create({...})
→ Execute: sc req new "User Auth" --epic=security
→ File created: requirements/security/req-XXX-user-auth.md
→ SyncManager.addPendingChange({type: "requirement", ...})
→ [Auto-sync] → Backend.push([change])
→ POST https://api.example.com/supernal/push

Synchronization Flow

┌──────────────────────────────────────────────────┐
│              Sync Cycle (Every N seconds)        │
└──────────────────┬───────────────────────────────┘
                   │
         ┌─────────┴─────────┐
         │  1. Pull Remote   │
         │     Changes       │
         └─────────┬─────────┘
                   │
         ┌─────────┴─────────┐
         │  2. Detect        │
         │     Conflicts     │
         └─────────┬─────────┘
                   │
         ┌─────────┴─────────┐
         │  3. Resolve       │ ← Strategy: manual/local/remote/latest
         │     Conflicts     │
         └─────────┬─────────┘
                   │
         ┌─────────┴─────────┐
         │  4. Apply         │
         │     Changes       │
         └─────────┬─────────┘
                   │
         ┌─────────┴─────────┐
         │  5. Push Local    │
         │     Changes       │
         └─────────┬─────────┘
                   │
         ┌─────────┴─────────┐
         │  6. Update        │
         │     Status        │
         └───────────────────┘

Communication Patterns

Request/Response (Tools)

Used for discrete operations:

{
  "method": "tools/call",
  "params": {
    "name": "sc_req_validate",
    "arguments": {
      "id": "REQ-037"
    }
  }
}

Resource Access (Bulk Data)

Used for large data sets:

{
  "method": "resources/read",
  "params": {
    "uri": "requirements://list"
  }
}

Event-Driven (Webhooks)

Used for async notifications:

{
  "event": "sync.conflict",
  "data": {
    "id": "REQ-037",
    "local": {...},
    "remote": {...}
  },
  "timestamp": "2025-10-27T20:00:00Z"
}

Scalability Considerations

Caching Strategy

┌──────────────────────────────────────┐
│         MCP Server Cache             │
├──────────────────────────────────────┤
│ Requirements List   (TTL: 5min)      │
│ Kanban Boards       (TTL: 2min)      │
│ Active Rules        (TTL: 10min)     │
│ Config              (TTL: 30min)     │
└──────────────────────────────────────┘

Invalidation:

File system changes → Invalidate related cache
Config updates → Invalidate config cache
Manual invalidation via tool

Batch Operations

Good:

Access requirements://list (all at once)
Process locally in Claude Code

Bad:

Loop: sc_req_read(id) for each requirement
Multiple tool calls

Sync Optimization

[sync]
# Reduce frequency
syncInterval = 300000  # 5 minutes

# Filter what syncs
[sync.filters]
includeRequirements = true
includeKanban = true
includeRules = false
excludePatterns = ["*.draft.md", "*.local.md"]

# Batch changes
batchSize = 50  # Push 50 changes at once
batchDelay = 5000  # Wait 5s to accumulate changes

Security Architecture

Authentication

┌─────────────┐
│ Claude Code │
└──────┬──────┘
       │ MCP (local, trusted)
┌──────┴──────┐
│ MCP Server  │
└──────┬──────┘
       │ API Key (env var)
┌──────┴──────┐
│   Backend   │
└──────┬──────┘
       │ Auth Header
┌──────┴──────┐
│ Remote API  │
└─────────────┘

Data Privacy

Local Data:

Stored in project directory
Subject to .gitignore
Not shared without consent

Sync Data:

Filtered by configuration
Encrypted in transit (HTTPS/WSS)
API key required
User consent respected

Consent Modes:

ai_agent_deny - No automatic sharing
manual - Ask every time
never - Never sync
always - Auto-sync (with filters)

Error Handling

Resilience Strategy

┌──────────────┐
│  Tool Call   │
└──────┬───────┘
       │
   ┌───┴────┐
   │ Retry? │ ← Transient errors: network, timeout
   └───┬────┘
       │
   ┌───┴────┐
   │Fallback│ ← Degraded mode: cache, local-only
   └───┬────┘
       │
   ┌───┴────┐
   │ Error  │ ← Structured error with guidance
   └────────┘

Error Types

Tool Errors - Invalid parameters, not found
Sync Errors - Network, conflicts, auth
Validation Errors - Pre-commit hooks, validation
System Errors - File access, permissions

Monitoring & Observability

Metrics Collection

[metrics]
enabled = true
endpoint = "https://metrics.example.com"
reportInterval = 300000  # 5 minutes

collectToolUsage = true
collectSyncMetrics = true
collectValidationMetrics = true
collectPerformanceMetrics = true

Collected Metrics:

Tool call frequency and latency
Sync success/failure rates
Conflict resolution outcomes
Cache hit/miss rates
Error rates by type

Health Checks

Backend Health Check (every sync cycle):
- GET /health
- Verify connectivity
- Check auth validity
- Report to sync status

Extension Points

Custom Tools

Add domain-specific tools:

// tools/my-tool.js
class MyTool {
  async myOperation(params) {
    // Custom logic
  }
}

Custom Backends

Integrate with any system:

// sync/backends/my-backend.js
class MyBackend {
  async push(changes) {
    // Custom sync logic
  }

  async pull() {
    // Custom retrieval
  }
}

Custom Webhooks

React to events:

[sync.webhooks]
onPush = "https://api.example.com/webhook/push"
onConflict = "https://api.example.com/webhook/conflict"

Best Practices

1. Use Appropriate Integration Layer

Simple operations → MCP tools
Bulk data → MCP resources
External systems → Sync layer

2. Optimize Data Transfer

Use resources for bulk access
Enable caching
Filter synced data
Batch operations

3. Handle Errors Gracefully

Provide clear error messages
Offer recovery options
Fall back to local-only
Log for debugging

4. Secure Communications

Use HTTPS/WSS only
Store keys in env vars
Respect consent settings
Audit access

5. Monitor Performance

Track metrics
Set up alerts
Review logs
Optimize bottlenecks

System Overview​

Backend Integration Options​

Higher-Level System Integration​

Integration Capabilities​

Integration Layers​

Layer 1: Claude Code ↔ MCP Server​

Layer 2: MCP Server ↔ Local System​

Layer 3: Local System ↔ Higher-Level Systems​

Data Flow​

Read Operations​

Write Operations​

Synchronization Flow​

Communication Patterns​

Request/Response (Tools)​

Resource Access (Bulk Data)​

Event-Driven (Webhooks)​

Scalability Considerations​

Caching Strategy​

Batch Operations​

Sync Optimization​

Security Architecture​

Authentication​

Data Privacy​

Error Handling​

Resilience Strategy​

Error Types​

Monitoring & Observability​

Metrics Collection​

Health Checks​

Extension Points​

Custom Tools​

Custom Backends​

Custom Webhooks​

Best Practices​

1. Use Appropriate Integration Layer​

2. Optimize Data Transfer​

3. Handle Errors Gracefully​

4. Secure Communications​

5. Monitor Performance​

Next Steps​