Initial commit: Clean DSS implementation
Migrated from design-system-swarm with fresh git history.
Old project history preserved in /home/overbits/apps/design-system-swarm
Core components:
- MCP Server (Python FastAPI with mcp 1.23.1)
- Claude Plugin (agents, commands, skills, strategies, hooks, core)
- DSS Backend (dss-mvp1 - token translation, Figma sync)
- Admin UI (Node.js/React)
- Server (Node.js/Express)
- Storybook integration (dss-mvp1/.storybook)
Self-contained configuration:
- All paths relative or use DSS_BASE_PATH=/home/overbits/dss
- PYTHONPATH configured for dss-mvp1 and dss-claude-plugin
- .env file with all configuration
- Claude plugin uses ${CLAUDE_PLUGIN_ROOT} for portability
Migration completed: $(date)
🤖 Clean migration with full functionality preserved
This commit is contained in:
Digital Production Factory
336
ARCHITECTURE_MCP_FIRST.md
Normal file
336
ARCHITECTURE_MCP_FIRST.md
Normal file
@@ -0,0 +1,336 @@
|
||||
# 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)
|
||||
|
||||
```javascript
|
||||
// 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)
|
||||
|
||||
```javascript
|
||||
// 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:
|
||||
```javascript
|
||||
// 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:
|
||||
```python
|
||||
# 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!** 🚀
|
||||
Reference in New Issue
Block a user