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