1

Sprint-1-viz-platform-Implementation-Plan

Leo Miranda edited this page 2026-01-26 16:23:09 +00:00

Table of Contents

• Sprint 1: viz-platform Plugin Implementation Plan
• Sprint Overview
• Scope
• Key Decisions
• Issues Created
• Dependency Graph
• Execution Order (Parallel Batches)
• Batch 1 (Foundation)
• Batch 2 (Core Tools - can run in parallel)
• Batch 3 (Dependent Tools)
• Batch 4 (Plugin Integration)
• Batch 5 (Testing)
• Batch 6 (Final)
• Technical Architecture
• MCP Server Structure
• Plugin Structure
• Tool Specifications
• DMC Tools (Constraint Layer)
• Chart Tools
• Layout Tools
• Theme Tools
• Page Tools
• Design Token Structure
• Success Criteria
• Cross-Plugin Integration
• Next Sprint Preview

Sprint 1: viz-platform Plugin Implementation Plan

Milestone: Sprint 1 - viz-platform Plugin Created: 2026-01-26 Status: Planning Complete Reference: docs/changes/CHANGE_V04_0_0_PROPOSAL_ORIGINAL.md (Phases 4-5)

---

Sprint Overview

Implement the viz-platform plugin with DMC component validation and visualization capabilities.

Scope

Component	Count	Description
MCP Server	1	mcp-servers/viz-platform/
Tools	15	DMC (3), Chart (2), Layout (3), Theme (4), Page (3)
Commands	7	/chart, /dashboard, /theme, /component, etc.
Agents	3	theme-setup, layout-builder, component-check

Key Decisions

Decision	Choice	Rationale
Component Registry	Static JSON	Fast, deterministic, offline-capable
Data Sharing	Claude passes inline	Simplest for v1, no shared state
Theme Storage	User + Project level	Project takes precedence

---

Issues Created

#	Title	Type	Priority	Effort	Dependencies
#170	Create viz-platform MCP server foundation	feat	High	M	None
#171	Implement DMC component registry with static JSON	feat	High	L	#170
#172	Implement DMC validation tools (3 tools)	feat	High	M	#170, #171
#173	Implement chart tools (2 tools)	feat	High	M	#170
#174	Implement layout tools (3 tools)	feat	Medium	M	#170
#175	Implement theme tools (4 tools)	feat	High	L	#170
#176	Implement page tools (3 tools)	feat	Medium	M	#170, #174
#177	Create viz-platform plugin structure	feat	High	S	#170
#178	Create viz-platform commands (7 commands)	feat	Medium	S	#177
#179	Create viz-platform agents (3 agents)	feat	Medium	M	#177, #172, #175
#180	Create viz-platform documentation	docs	Medium	M	#177
#181	Add viz-platform to marketplace	feat	High	S	ALL
#182	Create viz-platform MCP server tests	test	Medium	L	#170-#175

Total Issues: 13

---

Dependency Graph

#170 (Foundation)
  ├── #171 (Registry) ──► #172 (DMC Tools)
  ├── #173 (Chart Tools)
  ├── #174 (Layout Tools) ──► #176 (Page Tools)
  ├── #175 (Theme Tools)
  └── #177 (Plugin Structure)
        ├── #178 (Commands)
        ├── #179 (Agents) ◄── #172, #175
        └── #180 (Documentation)

#182 (Marketplace Integration) ◄── ALL ISSUES

#182 (Tests) ◄── #170, #171, #172, #173, #175

---

Execution Order (Parallel Batches)

Batch 1 (Foundation)

• #170: MCP server foundation

Batch 2 (Core Tools - can run in parallel)

• #171: Component registry
• #173: Chart tools
• #174: Layout tools
• #175: Theme tools

Batch 3 (Dependent Tools)

• #172: DMC validation tools (needs #171)
• #176: Page tools (needs #174)
• #177: Plugin structure (needs #170)

Batch 4 (Plugin Integration)

• #178: Commands (needs #177)
• #179: Agents (needs #177, #172, #175)
• #180: Documentation (needs #177)

Batch 5 (Testing)

• #182: Tests (needs core tools)

Batch 6 (Final)

• #181: Marketplace integration (needs ALL)

---

Technical Architecture

MCP Server Structure

mcp-servers/viz-platform/
├── mcp_server/
│   ├── __init__.py
│   ├── server.py              # Entry point
│   ├── config.py              # DMC version detection
│   ├── component_registry.py  # Static JSON loader
│   ├── dmc_tools.py           # list_components, get_component_props, validate_component
│   ├── chart_tools.py         # chart_create, chart_configure_interaction
│   ├── layout_tools.py        # layout_create, layout_add_filter, layout_set_grid
│   ├── theme_tools.py         # theme_create, theme_extend, theme_validate, theme_export_css
│   ├── theme_store.py         # Theme persistence
│   └── page_tools.py          # page_create, page_add_navbar, page_set_auth
├── registry/
│   └── dmc_0.14.json          # Version-locked component definitions
├── scripts/
│   └── generate-dmc-registry.py
├── tests/
├── requirements.txt
└── pyproject.toml

Plugin Structure

plugins/viz-platform/
├── .claude-plugin/
│   └── plugin.json
├── .mcp.json
├── mcp-servers/
│   └── viz-platform -> ../../../mcp-servers/viz-platform
├── commands/
│   ├── initial-setup.md
│   ├── chart.md
│   ├── dashboard.md
│   ├── theme.md
│   ├── theme-new.md
│   ├── theme-css.md
│   └── component.md
├── agents/
│   ├── theme-setup.md
│   ├── layout-builder.md
│   └── component-check.md
├── hooks/
│   └── hooks.json
├── README.md
└── claude-md-integration.md

---

Tool Specifications

DMC Tools (Constraint Layer)

Tool	Input	Output
list_components	category?: string	Component names by category
get_component_props	component: string	Props schema with types/defaults
validate_component	component: string, props: object	{valid, errors[], warnings[]}

Chart Tools

Tool	Input	Output
chart_create	chart_type, data, options?	Plotly figure JSON
chart_configure_interaction	figure_ref, interactions	Updated figure JSON

Layout Tools

Tool	Input	Output
layout_create	name, template?	Layout reference
layout_add_filter	layout_ref, filter_type, options	Updated layout
layout_set_grid	layout_ref, grid	Updated layout

Theme Tools

Tool	Input	Output
theme_create	name, tokens	Theme reference
theme_extend	base_theme, overrides	New theme reference
theme_validate	theme_name	Validation report
theme_export_css	theme_name	CSS custom properties

Page Tools

Tool	Input	Output
page_create	name, path, layout_ref?	Page reference
page_add_navbar	pages[], options	Navbar component
page_set_auth	page_ref, auth_config	Updated page

---

Design Token Structure

tokens:
  colors:
    primary: "#228be6"
    secondary: "#868e96"
    background:
      base: "#ffffff"
      subtle: "#f8f9fa"
    text:
      primary: "#212529"
      muted: "#868e96"
  spacing:
    xs: "4px"
    sm: "8px"
    md: "16px"
    lg: "24px"
  typography:
    fontFamily: "Inter, sans-serif"
    fontSize:
      sm: "14px"
      md: "16px"
  radii:
    sm: "4px"
    md: "8px"

---

Success Criteria

• MCP server starts without errors
• All 15 tools registered and functional
• Component registry loads for DMC 0.14.x
• validate_component catches invalid props
• Theme tokens apply to charts
• All 7 commands work via slash commands
• All 3 agents trigger correctly
• Plugin passes ./scripts/validate-marketplace.sh
• Tests pass with >70% coverage
• Documentation complete

---

Cross-Plugin Integration

After Sprint 1, projects can define cross-plugin agents in their CLAUDE.md:

| Agent | Sequence |
|-------|----------|
| dashboard_builder | pg_query → pandas.pivot → dmc.validate → chart_create → layout_create |
| visualization_prep | pg_query → pandas.reshape → chart_create |

---

Next Sprint Preview

Sprint 2: contract-validator Plugin

• Validates cross-plugin compatibility
• Parses plugin READMEs for interfaces
• Validates Claude.md agent definitions
• 3 commands, 2 agents, no MCP server