NTV Scaffolding MCP Server

# 🏗️ 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 ✅