personal-projects/leo-claude-mktplace
Template
0
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update "unnamed"

Leo Miranda
2026-01-25 19:06:42 +00:00
parent 01f9ca1d42
commit b98b879ee8
1 changed files with 665 additions and 654 deletions
Download Patch File Download Diff File Expand all files Collapse all files

233
Change-V04.0.0%3A-Proposal.md → unnamed.md

@@ -1,3 +1,14 @@
> **Type:** Change Proposal
> **Version:** V04.0.0
> **Status:** Implemented
> **Date:** 2026-01-25
## Implementations
- [Change V04.0.0: Proposal (Implementation 1)](Change-V04.0.0:-Proposal-(Implementation-1)) - data-platform plugin
---
# MCP Data Platform — Architecture Reference
*Plugin taxonomy, server responsibilities, and interaction patterns for Leo data marketplace*
@@ -63,7 +74,7 @@ mcp_servers:
- dbt-mcp
```
Agents check server availability at runtime. If dbt-mcp is not loaded, dbt-related steps are skipped or surface “not available for this project.”
Agents check server availability at runtime. If dbt-mcp is not loaded, dbt-related steps are skipped or surface "not available for this project."
-----
@@ -79,12 +90,12 @@ Agents check server availability at runtime. If dbt-mcp is not loaded, dbt-relat
#### Tool Categories
|Category |Tools |Description |
|---------|-----------------------------------------------------------------|-----------------------------------|
|Ingestion|`read_file`, `write_file`, `detect_encoding` |File I/O with format auto-detection|
|Profiling|`profile`, `validate`, `sample` |Data quality assessment |
|Schema |`infer_schema` |Generate DDL from data structure |
|Shaping |`reshape`, `pivot`, `melt`, `merge`, `add_columns`, `filter_rows`|Transform any data reference |
|Category |Tools |Description |
|---------|------------------------------------------------------------------|---------------------------------|
|Ingestion|`read_file`, `write_file`, `detect_encoding` |File I/O with format auto-detection|
|Profiling|`profile`, `validate`, `sample` |Data quality assessment |
|Schema |`infer_schema` |Generate DDL from data structure |
|Shaping |`reshape`, `pivot`, `melt`, `merge`, `add_columns`, `filter_rows` |Transform any data reference |
#### Data Reference Sources
@@ -116,12 +127,12 @@ pandas-mcp accepts `data_ref` from multiple origins:
#### Tool Categories
|Category|Tools |Description |
|--------|------------------------------------------------------------------------------------|--------------------------------------|
|Query |`list_schemas`, `list_tables`, `get_table_schema`, `execute_query`, `query_geometry`|Read operations |
|Analysis|`explain_query`, `recommend_indexes`, `health_check` |Performance insights |
|Write |`execute_write`, `load_dataframe` |Data modification |
|DDL |`execute_ddl`, `get_schema_snapshot` |Schema management with change tracking|
|Category|Tools |Description |
|--------|---------------------------------------------------------------------------------------------------|-------------------------------------|
|Query |`list_schemas`, `list_tables`, `get_table_schema`, `execute_query`, `query_geometry` |Read operations |
|Analysis|`explain_query`, `recommend_indexes`, `health_check` |Performance insights |
|Write |`execute_write`, `load_dataframe` |Data modification |
|DDL |`execute_ddl`, `get_schema_snapshot` |Schema management with change tracking|
#### DDL Change Tracking
@@ -155,12 +166,12 @@ This enables documentation updates, ERD regeneration (via Mermaid Chart MCP), or
#### Tool Categories
|Category |Tools |Description |
|-------------|-----------------------------------------------|------------------------|
|Discovery |`parse_manifest`, `list_models`, `list_sources`|Project exploration |
|Model |`get_model`, `get_lineage`, `compile_sql` |Model inspection |
|Execution |`run_model`, `test_model`, `get_run_results` |dbt CLI wrapper |
|Documentation|`generate_yaml` |Auto-generate schema.yml|
|Category |Tools |Description |
|-------------|-------------------------------------------------|------------------------|
|Discovery |`parse_manifest`, `list_models`, `list_sources` |Project exploration |
|Model |`get_model`, `get_lineage`, `compile_sql` |Model inspection |
|Execution |`run_model`, `test_model`, `get_run_results` |dbt CLI wrapper |
|Documentation|`generate_yaml` |Auto-generate schema.yml|
#### Lineage Output
@@ -176,31 +187,31 @@ files → pandas-mcp → postgres-mcp ↔ dbt-mcp
(query results for reshaping)
```
|Flow |Description |
|-----------------|------------------------------------|
|files → pandas |Entry point for raw data |
|pandas → postgres|Schema inference, bulk loading |
|postgres ↔ dbt |dbt queries marts, postgres executes|
|postgres → pandas|Query results for reshaping |
|dbt → pandas |Model outputs for visualization prep|
|Flow |Description |
|-----------------|-------------------------------------|
|files → pandas |Entry point for raw data |
|pandas → postgres|Schema inference, bulk loading |
|postgres ↔ dbt |dbt queries marts, postgres executes |
|postgres → pandas|Query results for reshaping |
|dbt → pandas |Model outputs for visualization prep |
-----
### Agents (data-platform)
|Agent |Trigger |Sequence |
|----------------|--------------------------|----------------------------------------------------------------------------|
|`data_ingestion`|User provides file |read_file → profile → infer_schema → execute_ddl → load_dataframe → validate|
|`model_analysis`|User asks about dbt model |get_model → get_lineage → explain_query → test_model → synthesize |
|`full_pipeline` |File to materialized model|data_ingestion → create dbt model → run_model |
|Agent |Trigger |Sequence |
|----------------|--------------------------|----------------------------------------------------------------------------------|
|`data_ingestion`|User provides file |read_file → profile → infer_schema → execute_ddl → load_dataframe → validate |
|`model_analysis`|User asks about dbt model |get_model → get_lineage → explain_query → test_model → synthesize |
|`full_pipeline` |File to materialized model|data_ingestion → create dbt model → run_model |
**Behavior when dbt-mcp absent:**
|Agent |Behavior |
|----------------|-------------------------------------|
|`data_ingestion`|Runs fully (no dbt steps) |
|`model_analysis`|Skipped—surfaces “dbt not configured”|
|`full_pipeline` |Stops after load, prompts user |
|Agent |Behavior |
|----------------|-----------------------------------|
|`data_ingestion`|Runs fully (no dbt steps) |
|`model_analysis`|Skipped—surfaces "dbt not configured"|
|`full_pipeline` |Stops after load, prompts user |
-----
@@ -218,7 +229,7 @@ files → pandas-mcp → postgres-mcp ↔ dbt-mcp
|`/run {model}` |`dbt-mcp.run_model` |
|`/test {model}` |`dbt-mcp.test_model` |
dbt commands return graceful “dbt-mcp not loaded” when unavailable.
dbt commands return graceful "dbt-mcp not loaded" when unavailable.
-----
@@ -226,10 +237,10 @@ dbt commands return graceful “dbt-mcp not loaded” when unavailable.
### Servers
|Server |Responsibility |
|--------|---------------------------------------------------------|
|dmc-mcp |Version-locked component registry, prop validation |
|dash-mcp|Charts, layouts, pages, theming—validates against dmc-mcp|
|Server |Responsibility |
|--------|-----------------------------------------------------------|
|dmc-mcp |Version-locked component registry, prop validation |
|dash-mcp|Charts, layouts, pages, theming—validates against dmc-mcp |
-----
@@ -241,17 +252,17 @@ dbt commands return graceful “dbt-mcp not loaded” when unavailable.
#### Tool Categories
|Category |Tools |Description |
|-------------|---------------------|-------------------------------------|
|Discovery |`list_components` |What exists in installed version |
|Introspection|`get_component_props`|Valid props, types, defaults |
|Validation |`validate_component` |Check component definition before use|
|Category |Tools |Description |
|-------------|----------------------|-----------------------------------------|
|Discovery |`list_components` |What exists in installed version |
|Introspection|`get_component_props` |Valid props, types, defaults |
|Validation |`validate_component` |Check component definition before use |
#### Usage Pattern
Claude queries dmc-mcp first:
1. “What props does `dmc.Select` accept?” → `get_component_props`
1. "What props does `dmc.Select` accept?" → `get_component_props`
1. Build component with valid props
1. Pass to dash-mcp for rendering
@@ -267,12 +278,12 @@ dash-mcp validates against dmc-mcp before rendering. Invalid components fail fas
#### Tool Categories
|Category |Tools |Description |
|----------|--------------------------------------------------------------------|-------------------------------|
|`chart_*` |`chart_create`, `chart_configure_interaction` |Data visualization (Plotly) |
|`layout_*`|`layout_create`, `layout_add_filter`, `layout_set_grid` |Dashboard composition |
|`page_*` |`page_create`, `page_add_navbar`, `page_set_auth` |App-level structure |
|`theme_*` |`theme_create`, `theme_extend`, `theme_validate`, `theme_export_css`|Design tokens, component styles|
|Category |Tools |Description |
|----------|--------------------------------------------------------------------|---------------------------------|
|`chart_*` |`chart_create`, `chart_configure_interaction` |Data visualization (Plotly) |
|`layout_*`|`layout_create`, `layout_add_filter`, `layout_set_grid` |Dashboard composition |
|`page_*` |`page_create`, `page_add_navbar`, `page_set_auth` |App-level structure |
|`theme_*` |`theme_create`, `theme_extend`, `theme_validate`, `theme_export_css`|Design tokens, component styles |
#### Design Token Structure
@@ -335,11 +346,11 @@ dash-mcp always validates component definitions against dmc-mcp. No direct data
### Agents (viz-platform)
|Agent |Trigger |Sequence |
|-----------------|----------------------------------|----------------------------------------------------------------------|
|`theme_setup` |New project or brand consistency |list_themes → create_theme → register_component_style → validate_theme|
|`layout_builder` |User wants dashboard structure |create_layout → add_filter → apply_theme → preview |
|`component_check`|Before rendering any DMC component|get_component_props → validate_component → proceed or error |
|Agent |Trigger |Sequence |
|-----------------|-----------------------------------|------------------------------------------------------------------------------------|
|`theme_setup` |New project or brand consistency |list_themes → create_theme → register_component_style → validate_theme |
|`layout_builder` |User wants dashboard structure |create_layout → add_filter → apply_theme → preview |
|`component_check`|Before rendering any DMC component |get_component_props → validate_component → proceed or error |
-----
@@ -368,12 +379,12 @@ MCP servers do not call each other. Claude orchestrates:
### Documentation Layers
|Layer |Location |Purpose |
|------------------|-----------------------|------------------------------------|
|Plugin docs |Each plugin’s README.md|Declares inputs/outputs |
|Claude.md |Project root |Cross-plugin agents for this project|
|contract-validator|Separate plugin |Validates compatibility |
|doc-guardian |Separate plugin |Catches drift within each project |
|Layer |Location |Purpose |
|------------------|-------------------------|---------------------------------------|
|Plugin docs |Each plugin's README.md |Declares inputs/outputs |
|Claude.md |Project root |Cross-plugin agents for this project |
|contract-validator|Separate plugin |Validates compatibility |
|doc-guardian |Separate plugin |Catches drift within each project |
### Interface Contracts
@@ -393,10 +404,10 @@ Each plugin declares what it produces and accepts:
### Cross-Plugin Agents (defined in Claude.md)
|Agent |Trigger |Sequence |
|--------------------|-----------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------|
|`dashboard_builder` |User requests visualization of database content|postgres-mcp.execute_query → pandas-mcp.pivot (if needed) → dmc-mcp.validate → dash-mcp.chart_create → dash-mcp.layout_create|
|`visualization_prep`|Query result needs reshaping |postgres-mcp.execute_query → pandas-mcp.reshape → dash-mcp.chart_create |
|Agent |Trigger |Sequence |
|--------------------|---------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|
|`dashboard_builder` |User requests visualization of database content |postgres-mcp.execute_query → pandas-mcp.pivot (if needed) → dmc-mcp.validate → dash-mcp.chart_create → dash-mcp.layout_create|
|`visualization_prep`|Query result needs reshaping |postgres-mcp.execute_query → pandas-mcp.reshape → dash-mcp.chart_create |
### Validation: contract-validator
@@ -404,8 +415,8 @@ Separate plugin for cross-plugin validation. See **Plugin: contract-validator**
**Key distinction from doc-guardian:**
- doc-guardian: “did code change break docs?” (within a project)
- contract-validator: “do plugins work together?” (across plugins)
- doc-guardian: "did code change break docs?" (within a project)
- contract-validator: "do plugins work together?" (across plugins)
-----
@@ -417,18 +428,18 @@ Validates cross-plugin compatibility and Claude.md agent definitions. Ensures pl
**Problem solved:** Plugins declare interfaces in README. Claude.md references tools across plugins. Without validation:
- Agents reference tools that don’t exist
- viz-platform expects input format data-platform doesn’t produce
- Agents reference tools that don't exist
- viz-platform expects input format data-platform doesn't produce
- Plugin updates break workflows silently
-----
### What It Reads
|Source |Purpose |
|------------------|----------------------------------------------------|
|Plugin README.md |Extract declared inputs/outputs |
|Claude.md |Extract agent definitions and tool references |
|Source |Purpose |
|------------------|-------------------------------------------------|
|Plugin README.md |Extract declared inputs/outputs |
|Claude.md |Extract agent definitions and tool references |
|MCP server schemas|Verify tools actually exist with expected signatures|
-----
@@ -472,19 +483,19 @@ Validates cross-plugin compatibility and Claude.md agent definitions. Ensures pl
### Agents (contract-validator)
|Agent |Trigger |Sequence |
|-----------------|-------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|
|`full_validation`|User runs `/validate-contracts`|parse all plugin interfaces → parse Claude.md → validate_compatibility for each pair → validate_agent_refs for each agent → generate_compatibility_report|
|`agent_check` |User runs `/check-agent {name}`|parse_claude_md_agents → find agent → validate_agent_refs → validate_data_flow → report issues |
|Agent |Trigger |Sequence |
|-----------------|---------------------------------|---------------------------------------------------------------------------------------------------------------------------------------|
|`full_validation`|User runs `/validate-contracts` |parse all plugin interfaces → parse Claude.md → validate_compatibility for each pair → validate_agent_refs for each agent → generate_compatibility_report|
|`agent_check` |User runs `/check-agent {name}` |parse_claude_md_agents → find agent → validate_agent_refs → validate_data_flow → report issues |
-----
### Commands
|Command |Maps To |Description |
|---------------------|----------------------------------------|--------------------------------------|
|`/validate-contracts`|`full_validation` agent |Full project validation |
|`/check-agent {name}`|`agent_check` agent |Validate single agent definition |
|Command |Maps To |Description |
|---------------------|---------------------------------------|-----------------------------------|
|`/validate-contracts`|`full_validation` agent |Full project validation |
|`/check-agent {name}`|`agent_check` agent |Validate single agent definition |
|`/list-interfaces` |`parse_plugin_interface` for all plugins|Show what each plugin produces/accepts|
-----
@@ -520,12 +531,12 @@ Validates cross-plugin compatibility and Claude.md agent definitions. Ensures pl
**Issue Types:**
|Type |Severity|Example |
|-------------------|--------|------------------------------------------------------------------------|
|Missing tool |Error |Agent references `pandas-mcp.transform` but tool is `pandas-mcp.reshape`|
|Interface mismatch |Error |viz-platform expects `chart_data` but data-platform produces `data_ref` |
|Optional dependency|Warning |Agent uses dbt-mcp which may not be loaded |
|Undeclared output |Warning |Plugin produces output not listed in README |
|Type |Severity|Example |
|-------------------|--------|--------------------------------------------------------------------------------|
|Missing tool |Error |Agent references `pandas-mcp.transform` but tool is `pandas-mcp.reshape` |
|Interface mismatch |Error |viz-platform expects `chart_data` but data-platform produces `data_ref` |
|Optional dependency|Warning |Agent uses dbt-mcp which may not be loaded |
|Undeclared output |Warning |Plugin produces output not listed in README |
-----
@@ -533,10 +544,10 @@ Validates cross-plugin compatibility and Claude.md agent definitions. Ensures pl
**Separation of concerns:**
|Plugin |Scope |Trigger |
|------------------|----------------------------------|------------------------|
|doc-guardian |Code ↔ docs drift within a project|PostToolUse (Write/Edit)|
|contract-validator|Plugin ↔ plugin compatibility |On-demand or CI hook |
|Plugin |Scope |Trigger |
|------------------|----------------------------------|----------------------|
|doc-guardian |Code → docs drift within a project|PostToolUse (Write/Edit)|
|contract-validator|Plugin → plugin compatibility |On-demand or CI hook |
contract-validator does NOT watch for file changes. It runs on-demand or as CI step.
@@ -565,14 +576,14 @@ This avoids the complexity of draw.io XML generation while maintaining documenta
## Implementation Order
|Phase|Plugin |Server |Rationale |
|-----|------------------|------------|-----------------------------------------------|
|1 |data-platform |pandas-mcp |Entry point, no dependencies |
|2 |data-platform |postgres-mcp|Load from Phase 1, query capabilities |
|3 |data-platform |dbt-mcp |Transform layer, requires postgres-mcp |
|4 |viz-platform |dmc-mcp |Constraint layer, no dependencies |
|5 |viz-platform |dash-mcp |Visualization, validates against dmc-mcp |
|6 |contract-validator|— |Validates all above, requires stable interfaces|
|Phase|Plugin |Server |Rationale |
|-----|------------------|------------|------------------------------------------------|
|1 |data-platform |pandas-mcp |Entry point, no dependencies |
|2 |data-platform |postgres-mcp|Load from Phase 1, query capabilities |
|3 |data-platform |dbt-mcp |Transform layer, requires postgres-mcp |
|4 |viz-platform |dmc-mcp |Constraint layer, no dependencies |
|5 |viz-platform |dash-mcp |Visualization, validates against dmc-mcp |
|6 |contract-validator|— |Validates all above, requires stable interfaces |
**Notes:**
@@ -630,11 +641,11 @@ Auto-detect `dbt_project.yml` in common locations, or require explicit path?
### Core Plugins
|Plugin |Servers/Scope |Key Characteristic |
|------------------|---------------------------------------|------------------------------------------------------|
|data-platform |pandas-mcp, postgres-mcp, dbt-mcp |Optional server loading per project |
|viz-platform |dmc-mcp, dash-mcp |dmc-mcp validates before dash-mcp renders |
|contract-validator|Interface parsing, compatibility checks|Validates cross-plugin contracts and agent definitions|
|Plugin |Servers/Scope |Key Characteristic |
|------------------|-------------------------------------------|---------------------------------------------------|
|data-platform |pandas-mcp, postgres-mcp, dbt-mcp |Optional server loading per project |
|viz-platform |dmc-mcp, dash-mcp |dmc-mcp validates before dash-mcp renders |
|contract-validator|Interface parsing, compatibility checks |Validates cross-plugin contracts and agent definitions|
### Supporting Plugins (Existing)
@@ -646,10 +657,10 @@ Auto-detect `dbt_project.yml` in common locations, or require explicit path?
### Interaction Model
```
Plugin READMEs → declare inputs/outputs
Claude.md → define cross-plugin agents
contract-validator → validate compatibility
doc-guardian → catch drift within projects
Plugin READMEs → declare inputs/outputs
Claude.md → define cross-plugin agents
contract-validator → validate compatibility
doc-guardian → catch drift within projects
```
**Flow:** Plugins declare interfaces. Claude.md defines workflows. contract-validator enforces compatibility. doc-guardian handles internal drift.