# 🏗️ NTV Scaffolding MCP Server - Architecture
## System Overview
```
┌─────────────────────────────────────────────────────────────────────────┐
│ AI CLIENTS / CONSUMERS │
├─────────┬──────────────┬──────────────┬──────────────┬──────────────────┤
│ Cursor │ VS Code │ Cody │ Claude API │ Command Line │
│ Editor │ + MCP Ext │ (Sourcegraph)│ │ │
└────────┬┘──────┬──────┘──────┬───────┘──────┬───────┘────────┬─────────┘
│ │ │ │ │
│ └─────────────┼───────────────┼────────────────┤
│ ▼ │ │
│ ┌──────────────────────┴────────────────┘
│ │
│ ▼
┌────────────────────────────────────────────────────────────────────────┐
│ MCP Server (NTV Scaffolding MCP) │
│ ┌────────────────────────────────────────────────┐ │
│ │ main: src/index.ts │ │
│ │ - MCP Protocol Handler │ │
│ │ - Tool Registry │ │
│ │ - Error Handling │ │
│ └────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ TOOLS LAYER │ │
│ │ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │ │
│ │ │ list_ntv_ │ │ get_ntv_ │ │ get_ntv_ │ │ │
│ │ │ components │ │ component_doc │ │ component_ │ │ │
│ │ └────────────────┘ └────────────────┘ │ props │ │ │
│ │ └────────────────┘ │ │
│ │ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │ │
│ │ │ generate_ntv_ │ │ generate_ntv_ │ │ generate_ntv_ │ │ │
│ │ │ template_code │ │ component_ │ │ component_ │ │ │
│ │ │ │ │ usage │ │ file │ │ │
│ │ └────────────────┘ └────────────────┘ └────────────────┘ │ │
│ │ │ │
│ │ ┌────────────────┐ │ │
│ │ │ get_ntv_ │ │ │
│ │ │ component_ │ │ │
│ │ │ examples │ │ │
│ │ └────────────────┘ │ │
│ │ │ │
│ │ src/tools/ │ │
│ │ ├── index.ts (Tool Registry) │ │
│ │ ├── listComponents.ts │ │
│ │ ├── getComponentDoc.ts │ │
│ │ ├── getComponentProps.ts │ │
│ │ ├── generateTemplateCode.ts │ │
│ │ ├── generateComponentUsage.ts │ │
│ │ ├── generateComponent.ts │ │
│ │ └── getComponentExamples.ts │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ DATA LAYER │ │
│ │ │ │
│ │ src/data/components.ts │ │
│ │ ┌────────────────────────────────────────────────────────────┐ │ │
│ │ │ COMPONENTS_DB: Component[] │ │ │
│ │ │ │ │ │
│ │ │ ├── Button ├── Input ├── Card │ │ │
│ │ │ ├── Autocomplete ├── Accordion ├── Stepper │ │ │
│ │ │ ├── Popover ├── ThumbnailGal ├── Modal │ │ │
│ │ │ └── Template │ │ │
│ │ │ │ │ │
│ │ │ Each component contains: │ │ │
│ │ │ • Metadata (name, selector, category) │ │ │
│ │ │ • Properties with types & defaults │ │ │
│ │ │ • Events & Slots │ │ │
│ │ │ • Usage Examples │ │ │
│ │ │ • Best Practices │ │ │
│ │ └────────────────────────────────────────────────────────────┘ │ │
│ └──────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────┘
│
▼
┌───────────────────────────┐
│ Generated Output: │
│ • Component Docs │
│ • Code Templates │
│ • Usage Examples │
│ • Component Files │
└───────────────────────────┘
```
## Component Architecture
```
┌─────────────────────────────────────────────────────────┐
│ Component Interface (from DB) │
├─────────────────────────────────────────────────────────┤
│ │
│ interface Component { │
│ name: string; ┐ │
│ selector: string; │ │
│ category: ComponentCategory; ├─ Metadata │
│ description: string; │ │
│ ┘ │
│ props: ComponentProp[]; ┐ │
│ events: ComponentEvent[]; ├─ API │
│ slots: ComponentSlot[]; │ │
│ configInterface?: string; ┘ │
│ ┐ │
│ examples: ComponentExample[]; ├─ Documentation │
│ bestPractices: string[]; │ │
│ } ┘ │
│ │
└─────────────────────────────────────────────────────────┘
```
## Tool Execution Flow
```
┌──────────────────┐
│ AI Client │
│ (e.g., Cursor) │
└────────┬─────────┘
│
│ "Generate a primary Button"
│
▼
┌──────────────────────────────────┐
│ MCP Server │
│ - Receives tool call │
│ - Validates parameters │
│ - Routes to appropriate tool │
└────────┬─────────────────────────┘
│
▼
┌────────────────────────────────────────────┐
│ Tool: generate_ntv_template_code │
│ Input: { │
│ component: "Button", │
│ variant: "primary", │
│ size: "lg" │
│ } │
└────────┬─────────────────────────────────┘
│
▼
┌────────────────────────────────────────────┐
│ Lookup Component in Database │
│ Find: COMPONENTS_DB.find(c => c.name │
│ === "Button") │
└────────┬─────────────────────────────────┘
│
▼
┌────────────────────────────────────────────┐
│ Generate Template Code │
│ - Build prop strings │
│ - Generate imports │
│ - Format template │
└────────┬─────────────────────────────────┘
│
▼
┌────────────────────────────────────────────┐
│ Return Result to AI Client │
│ { │
│ template: "<ntv-button [config]='...'>", │
│ imports: "import { Button } from...", │
│ componentDecorator: {...} │
│ } │
└────────────────────────────────────────────┘
│
▼
┌──────────────────┐
│ AI Client │
│ Uses result │
└──────────────────┘
```
## Data Flow Architecture
```
┌─ listComponents
│
├─ getComponentDoc ───┐
AI Client ────→ │ │
(various) ├─ getComponentProps ├─→ Components DB ─→ Response
│ │
├─ generateTemplateCode
│
├─ generateComponentUsage
│
├─ generateComponent
│
└─ getComponentExamples
```
## Folder Structure & Responsibilities
```
component-mcp/
│
├── src/
│ ├── index.ts
│ │ └─ Purpose: MCP Server initialization & protocol handling
│ │
│ ├── tools/
│ │ ├── index.ts
│ │ │ └─ Registry: Exports all tools
│ │ │
│ │ ├── listComponents.ts
│ │ │ └─ Lists available components with filtering
│ │ │
│ │ ├── getComponentDoc.ts
│ │ │ └─ Full documentation for a component
│ │ │
│ │ ├── getComponentProps.ts
│ │ │ └─ Property details and types
│ │ │
│ │ ├── generateTemplateCode.ts
│ │ │ └─ HTML template generation
│ │ │
│ │ ├── generateComponentUsage.ts
│ │ │ └─ Full component usage examples
│ │ │
│ │ ├── generateComponent.ts
│ │ │ └─ Complete component file generation
│ │ │
│ │ └── getComponentExamples.ts
│ │ └─ Predefined usage snippets
│ │
│ ├── data/
│ │ └── components.ts
│ │ └─ Component database (all metadata)
│ │
│ └── resources/
│ └── index.ts
│ └─ Resource handlers (extensible)
│
├── dist/
│ └─ Compiled JavaScript output
│
├── Configuration Files
│ ├── package.json (Dependencies & scripts)
│ ├── tsconfig.json (TypeScript config)
│ └── .gitignore (Git configuration)
│
└── Documentation
├── README.md (Full documentation)
├── QUICK_START.md (3-minute setup)
├── INTEGRATION.md (AI client setup)
├── PROJECT_SUMMARY.md (Overview)
└── ARCHITECTURE.md (This file)
```
## Tool Interaction Patterns
### Pattern 1: Simple Lookup
```
get_ntv_component_doc(component: "Button")
└─→ Search COMPONENTS_DB
└─→ Return found component metadata
```
### Pattern 2: Template Generation
```
generate_ntv_template_code(component, variant, size, ...)
└─→ Find component in DB
└─→ Build config object
└─→ Generate HTML template
└─→ Include import statement
```
### Pattern 3: Code Generation
```
generate_ntv_component_file(component, filename, selector, ...)
└─→ Find component
└─→ Generate TypeScript file
└─→ Generate HTML template
└─→ Generate CSS file
└─→ Generate test file
```
## Extensibility Points
```
┌──────────────────────────────────────────────┐
│ Add New Tool │
│ 1. Create src/tools/myTool.ts │
│ 2. Implement MCPTool interface │
│ 3. Export from src/tools/index.ts │
│ 4. Automatically registered │
└──────────────────────────────────────────────┘
┌──────────────────────────────────────────────┐
│ Add New Component │
│ 1. Edit src/data/components.ts │
│ 2. Add to COMPONENTS_DB array │
│ 3. Rebuild: npm run build │
│ 4. Restart server: npm start │
└──────────────────────────────────────────────┘
```
## Deployment Architecture
```
Development:
┌─────────────────┐
│ source code │
│ (TypeScript) │
└────────┬────────┘
│ npm run build
▼
┌─────────────────┐
│ dist/ │
│ (JavaScript) │
└────────┬────────┘
│ npm run dev (ts-node)
▼
┌─────────────────┐
│ MCP Server │
│ (localhost) │
└─────────────────┘
Production:
┌─────────────────┐
│ source code │
└────────┬────────┘
│ npm run build
▼
┌─────────────────┐
│ dist/ │
└────────┬────────┘
│ npm start (node dist/index.js)
▼
┌─────────────────┐
│ MCP Server │
│ (production) │
└─────────────────┘
Docker:
┌─────────────────┐
│ Dockerfile │
└────────┬────────┘
│ docker build
▼
┌─────────────────┐
│ Docker Image │
└────────┬────────┘
│ docker run
▼
┌─────────────────┐
│ Container │
│ MCP Server │
└─────────────────┘
```
## Performance Characteristics
```
Operation Time Space
────────────────────────────────────────
List Components O(n) O(n)
Get Component Doc O(log n) O(1)
Generate Template O(1) O(n)
Generate Component O(1) O(n)
Get Examples O(1) O(m)
Legend:
n = number of components (currently 10)
m = number of examples per component
```
## Security Model
```
Input → Validation → Safe Execution → Output
├─ Type checking
├─ Range validation
├─ Pattern matching
└─ Sanitization
```
---
**Architecture Version**: 1.0
**Last Updated**: October 2025
**Status**: Production Ready ✅
