dss/ARCHITECTURE_MCP_FIRST.md

DSS MCP-First Architecture

Why MCP? Why Not REST?

You were absolutely right to question REST endpoints. Here's why MCP-first is the right approach for DSS:

The Problem with REST (Traditional Approach)

JavaScript Chat UI
    ↓
REST API (/api/projects, /api/manifest, etc.)
    ↓
Python Backend
    ↓
Database/Filesystem
    ↓
Response → Chat UI

Issues:

• ❌ Duplicate business logic (REST endpoint + MCP tool)
• ❌ Latency: JS → HTTP → Python → DB → HTTP → JS
• ❌ Two implementations of same feature
• ❌ Hard to test end-to-end
• ❌ Claude can't directly call your tools
• ❌ Requires building REST wrapper around everything

---

The MCP-First Solution

JavaScript Chat UI
    ↓
Claude (with MCP tools available)
    ↓
Call MCP Tool (tool_use)
    ↓
Python MCP Server
    ↓
Database/Filesystem
    ↓
Response → Claude → Chat UI

Benefits:

• ✅ Single source of truth (MCP tool)
• ✅ Claude makes intelligent decisions
• ✅ Native tool_use integration
• ✅ No REST endpoints to maintain
• ✅ Better context awareness
• ✅ Simpler architecture

---

The Workflow

Old Way (REST-based)

// UI code
const response = await fetch('/api/projects', {
  method: 'POST',
  body: JSON.stringify({name, root_path, description})
});
const project = await response.json();

New Way (MCP-first)

// Chat interprets: "create project test in ./src"
// JavaScript just parses and sends to Claude:

{
  action: 'call_mcp_tool',
  tool: 'dss_create_project',
  args: {name, root_path, description}
}

// Claude receives the tool result and responds naturally

---

Component Roles

JavaScript (Frontend)

• Parse natural language input
• Extract structured parameters using AI
• Display MCP tool results
• Manage chat conversation
• Does NOT make API calls

Claude (AI Agent)

• Understands user intent
• Calls appropriate MCP tools
• Chains tools together (e.g., create project → setup Figma → discover files)
• Returns human-readable results
• Orchestrates the workflow

MCP Server (Backend)

• Implements all business logic as tools
• Reads/writes to database and filesystem
• Manages project manifests
• Handles Figma API integration
• Encrypts credentials
• Audit logging
• Single implementation

---

Architecture Comparison

Aspect	REST Approach	MCP-First Approach
API Endpoints	Many (/projects, /manifest, /figma, etc.)	None (just MCP tools)
Where logic lives	Scattered (REST + MCP)	Centralized (MCP tools only)
Data flow	JS → HTTP → Python → DB → HTTP → JS	JS → Claude → MCP Server → DB
Claude integration	Hooks into REST responses	Direct tool_use
Debugging	Need to trace both REST and MCP	Trace MCP tool directly
Tool reusability	Limited	All MCP tools available to Claude
Latency	2 HTTP roundtrips	1 MCP tool call
Testing	Unit test REST, unit test MCP	Integration test MCP tools

---

Implementation Phases

Phase 1: Implement MCP Tools

• Add 6 new MCP tools to tools/dss_mcp/tools/project_tools.py
• Implement manifest management
• Encrypt Figma credentials in database
• Register tools in handler

Phase 2: Update JavaScript

• Remove REST calls
• Keep command parsing
• Return MCP tool specifications
• Let Claude execute tools

Phase 3: End-to-End Testing

• Test full workflow: user input → Claude → MCP tool → result
• Verify credential encryption
• Test manifest creation/updates
• Test Figma API integration

---

Example Workflow: Create Project with Figma

User says:

"Create a design system project called web-ui in ./packages/design with my Figma workspace"

JavaScript processes:

// Parse natural language
const command = '/init'
const params = {
  name: 'web-ui',
  root_path: './packages/design'
}

Claude orchestrates:

1. Ask for Figma API token if not already configured
2. Call dss_setup_figma_credentials (if needed)
3. Call dss_create_project
4. Call dss_discover_figma_files
5. Return summary to user

Each tool runs:

# Tool 1: dss_create_project
- Create project in database
- Create figma.json manifest
- Return project_id

# Tool 2: dss_setup_figma_credentials (cached if already set)
- Encrypt and store token
- Validate with Figma API

# Tool 3: dss_discover_figma_files
- Read credentials from database
- Query Figma API for user's files
- Return suggestions

Result:

✅ Project created: web-ui
✅ Figma credentials stored
✅ Found 5 Figma files:
   - Design Tokens
   - Components
   - Icons
   - Patterns
   - Documentation

Next steps:
- /add-figma <file_key> to link specific files
- /sync to extract tokens
- /analyze to scan for components

---

Database Schema Integration

Existing Tables Used:

• projects - Project metadata
• project_integrations - User-scoped encrypted credentials
• integration_health - API health monitoring
• mcp_tool_usage - Audit log

No New Tables Needed!

The existing schema already supports:

• Project creation
• User-scoped credentials
• Integration health tracking
• Tool usage auditing

Manifest Location:

• File-based: {project_root}/figma.json
• Version controlled: Can be checked into git
• Fast access: Direct filesystem read/write
• Auditable: Last modified timestamp

---

Security

Credential Storage

User Input: "figd_pAT_xxxxxxxxxxxx"
    ↓
Encrypted with Fernet: cipher.encrypt(config.encode())
    ↓
Stored in project_integrations.config
    ↓
Retrieved and decrypted when needed
    ↓
Never exposed to frontend

User Isolation

• Credentials scoped to user_id
• Each project can have user's own integration configs
• No global shared credentials
• Audit trail of all tool usage

Circuit Breaker

• Protects against cascading Figma API failures
• Fails gracefully with clear error messages
• Tracks integration health
• Automatic recovery

---

Why This is Better

1. Single Source of Truth

   • MCP tools define everything
   • No REST endpoints to maintain
   • No duplication

2. Better User Experience

   • Claude understands context
   • Can chain operations (create → setup → discover)
   • Returns natural language feedback
   • Anticipates next steps

3. Easier to Debug

   • Trace single execution path
   • Clear tool input/output
   • Audit log of all operations
   • No HTTP layer to troubleshoot

4. Scales Better

   • Add new tools without REST endpoints
   • Claude can discover and use new tools
   • No coordination between layers
   • Clear separation of concerns

5. More Secure

   • Credentials never exposed to frontend
   • Encrypted storage in database
   • User-scoped access control
   • Complete audit trail

---

Next Steps

1. Backend Implementation

   • Implement 6 MCP tools (see MCP_TOOLS_SPEC.md)
   • Add encryption to project_integrations
   • Register tools in handler
   • Test with MCP client

2. Frontend Updates

   • Keep command parsing in JavaScript
   • Return MCP tool specifications
   • Let Claude handle execution
   • Display results naturally

3. Testing

   • Test each MCP tool individually
   • Test end-to-end workflow
   • Verify encryption/decryption
   • Load test Figma API calls

4. Documentation

   • Update user guides
   • Document command flow
   • Add troubleshooting guide
   • Create architecture diagram

---

Result

A true MCP-first, AI-native design system platform where:

• Claude orchestrates all operations
• Tools are the single source of truth
• No REST API complexity
• Clean, maintainable architecture
• Better user experience
• Maximum security

This is how modern AI applications should be built! 🚀