feat(scripts): integrate skill aliases into setup process

- Add setup_skill_aliases() function to setup.sh
- Automatically install personal skill aliases during setup
- Update section numbering and header documentation

This ensures skill aliases are installed on all machines during
initial setup, eliminating manual step for command routing.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

.claude-plugin/marketplace-full.json

@@ -0,0 +1,205 @@
+{
+  "name": "leo-claude-mktplace",
+  "owner": {
+    "name": "Leo Miranda",
+    "email": "leobmiranda@gmail.com"
+  },
+  "metadata": {
+    "description": "Project management plugins with Gitea and NetBox integrations",
+    "version": "7.1.0"
+  },
+  "plugins": [
+    {
+      "name": "projman",
+      "version": "7.1.0",
+      "description": "Sprint planning and project management with Gitea integration",
+      "source": "./plugins/projman",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/projman/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "hooks": ["./hooks/hooks.json"],
+      "category": "development",
+      "tags": ["sprint", "agile", "gitea", "project-management"],
+      "license": "MIT"
+    },
+    {
+      "name": "doc-guardian",
+      "version": "7.1.0",
+      "description": "Automatic documentation drift detection and synchronization",
+      "source": "./plugins/doc-guardian",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/doc-guardian/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "hooks": ["./hooks/hooks.json"],
+      "category": "productivity",
+      "tags": ["documentation", "drift-detection", "sync"],
+      "license": "MIT"
+    },
+    {
+      "name": "code-sentinel",
+      "version": "7.1.0",
+      "description": "Security scanning and code refactoring tools",
+      "source": "./plugins/code-sentinel",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/code-sentinel/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "hooks": ["./hooks/hooks.json"],
+      "category": "security",
+      "tags": ["security-scan", "refactoring", "vulnerabilities"],
+      "license": "MIT"
+    },
+    {
+      "name": "project-hygiene",
+      "version": "7.1.0",
+      "description": "Post-task cleanup hook that removes temp files and manages orphaned files",
+      "source": "./plugins/project-hygiene",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/project-hygiene/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "hooks": ["./hooks/hooks.json"],
+      "category": "productivity",
+      "tags": ["cleanup", "automation", "hygiene"],
+      "license": "MIT"
+    },
+    {
+      "name": "cmdb-assistant",
+      "version": "7.1.0",
+      "description": "NetBox CMDB integration with data quality validation and machine registration",
+      "source": "./plugins/cmdb-assistant",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/cmdb-assistant/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "hooks": ["./hooks/hooks.json"],
+      "category": "infrastructure",
+      "tags": ["cmdb", "netbox", "dcim", "ipam", "data-quality", "validation"],
+      "license": "MIT"
+    },
+    {
+      "name": "claude-config-maintainer",
+      "version": "7.1.0",
+      "description": "CLAUDE.md and settings.local.json optimization for Claude Code projects",
+      "source": "./plugins/claude-config-maintainer",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/claude-config-maintainer/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "hooks": ["./hooks/hooks.json"],
+      "category": "development",
+      "tags": ["claude-md", "configuration", "optimization"],
+      "license": "MIT"
+    },
+    {
+      "name": "clarity-assist",
+      "version": "7.1.0",
+      "description": "Prompt optimization and requirement clarification with ND-friendly accommodations",
+      "source": "./plugins/clarity-assist",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/clarity-assist/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "hooks": ["./hooks/hooks.json"],
+      "category": "productivity",
+      "tags": ["prompts", "requirements", "clarification", "nd-friendly"],
+      "license": "MIT"
+    },
+    {
+      "name": "git-flow",
+      "version": "7.1.0",
+      "description": "Git workflow automation with intelligent commit messages and branch management",
+      "source": "./plugins/git-flow",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/git-flow/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "hooks": ["./hooks/hooks.json"],
+      "category": "development",
+      "tags": ["git", "workflow", "commits", "branching"],
+      "license": "MIT"
+    },
+    {
+      "name": "pr-review",
+      "version": "7.1.0",
+      "description": "Multi-agent pull request review with confidence scoring and actionable feedback",
+      "source": "./plugins/pr-review",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/pr-review/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "hooks": ["./hooks/hooks.json"],
+      "category": "development",
+      "tags": ["code-review", "pull-requests", "security", "quality"],
+      "license": "MIT"
+    },
+    {
+      "name": "data-platform",
+      "version": "7.1.0",
+      "description": "Data engineering tools with pandas, PostgreSQL/PostGIS, and dbt integration",
+      "source": "./plugins/data-platform",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/data-platform/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "hooks": ["./hooks/hooks.json"],
+      "category": "data",
+      "tags": ["pandas", "postgresql", "postgis", "dbt", "data-engineering", "etl"],
+      "license": "MIT"
+    },
+    {
+      "name": "viz-platform",
+      "version": "7.1.0",
+      "description": "Visualization tools with Dash Mantine Components validation, Plotly charts, and theming",
+      "source": "./plugins/viz-platform",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/viz-platform/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "hooks": ["./hooks/hooks.json"],
+      "category": "visualization",
+      "tags": ["dash", "plotly", "mantine", "charts", "dashboards", "theming", "dmc"],
+      "license": "MIT"
+    },
+    {
+      "name": "contract-validator",
+      "version": "7.1.0",
+      "description": "Cross-plugin compatibility validation and Claude.md agent verification",
+      "source": "./plugins/contract-validator",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/contract-validator/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "hooks": ["./hooks/hooks.json"],
+      "category": "development",
+      "tags": ["validation", "contracts", "compatibility", "agents", "interfaces", "cross-plugin"],
+      "license": "MIT"
+    }
+  ]
+}

.claude-plugin/marketplace-lean.json

@@ -0,0 +1,109 @@
+{
+  "name": "leo-claude-mktplace",
+  "owner": {
+    "name": "Leo Miranda",
+    "email": "leobmiranda@gmail.com"
+  },
+  "metadata": {
+    "description": "Project management plugins with Gitea and NetBox integrations",
+    "version": "7.1.0"
+  },
+  "plugins": [
+    {
+      "name": "projman",
+      "version": "7.1.0",
+      "description": "Sprint planning and project management with Gitea integration",
+      "source": "./plugins/projman",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/projman/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "hooks": ["./hooks/hooks.json"],
+      "category": "development",
+      "tags": ["sprint", "agile", "gitea", "project-management"],
+      "license": "MIT"
+    },
+    {
+      "name": "git-flow",
+      "version": "7.1.0",
+      "description": "Git workflow automation with intelligent commit messages and branch management",
+      "source": "./plugins/git-flow",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/git-flow/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "hooks": ["./hooks/hooks.json"],
+      "category": "development",
+      "tags": ["git", "workflow", "commits", "branching"],
+      "license": "MIT"
+    },
+    {
+      "name": "pr-review",
+      "version": "7.1.0",
+      "description": "Multi-agent pull request review with confidence scoring and actionable feedback",
+      "source": "./plugins/pr-review",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/pr-review/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "hooks": ["./hooks/hooks.json"],
+      "category": "development",
+      "tags": ["code-review", "pull-requests", "security", "quality"],
+      "license": "MIT"
+    },
+    {
+      "name": "clarity-assist",
+      "version": "7.1.0",
+      "description": "Prompt optimization and requirement clarification with ND-friendly accommodations",
+      "source": "./plugins/clarity-assist",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/clarity-assist/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "hooks": ["./hooks/hooks.json"],
+      "category": "productivity",
+      "tags": ["prompts", "requirements", "clarification", "nd-friendly"],
+      "license": "MIT"
+    },
+    {
+      "name": "code-sentinel",
+      "version": "7.1.0",
+      "description": "Security scanning and code refactoring tools",
+      "source": "./plugins/code-sentinel",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/code-sentinel/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "hooks": ["./hooks/hooks.json"],
+      "category": "security",
+      "tags": ["security-scan", "refactoring", "vulnerabilities"],
+      "license": "MIT"
+    },
+    {
+      "name": "doc-guardian",
+      "version": "7.1.0",
+      "description": "Automatic documentation drift detection and synchronization",
+      "source": "./plugins/doc-guardian",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/doc-guardian/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "hooks": ["./hooks/hooks.json"],
+      "category": "productivity",
+      "tags": ["documentation", "drift-detection", "sync"],
+      "license": "MIT"
+    }
+  ]
+}

.claude-plugin/marketplace.json

@@ -1,53 +1,443 @@
 {
-  "name": "claude-code-marketplace",
-  "version": "2.0.0",
-  "description": "Project management plugins with Gitea and NetBox integrations",
+  "name": "leo-claude-mktplace",
   "owner": {
     "name": "Leo Miranda",
     "email": "leobmiranda@gmail.com"
   },
+  "metadata": {
+    "description": "Project management plugins with Gitea and NetBox integrations",
+    "version": "9.1.2"
+  },
   "plugins": [
     {
       "name": "projman",
-      "version": "2.0.0",
+      "version": "9.0.1",
       "description": "Sprint planning and project management with Gitea integration",
       "source": "./plugins/projman",
-      "mcpServers": ["gitea"],
-      "integrationFile": "claude-md-integration.md"
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/projman/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "category": "development",
+      "tags": [
+        "sprint",
+        "agile",
+        "gitea",
+        "project-management"
+      ],
+      "license": "MIT"
+    },
+    {
+      "name": "doc-guardian",
+      "version": "9.0.1",
+      "description": "Automatic documentation drift detection and synchronization",
+      "source": "./plugins/doc-guardian",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/doc-guardian/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "category": "productivity",
+      "tags": [
+        "documentation",
+        "drift-detection",
+        "sync"
+      ],
+      "license": "MIT"
+    },
+    {
+      "name": "code-sentinel",
+      "version": "9.0.1",
+      "description": "Security scanning and code refactoring tools",
+      "source": "./plugins/code-sentinel",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/code-sentinel/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "hooks": [
+        "./hooks/hooks.json"
+      ],
+      "category": "security",
+      "tags": [
+        "security-scan",
+        "refactoring",
+        "vulnerabilities"
+      ],
+      "license": "MIT"
     },
     {
       "name": "project-hygiene",
-      "version": "0.1.0",
-      "description": "Post-task cleanup hook that removes temp files and manages orphaned files",
+      "version": "9.0.1",
+      "description": "Manual project hygiene checks — temp files, misplaced files, empty dirs, debug artifacts",
       "source": "./plugins/project-hygiene",
-      "mcpServers": [],
-      "integrationFile": "claude-md-integration.md",
-      "hooks": ["PostToolUse"]
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/project-hygiene/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "category": "productivity",
+      "tags": [
+        "cleanup",
+        "hygiene",
+        "maintenance",
+        "manual-check"
+      ],
+      "license": "MIT"
     },
     {
       "name": "cmdb-assistant",
-      "version": "1.0.0",
-      "description": "NetBox CMDB integration for infrastructure management",
+      "version": "9.0.1",
+      "description": "NetBox CMDB integration with data quality validation and machine registration",
       "source": "./plugins/cmdb-assistant",
-      "mcpServers": ["netbox"],
-      "integrationFile": "claude-md-integration.md"
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/cmdb-assistant/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "hooks": [
+        "./hooks/hooks.json"
+      ],
+      "category": "infrastructure",
+      "tags": [
+        "cmdb",
+        "netbox",
+        "dcim",
+        "ipam",
+        "data-quality",
+        "validation"
+      ],
+      "license": "MIT"
     },
     {
       "name": "claude-config-maintainer",
-      "version": "1.0.0",
-      "description": "CLAUDE.md optimization and maintenance for Claude Code projects",
+      "version": "9.0.1",
+      "description": "CLAUDE.md and settings.local.json optimization for Claude Code projects",
       "source": "./plugins/claude-config-maintainer",
-      "mcpServers": [],
-      "integrationFile": "claude-md-integration.md"
-    }
-  ],
-  "pluginDetection": {
-    "mcpServerMapping": {
-      "gitea": "projman",
-      "netbox": "cmdb-assistant"
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/claude-config-maintainer/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "category": "development",
+      "tags": [
+        "claude-md",
+        "configuration",
+        "optimization"
+      ],
+      "license": "MIT"
     },
-    "hookMapping": {
-      "PostToolUse:Write|Edit": "project-hygiene"
+    {
+      "name": "clarity-assist",
+      "version": "9.0.1",
+      "description": "Prompt optimization and requirement clarification with ND-friendly accommodations",
+      "source": "./plugins/clarity-assist",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/clarity-assist/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "hooks": [
+        "./hooks/hooks.json"
+      ],
+      "category": "productivity",
+      "tags": [
+        "prompts",
+        "requirements",
+        "clarification",
+        "nd-friendly"
+      ],
+      "license": "MIT"
+    },
+    {
+      "name": "git-flow",
+      "version": "9.0.1",
+      "description": "Git workflow automation with intelligent commit messages and branch management",
+      "source": "./plugins/git-flow",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/git-flow/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "hooks": [
+        "./hooks/hooks.json"
+      ],
+      "category": "development",
+      "tags": [
+        "git",
+        "workflow",
+        "commits",
+        "branching"
+      ],
+      "license": "MIT"
+    },
+    {
+      "name": "pr-review",
+      "version": "9.0.1",
+      "description": "Multi-agent pull request review with confidence scoring and actionable feedback",
+      "source": "./plugins/pr-review",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/pr-review/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "category": "development",
+      "tags": [
+        "code-review",
+        "pull-requests",
+        "security",
+        "quality"
+      ],
+      "license": "MIT"
+    },
+    {
+      "name": "data-platform",
+      "version": "9.0.1",
+      "description": "Data engineering tools with pandas, PostgreSQL/PostGIS, and dbt integration",
+      "source": "./plugins/data-platform",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/data-platform/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "category": "data",
+      "tags": [
+        "pandas",
+        "postgresql",
+        "postgis",
+        "dbt",
+        "data-engineering",
+        "etl"
+      ],
+      "license": "MIT"
+    },
+    {
+      "name": "viz-platform",
+      "version": "9.0.1",
+      "description": "Visualization tools with Dash Mantine Components validation, Plotly charts, and theming",
+      "source": "./plugins/viz-platform",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/viz-platform/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "category": "visualization",
+      "tags": [
+        "dash",
+        "plotly",
+        "mantine",
+        "charts",
+        "dashboards",
+        "theming",
+        "dmc"
+      ],
+      "license": "MIT"
+    },
+    {
+      "name": "contract-validator",
+      "version": "9.0.1",
+      "description": "Cross-plugin compatibility validation and Claude.md agent verification",
+      "source": "./plugins/contract-validator",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/contract-validator/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "category": "development",
+      "tags": [
+        "validation",
+        "contracts",
+        "compatibility",
+        "agents",
+        "interfaces",
+        "cross-plugin"
+      ],
+      "license": "MIT"
+    },
+    {
+      "name": "saas-api-platform",
+      "version": "0.1.0",
+      "description": "REST and GraphQL API scaffolding for FastAPI and Express projects",
+      "source": "./plugins/saas-api-platform",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/saas-api-platform/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "category": "development",
+      "tags": [
+        "api",
+        "rest",
+        "graphql",
+        "fastapi",
+        "express",
+        "openapi"
+      ],
+      "license": "MIT"
+    },
+    {
+      "name": "saas-db-migrate",
+      "version": "0.1.0",
+      "description": "Database migration management for Alembic, Prisma, and raw SQL",
+      "source": "./plugins/saas-db-migrate",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/saas-db-migrate/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "category": "development",
+      "tags": [
+        "database",
+        "migrations",
+        "alembic",
+        "prisma",
+        "sql",
+        "schema"
+      ],
+      "license": "MIT"
+    },
+    {
+      "name": "saas-react-platform",
+      "version": "0.1.0",
+      "description": "React frontend development toolkit for Next.js and Vite projects",
+      "source": "./plugins/saas-react-platform",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/saas-react-platform/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "category": "development",
+      "tags": [
+        "react",
+        "nextjs",
+        "vite",
+        "typescript",
+        "frontend",
+        "components"
+      ],
+      "license": "MIT"
+    },
+    {
+      "name": "saas-test-pilot",
+      "version": "0.1.0",
+      "description": "Test automation toolkit for pytest, Jest, Vitest, and Playwright",
+      "source": "./plugins/saas-test-pilot",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/saas-test-pilot/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "category": "development",
+      "tags": [
+        "testing",
+        "pytest",
+        "jest",
+        "vitest",
+        "playwright",
+        "coverage"
+      ],
+      "license": "MIT"
+    },
+    {
+      "name": "data-seed",
+      "version": "0.1.0",
+      "description": "Test data generation and database seeding with relationship-aware profiles",
+      "source": "./plugins/data-seed",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/data-seed/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "category": "data",
+      "tags": [
+        "seed-data",
+        "test-data",
+        "faker",
+        "fixtures",
+        "database"
+      ],
+      "license": "MIT"
+    },
+    {
+      "name": "ops-release-manager",
+      "version": "0.1.0",
+      "description": "Release management with semantic versioning, changelogs, and tag automation",
+      "source": "./plugins/ops-release-manager",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/ops-release-manager/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "category": "development",
+      "tags": [
+        "release",
+        "semver",
+        "changelog",
+        "versioning",
+        "tags"
+      ],
+      "license": "MIT"
+    },
+    {
+      "name": "ops-deploy-pipeline",
+      "version": "0.1.0",
+      "description": "CI/CD deployment pipeline management for Docker Compose and systemd services",
+      "source": "./plugins/ops-deploy-pipeline",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/ops-deploy-pipeline/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "category": "infrastructure",
+      "tags": [
+        "deploy",
+        "docker-compose",
+        "systemd",
+        "caddy",
+        "cicd"
+      ],
+      "license": "MIT"
+    },
+    {
+      "name": "debug-mcp",
+      "version": "0.1.0",
+      "description": "MCP server debugging, inspection, and development toolkit",
+      "source": "./plugins/debug-mcp",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/debug-mcp/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "category": "development",
+      "tags": [
+        "mcp",
+        "debugging",
+        "diagnostics",
+        "server",
+        "development"
+      ],
+      "license": "MIT"
     }
-  }
+  ]
 }

.claude/settings.json

@@ -0,0 +1,3 @@
+{
+  "model": "opusplan"
+}

.env

@@ -0,0 +1 @@
+GITEA_REPO=personal-projects/leo-claude-mktplace

.gitignore

@@ -31,6 +31,8 @@ venv/
 ENV/
 env/
 .venv/
+.venv
+**/.venv
 
 # PyCharm
 .idea/
@@ -82,6 +84,13 @@ Thumbs.db
 # Claude Code
 .claude/settings.local.json
 .claude/history/
+.claude/backups/
+
+# Doc Guardian transient files
+.doc-guardian-queue
+
+# Development convenience links
+.marketplaces-link
 
 # Logs
 logs/
@@ -123,4 +132,5 @@ site/
 *credentials*
 *secret*
 *token*
+!**/token-budget-report.md
 !.gitkeep

.mcp-full.json

@@ -0,0 +1,24 @@
+{
+  "mcpServers": {
+    "gitea": {
+      "command": "./mcp-servers/gitea/run.sh",
+      "args": []
+    },
+    "netbox": {
+      "command": "./mcp-servers/netbox/run.sh",
+      "args": []
+    },
+    "viz-platform": {
+      "command": "./mcp-servers/viz-platform/run.sh",
+      "args": []
+    },
+    "data-platform": {
+      "command": "./mcp-servers/data-platform/run.sh",
+      "args": []
+    },
+    "contract-validator": {
+      "command": "./mcp-servers/contract-validator/run.sh",
+      "args": []
+    }
+  }
+}

.mcp-lean.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "gitea": {
+      "command": "./mcp-servers/gitea/run.sh",
+      "args": []
+    }
+  }
+}

.mcp.json

@@ -0,0 +1,24 @@
+{
+  "mcpServers": {
+    "gitea": {
+      "command": "./mcp-servers/gitea/run.sh",
+      "args": []
+    },
+    "netbox": {
+      "command": "./mcp-servers/netbox/run.sh",
+      "args": []
+    },
+    "viz-platform": {
+      "command": "./mcp-servers/viz-platform/run.sh",
+      "args": []
+    },
+    "data-platform": {
+      "command": "./mcp-servers/data-platform/run.sh",
+      "args": []
+    },
+    "contract-validator": {
+      "command": "./mcp-servers/contract-validator/run.sh",
+      "args": []
+    }
+  }
+}

CLAUDE.md

@@ -1,478 +1,566 @@
 # CLAUDE.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+## ⛔ MANDATORY BEHAVIOR RULES - READ FIRST
+
+**These rules are NON-NEGOTIABLE. Violating them wastes the user's time and money.**
+
+### 1. WHEN USER ASKS YOU TO CHECK SOMETHING - CHECK EVERYTHING
+- Search ALL locations, not just where you think it is
+- Check cache directories: `~/.claude/plugins/cache/`
+- Check installed: `~/.claude/plugins/marketplaces/`
+- Check source directories
+- **NEVER say "no" or "that's not the issue" without exhaustive verification**
+
+### 2. WHEN USER SAYS SOMETHING IS WRONG - BELIEVE THEM
+- The user knows their system better than you
+- Investigate thoroughly before disagreeing
+- **Your confidence is often wrong. User's instincts are often right.**
+
+### 3. NEVER SAY "DONE" WITHOUT VERIFICATION
+- Run the actual command/script to verify
+- Show the output to the user
+- **"Done" means VERIFIED WORKING, not "I made changes"**
+
+### 4. SHOW EXACTLY WHAT USER ASKS FOR
+- If user asks for messages, show the MESSAGES
+- If user asks for code, show the CODE
+- **Do not interpret or summarize unless asked**
+
+**FAILURE TO FOLLOW THESE RULES = WASTED USER TIME = UNACCEPTABLE**
+
+---
+
+
+
+This file provides guidance to Claude Code when working with code in this repository.
+
+## ⛔ RULES - READ FIRST
+
+### Behavioral Rules
+
+| Rule | Summary |
+|------|---------|
+| **Check everything** | Search cache (`~/.claude/plugins/cache/`), installed (`~/.claude/plugins/marketplaces/`), and source (`~/claude-plugins-work/`) |
+| **Believe the user** | User knows their system. Investigate before disagreeing. |
+| **Verify before "done"** | Run commands, show output, check all locations. "Done" = verified working. |
+| **Show what's asked** | Don't interpret or summarize unless asked. |
+
+### After Plugin Updates
+
+Run `./scripts/verify-hooks.sh`. If changes affect MCP servers or hooks, inform user to restart session.
+**DO NOT clear cache mid-session** - breaks loaded MCP tools.
+
+### NEVER USE CLI TOOLS FOR EXTERNAL SERVICES
+- **FORBIDDEN:** `gh`, `tea`, `curl` to APIs, any CLI that talks to Gitea/GitHub/external services
+- **REQUIRED:** Use MCP tools exclusively (`mcp__plugin_projman_gitea__*`, `mcp__plugin_pr-review_gitea__*`)
+- **NO EXCEPTIONS.** Don't try CLI first. Don't fall back to CLI. MCP ONLY.
+
+### NEVER PUSH DIRECTLY TO PROTECTED BRANCHES
+- **FORBIDDEN:** `git push origin development`, `git push origin main`, `git push origin master`
+- **REQUIRED:** Create feature branch → push feature branch → create PR via MCP
+- If you accidentally commit to a protected branch locally: `git checkout -b fix/branch-name` then reset the protected branch
+
+### Repository Rules
+
+| Rule | Details |
+|------|---------|
+| **File creation** | Only in allowed paths. Use `.scratch/` for temp work. Verify against `docs/CANONICAL-PATHS.md` |
+| **plugin.json location** | Must be in `.claude-plugin/` directory |
+| **Hooks** | Use `hooks/hooks.json` (auto-discovered). Never inline in plugin.json |
+| **MCP servers** | Defined in root `.mcp.json`. Use MCP tools, never CLI (`tea`, `gh`) |
+| **Allowed root files** | `CLAUDE.md`, `README.md`, `LICENSE`, `CHANGELOG.md`, `.gitignore`, `.env.example` |
+
+**Valid hook events:** `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `SessionStart`, `SessionEnd`, `Notification`, `Stop`, `SubagentStop`, `PreCompact`
+
+### ⛔ MANDATORY: Before Any Code Change
+
+**Claude MUST show this checklist BEFORE editing any file:**
+
+#### 1. Impact Search Results
+Run and show output of:
+```bash
+grep -rn "PATTERN" --include="*.sh" --include="*.md" --include="*.json" --include="*.py" | grep -v ".git"
+```
+
+#### 2. Files That Will Be Affected
+Numbered list of every file to be modified, with the specific change for each.
+
+#### 3. Files Searched But Not Changed (and why)
+Proof that related files were checked and determined unchanged.
+
+#### 4. Documentation That References This
+List of docs that mention this feature/script/function.
+
+**User verifies this list before Claude proceeds. If Claude skips this, STOP IMMEDIATELY.**
+
+#### After Changes
+Run the same grep and show results proving no references remain unaddressed.
+
+---
+
+## ⚠️ Development Context: We Build AND Use These Plugins
+
+**This is a self-referential project.** We are:
+1. **BUILDING** a plugin marketplace (source code in `plugins/`)
+2. **USING** the installed marketplace to build it (dogfooding)
+
+### Plugins ACTIVELY USED in This Project
+
+These plugins are installed and should be used during development:
+
+| Plugin | Used For |
+|--------|----------|
+| **projman** | Sprint planning, issue management, lessons learned |
+| **git-flow** | Commits, branch management |
+| **pr-review** | Pull request reviews |
+| **doc-guardian** | Documentation drift detection |
+| **code-sentinel** | Security scanning, refactoring |
+| **clarity-assist** | Prompt clarification |
+| **claude-config-maintainer** | CLAUDE.md optimization |
+| **contract-validator** | Cross-plugin compatibility |
+
+### Plugins NOT Used Here (Development Only)
+
+These plugins exist in source but are **NOT relevant** to this project's workflow:
+
+| Plugin | Why Not Used |
+|--------|--------------|
+| **data-platform** | For data engineering projects (pandas, PostgreSQL, dbt) |
+| **viz-platform** | For dashboard projects (Dash, Plotly) |
+| **cmdb-assistant** | For infrastructure projects (NetBox) |
+| **saas-api-platform** | For REST/GraphQL API projects (FastAPI, Express) |
+| **saas-db-migrate** | For database migration projects (Alembic, Prisma) |
+| **saas-react-platform** | For React frontend projects (Next.js, Vite) |
+| **saas-test-pilot** | For test automation projects (pytest, Jest, Playwright) |
+| **data-seed** | For test data generation and seeding |
+| **ops-release-manager** | For release management workflows |
+| **ops-deploy-pipeline** | For deployment pipeline management |
+| **debug-mcp** | For MCP server debugging and development |
+
+**Do NOT suggest** `/data ingest`, `/data profile`, `/viz chart`, `/cmdb *`, `/api *`, `/db-migrate *`, `/react *`, `/test *`, `/seed *`, `/release *`, `/deploy *`, `/debug-mcp *` commands - they don't apply here.
+
+### Key Distinction
+
+| Context | Path | What To Do |
+|---------|------|------------|
+| **Editing plugin source** | `~/claude-plugins-work/plugins/` | Modify code, add features |
+| **Using installed plugins** | `~/.claude/plugins/marketplaces/` | Run commands like `/sprint plan` |
+
+When user says "run /sprint plan", use the INSTALLED plugin.
+When user says "fix the sprint plan command", edit the SOURCE code.
+
+---
 
 ## Project Overview
 
-This repository contains Claude Code plugins for project management:
+**Repository:** leo-claude-mktplace
+**Version:** 9.1.2
+**Status:** Production Ready
 
-1. **`projman`** - Single-repository project management plugin with Gitea integration
-2. **`projman-pmo`** - Multi-project PMO coordination plugin
-3. **`claude-config-maintainer`** - CLAUDE.md optimization and maintenance plugin
-4. **`cmdb-assistant`** - NetBox CMDB integration for infrastructure management
+A plugin marketplace for Claude Code containing:
 
-These plugins transform a proven 15-sprint workflow into reusable, distributable tools for managing software development with Claude Code, Gitea, and agile methodologies.
+| Plugin | Description | Version |
+|--------|-------------|---------|
+| `projman` | Sprint planning and project management with Gitea integration | 9.0.1 |
+| `git-flow` | Git workflow automation with smart commits and branch management | 9.0.1 |
+| `pr-review` | Multi-agent PR review with confidence scoring | 9.0.1 |
+| `clarity-assist` | Prompt optimization with ND-friendly accommodations | 9.0.1 |
+| `doc-guardian` | Automatic documentation drift detection and synchronization | 9.0.1 |
+| `code-sentinel` | Security scanning and code refactoring tools | 9.0.1 |
+| `claude-config-maintainer` | CLAUDE.md optimization and maintenance | 9.0.1 |
+| `cmdb-assistant` | NetBox CMDB integration for infrastructure management | 9.0.1 |
+| `data-platform` | pandas, PostgreSQL, and dbt integration for data engineering | 9.0.1 |
+| `viz-platform` | DMC validation, Plotly charts, and theming for dashboards | 9.0.1 |
+| `contract-validator` | Cross-plugin compatibility validation and agent verification | 9.0.1 |
+| `project-hygiene` | Manual project hygiene checks | 9.0.1 |
+| `saas-api-platform` | REST/GraphQL API scaffolding for FastAPI and Express | 0.1.0 |
+| `saas-db-migrate` | Database migration management for Alembic, Prisma, raw SQL | 0.1.0 |
+| `saas-react-platform` | React frontend toolkit for Next.js and Vite | 0.1.0 |
+| `saas-test-pilot` | Test automation for pytest, Jest, Vitest, Playwright | 0.1.0 |
+| `data-seed` | Test data generation and database seeding | 0.1.0 |
+| `ops-release-manager` | Release management with SemVer and changelog automation | 0.1.0 |
+| `ops-deploy-pipeline` | Deployment pipeline for Docker Compose and systemd | 0.1.0 |
+| `debug-mcp` | MCP server debugging and development toolkit | 0.1.0 |
 
-**Status:** projman v1.0.0 complete with full Gitea integration
+## Quick Start
 
-## File Creation Governance
+```bash
+# Validate marketplace compliance
+./scripts/validate-marketplace.sh
 
-### Allowed Root Files
+# After updates
+./scripts/post-update.sh   # Rebuild venvs
+```
 
-Only these files may exist at the repository root:
+### Plugin Commands - USE THESE in This Project
 
-- `CLAUDE.md` - This file
-- `README.md` - Repository overview
-- `LICENSE` - License file
-- `CHANGELOG.md` - Version history
-- `.gitignore` - Git ignore rules
-- `.env.example` - Environment template (if needed)
+| Category | Commands |
+|----------|----------|
+| **Setup** | `/projman setup` (modes: `--full`, `--quick`, `--sync`) |
+| **Sprint** | `/sprint plan`, `/sprint start`, `/sprint status` (with `--diagram`), `/sprint close` |
+| **Quality** | `/sprint review`, `/sprint test` (modes: `run`, `gen`) |
+| **Project** | `/project initiation`, `/project plan`, `/project status`, `/project close` |
+| **ADR** | `/adr create`, `/adr list`, `/adr update`, `/adr supersede` |
+| **RFC** | `/rfc create`, `/rfc list`, `/rfc review`, `/rfc approve`, `/rfc reject` |
+| **PR Review** | `/pr review`, `/pr summary`, `/pr findings`, `/pr diff` |
+| **Docs** | `/doc audit`, `/doc sync`, `/doc changelog-gen`, `/doc coverage`, `/doc stale-docs` |
+| **Security** | `/sentinel scan`, `/sentinel refactor`, `/sentinel refactor-dry` |
+| **Config** | `/claude-config analyze`, `/claude-config optimize`, `/claude-config diff`, `/claude-config lint` |
+| **Validation** | `/cv validate`, `/cv check-agent`, `/cv list-interfaces`, `/cv dependency-graph`, `/cv status` |
+| **Maintenance** | `/hygiene check` |
 
-### Allowed Root Directories
+### Plugin Commands - NOT RELEVANT to This Project
 
-Only these directories may exist at the repository root:
+These commands are being developed but don't apply to this project's workflow:
 
-| Directory | Purpose |
-|-----------|---------|
-| `.claude/` | Claude Code local settings |
-| `.claude-plugin/` | Marketplace manifest |
-| `.claude-plugins/` | Local marketplace definitions |
-| `.scratch/` | Transient work (auto-cleaned) |
-| `docs/` | Documentation |
-| `hooks/` | Shared hooks (if any) |
-| `plugins/` | All plugins (projman, projman-pmo, project-hygiene, cmdb-assistant, claude-config-maintainer) |
-| `scripts/` | Setup and maintenance scripts |
+| Category | Commands | For Projects Using |
+|----------|----------|-------------------|
+| **Data** | `/data ingest`, `/data profile`, `/data schema`, `/data lineage`, `/data dbt-test` | pandas, PostgreSQL, dbt |
+| **Visualization** | `/viz component`, `/viz chart`, `/viz dashboard`, `/viz theme` | Dash, Plotly dashboards |
+| **CMDB** | `/cmdb search`, `/cmdb device`, `/cmdb sync` | NetBox infrastructure |
+| **API** | `/api scaffold`, `/api validate`, `/api docs`, `/api middleware` | FastAPI, Express |
+| **DB Migrate** | `/db-migrate generate`, `/db-migrate validate`, `/db-migrate plan` | Alembic, Prisma |
+| **React** | `/react component`, `/react route`, `/react state`, `/react hook` | Next.js, Vite |
+| **Testing** | `/test generate`, `/test coverage`, `/test fixtures`, `/test e2e` | pytest, Jest, Playwright |
+| **Seeding** | `/seed generate`, `/seed profile`, `/seed apply` | Faker, test data |
+| **Release** | `/release prepare`, `/release validate`, `/release tag` | SemVer releases |
+| **Deploy** | `/deploy generate`, `/deploy validate`, `/deploy check` | Docker Compose, systemd |
+| **Debug MCP** | `/debug-mcp status`, `/debug-mcp test`, `/debug-mcp logs` | MCP server development |
 
-### File Creation Rules
+## Repository Structure
 
-1. **No new root files** - Do not create files directly in the repository root unless listed above
-2. **No new root directories** - Do not create top-level directories without explicit approval
-3. **Transient work goes in `.scratch/`** - Any temporary files, test outputs, or exploratory work must be created in `.scratch/`
-4. **Clean up after tasks** - Delete files in `.scratch/` when the task is complete
-5. **Documentation location** - All documentation goes in `docs/` with appropriate subdirectory:
-   - `docs/references/` - Reference specifications and summaries
-   - `docs/architecture/` - Architecture diagrams (Draw.io files)
-   - `docs/workflows/` - Workflow documentation
-6. **No output files** - Do not leave generated output, logs, or test results outside designated directories
+```
+leo-claude-mktplace/
+├── .claude-plugin/                # Marketplace manifest
+│   ├── marketplace.json
+│   ├── marketplace-lean.json      # Lean profile (6 core plugins)
+│   └── marketplace-full.json      # Full profile (all plugins)
+├── .mcp.json                     # MCP server configuration (all servers)
+├── mcp-servers/                  # SHARED MCP servers
+│   ├── gitea/                    # Gitea (issues, PRs, wiki)
+│   ├── netbox/                   # NetBox (DCIM, IPAM)
+│   ├── data-platform/            # pandas, PostgreSQL, dbt
+│   ├── viz-platform/             # DMC, Plotly, theming
+│   └── contract-validator/       # Plugin compatibility validation
+├── plugins/                      # All plugins (20 total)
+│   ├── projman/                  # [core] Sprint management
+│   │   ├── .claude-plugin/plugin.json
+│   │   ├── commands/             # 19 commands
+│   │   ├── agents/               # 4 agents
+│   │   └── skills/               # 23 reusable skill files
+│   ├── git-flow/                 # [core] Git workflow automation
+│   ├── pr-review/                # [core] PR review
+│   ├── clarity-assist/           # [core] Prompt optimization
+│   ├── doc-guardian/             # [core] Documentation drift detection
+│   ├── code-sentinel/            # [core] Security scanning
+│   ├── claude-config-maintainer/ # [core] CLAUDE.md optimization
+│   ├── contract-validator/       # [core] Cross-plugin validation
+│   ├── project-hygiene/          # [core] Manual cleanup checks
+│   ├── cmdb-assistant/           # [ops] NetBox CMDB integration
+│   ├── data-platform/            # [data] Data engineering
+│   ├── viz-platform/             # [data] Visualization
+│   ├── data-seed/                # [data] Test data generation (scaffold)
+│   ├── saas-api-platform/        # [saas] API scaffolding (scaffold)
+│   ├── saas-db-migrate/          # [saas] DB migrations (scaffold)
+│   ├── saas-react-platform/      # [saas] React toolkit (scaffold)
+│   ├── saas-test-pilot/          # [saas] Test automation (scaffold)
+│   ├── ops-release-manager/      # [ops] Release management (scaffold)
+│   ├── ops-deploy-pipeline/      # [ops] Deployment pipeline (scaffold)
+│   └── debug-mcp/                # [debug] MCP debugging (scaffold)
+├── scripts/                      # Setup and maintenance
+│   ├── setup.sh                  # Initial setup (create venvs, config)
+│   ├── post-update.sh            # Post-update (clear cache, changelog)
+│   ├── setup-venvs.sh            # MCP server venv management (cache-based)
+│   ├── validate-marketplace.sh   # Marketplace compliance validation
+│   ├── verify-hooks.sh           # Hook inventory verification
+│   ├── release.sh                # Release automation with version bumping
+│   ├── claude-launch.sh          # Profile-based launcher
+│   ├── install-plugin.sh         # Install plugin to consumer project
+│   ├── list-installed.sh         # Show installed plugins in a project
+│   └── uninstall-plugin.sh       # Remove plugin from consumer project
+├── docs/                         # Documentation
+│   ├── ARCHITECTURE.md           # System architecture & plugin reference
+│   ├── CANONICAL-PATHS.md        # Authoritative path reference
+│   ├── COMMANDS-CHEATSHEET.md    # All commands quick reference
+│   ├── CONFIGURATION.md          # Centralized setup guide
+│   ├── DEBUGGING-CHECKLIST.md    # Systematic troubleshooting guide
+│   ├── MIGRATION-v9.md           # v8.x to v9.0.0 migration guide
+│   └── UPDATING.md               # Update guide
+├── CLAUDE.md                      # Project instructions for Claude Code
+├── README.md
+├── CHANGELOG.md
+├── LICENSE
+└── .gitignore
+```
 
-### Enforcement
+## Architecture
 
-Before creating any file, verify:
+### Four-Agent Model (projman)
 
-1. Is this file type allowed in the target location?
-2. If temporary, am I using `.scratch/`?
-3. If documentation, am I using the correct `docs/` subdirectory?
-4. Will this file be cleaned up after the task?
+| Agent | Personality | Responsibilities |
+|-------|-------------|------------------|
+| **Planner** | Thoughtful, methodical | Sprint planning, architecture analysis, issue creation, lesson search |
+| **Orchestrator** | Concise, action-oriented | Sprint execution, parallel batching, Git operations, lesson capture |
+| **Executor** | Implementation-focused | Code implementation, branch management, MR creation |
+| **Code Reviewer** | Thorough, practical | Pre-close quality review, security scan, test verification |
 
-**Violation of these rules creates technical debt and project chaos.**
+### Agent Frontmatter Configuration
 
-## Path Verification (MANDATORY)
+Agents specify their configuration in frontmatter using Claude Code's supported fields. Reference: https://code.claude.com/docs/en/sub-agents
 
-### Before Generating Any Prompt or Creating Any File
+**Supported frontmatter fields:**
 
-**This is non-negotiable. Failure to follow causes structural damage.**
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `name` | Yes | — | Unique identifier, lowercase + hyphens |
+| `description` | Yes | — | When Claude should delegate to this subagent |
+| `model` | No | `inherit` | `sonnet`, `opus`, `haiku`, or `inherit` |
+| `permissionMode` | No | `default` | Controls permission prompts: `default`, `acceptEdits`, `dontAsk`, `bypassPermissions`, `plan` |
+| `disallowedTools` | No | none | Comma-separated tools to remove from agent's toolset |
+| `skills` | No | none | Comma-separated skills auto-injected into context at startup |
+| `hooks` | No | none | Lifecycle hooks scoped to this subagent |
 
-1. **READ `docs/CANONICAL-PATHS.md` FIRST**
-   - This file is the single source of truth
-   - Never infer paths from memory or context
-   - Never assume paths based on conversation history
+**Complete agent matrix:**
 
-2. **List All Paths**
-   - Before generating a prompt, list every file path it will create/modify
-   - Show the list to the user
+| Plugin | Agent | `model` | `permissionMode` | `disallowedTools` | `skills` |
+|--------|-------|---------|-------------------|--------------------|----------|
+| projman | planner | opus | default | — | frontmatter (2) + body text (12) |
+| projman | orchestrator | sonnet | acceptEdits | — | frontmatter (2) + body text (10) |
+| projman | executor | sonnet | bypassPermissions | — | frontmatter (7) |
+| projman | code-reviewer | opus | default | Write, Edit, MultiEdit | frontmatter (4) |
+| pr-review | coordinator | sonnet | plan | Write, Edit, MultiEdit | — |
+| pr-review | security-reviewer | sonnet | plan | Write, Edit, MultiEdit | — |
+| pr-review | performance-analyst | sonnet | plan | Write, Edit, MultiEdit | — |
+| pr-review | maintainability-auditor | haiku | plan | Write, Edit, MultiEdit | — |
+| pr-review | test-validator | haiku | plan | Write, Edit, MultiEdit | — |
+| data-platform | data-advisor | sonnet | default | — | — |
+| data-platform | data-analysis | sonnet | plan | Write, Edit, MultiEdit | — |
+| data-platform | data-ingestion | haiku | acceptEdits | — | — |
+| viz-platform | design-reviewer | sonnet | plan | Write, Edit, MultiEdit | — |
+| viz-platform | layout-builder | sonnet | default | — | — |
+| viz-platform | component-check | haiku | plan | Write, Edit, MultiEdit | — |
+| viz-platform | theme-setup | haiku | acceptEdits | — | — |
+| contract-validator | full-validation | sonnet | default | — | — |
+| contract-validator | agent-check | haiku | plan | Write, Edit, MultiEdit | — |
+| code-sentinel | security-reviewer | sonnet | plan | Write, Edit, MultiEdit | — |
+| code-sentinel | refactor-advisor | sonnet | acceptEdits | — | — |
+| doc-guardian | doc-analyzer | sonnet | acceptEdits | — | — |
+| clarity-assist | clarity-coach | sonnet | default | Write, Edit, MultiEdit | — |
+| git-flow | git-assistant | haiku | acceptEdits | — | — |
+| claude-config-maintainer | maintainer | sonnet | acceptEdits | — | frontmatter (2) |
+| cmdb-assistant | cmdb-assistant | sonnet | default | — | — |
 
-3. **Verify Each Path**
-   - Check each path against `docs/CANONICAL-PATHS.md`
-   - If a path is not in that file, STOP and ask
+**Design principles:**
+- `bypassPermissions` is granted to exactly ONE agent (Executor) which has code-sentinel PreToolUse hook + Code Reviewer downstream as safety nets.
+- `plan` mode is assigned to all pure analysis agents (pr-review, read-only validators).
+- `disallowedTools: Write, Edit, MultiEdit` provides defense-in-depth on agents that should never write files.
+- `skills` frontmatter is used for agents with ≤7 skills where guaranteed loading is safety-critical. Agents with 8+ skills use body text `## Skills to Load` for selective loading.
+- `hooks` (agent-scoped) is reserved for future use (v6.0+).
 
-4. **Show Verification**
-   - Present a verification table to user:
-   ```
-   | Path | Matches CANONICAL-PATHS.md? |
-   |------|----------------------------|
-   | plugins/projman/... | ✅ Yes |
-   ```
+Override any field by editing the agent's `.md` file in `plugins/{plugin}/agents/`.
 
-5. **Get Confirmation**
-   - User must confirm paths are correct before proceeding
+### MCP Server Tools (Gitea)
 
-### Relative Path Rules
+| Category | Tools |
+|----------|-------|
+| Issues | `list_issues`, `get_issue`, `create_issue`, `update_issue`, `add_comment`, `aggregate_issues` |
+| Labels | `get_labels`, `suggest_labels`, `create_label`, `create_label_smart` |
+| Milestones | `list_milestones`, `get_milestone`, `create_milestone`, `update_milestone`, `delete_milestone` |
+| Dependencies | `list_issue_dependencies`, `create_issue_dependency`, `remove_issue_dependency`, `get_execution_order` |
+| Wiki | `list_wiki_pages`, `get_wiki_page`, `create_wiki_page`, `update_wiki_page`, `create_lesson`, `search_lessons`, `allocate_rfc_number` |
+| **Pull Requests** | `list_pull_requests`, `get_pull_request`, `get_pr_diff`, `get_pr_comments`, `create_pr_review`, `add_pr_comment` |
+| Validation | `validate_repo_org`, `get_branch_protection` |
 
-- Plugin to bundled MCP server: `${CLAUDE_PLUGIN_ROOT}/mcp-servers/{server}`
-- Marketplace to plugin: `./../../../plugins/{plugin-name}`
-- **ALWAYS calculate from CANONICAL-PATHS.md, never from memory**
+### Hybrid Configuration
 
-### Recovery Protocol
+| Level | Location | Purpose |
+|-------|----------|---------|
+| System | `~/.config/claude/gitea.env` | Credentials (GITEA_API_URL, GITEA_API_TOKEN) |
+| Project | `.env` in project root | Repository specification (GITEA_ORG, GITEA_REPO) |
 
-If you suspect paths are wrong:
-1. Read `docs/CANONICAL-PATHS.md`
-2. Compare actual structure against documented structure
-3. Report discrepancies
-4. Generate corrective prompt if needed
+**Note:** `GITEA_ORG` is at project level since different projects may belong to different organizations.
 
-## Core Architecture
+### Branch-Aware Security
 
-### Three-Agent Model
+| Branch Pattern | Mode | Capabilities |
+|----------------|------|--------------|
+| `development`, `feat/*` | Development | Full access |
+| `staging` | Staging | Read-only code, can create issues |
+| `main`, `master` | Production | Read-only, emergency only |
 
-The plugins implement a three-agent architecture that mirrors the proven workflow:
+### RFC System
 
-**Planner Agent** (`agents/planner.md`)
-- Performs architecture analysis and sprint planning
-- Creates detailed planning documents
-- Makes architectural decisions
-- Creates Gitea issues with appropriate labels
-- Personality: Asks clarifying questions, thinks through edge cases, never rushes
+Wiki-based Request for Comments system for tracking feature ideas from proposal through implementation.
 
-**Orchestrator Agent** (`agents/orchestrator.md`)
-- Coordinates sprint execution
-- Generates lean execution prompts (not full docs)
-- Tracks progress and updates documentation
-- Handles Git operations (commit, merge, cleanup)
-- Manages task dependencies
-- Personality: Concise, action-oriented, tracks details meticulously
+**RFC Wiki Naming:**
+- RFC pages: `RFC-NNNN: Short Title` (4-digit zero-padded)
+- Index page: `RFC-Index` (auto-maintained)
 
-**Executor Agent** (`agents/executor.md`)
-- Implements features according to execution prompts
-- Writes clean, tested code
-- Follows architectural decisions from planning
-- Generates completion reports
-- Personality: Implementation-focused, follows specs precisely
+**Lifecycle:** Draft → Review → Approved → Implementing → Implemented
 
-### MCP Server Integration
+**Integration with Sprint Planning:**
+- `/sprint plan` detects approved RFCs and offers selection
+- `/sprint close` updates RFC status on completion
 
-**Gitea MCP Server** (Python) - bundled in projman plugin
+## Label Taxonomy
 
-**Issue Tools:**
-- `list_issues` - Query issues with filters
-- `get_issue` - Fetch single issue details
-- `create_issue` - Create new issue with labels
-- `update_issue` - Modify existing issue
-- `add_comment` - Add comments to issues
-- `get_labels` - Fetch org + repo label taxonomy
-- `suggest_labels` - Analyze context and suggest appropriate labels
+58 labels total: 31 organization + 27 repository
 
-**Milestone Tools:**
-- `list_milestones` - List sprint milestones
-- `get_milestone` - Get milestone details
-- `create_milestone` - Create sprint milestone
-- `update_milestone` - Update/close milestone
+**Organization:** Agent/2, Complexity/3, Efforts/5, Priority/4, Risk/3, Source/4, Status/4, Type/6
+**Repository:** Component/9, Tech/7, Domain/2, Epic/5, RnD/4
 
-**Dependency Tools:**
-- `list_issue_dependencies` - Get issue dependencies
-- `create_issue_dependency` - Create dependency between issues
-- `get_execution_order` - Get parallel execution batches
-
-**Wiki Tools (Gitea Wiki):**
-- `list_wiki_pages` - List wiki pages
-- `get_wiki_page` - Fetch specific page content
-- `create_wiki_page` - Create new wiki page
-- `create_lesson` - Create lessons learned document
-- `search_lessons` - Search past lessons by tags
-
-**Validation Tools:**
-- `validate_repo_org` - Check repo belongs to organization
-- `get_branch_protection` - Check branch protection rules
-- `create_label` - Create missing required labels
-
-**Key Architecture Points:**
-- MCP servers are **bundled inside each plugin** at `plugins/{plugin}/mcp-servers/`
-- This ensures plugins work when cached by Claude Code (only plugin directory is cached)
-- Configuration uses hybrid approach (system-level + project-level)
-- All plugins reference `${CLAUDE_PLUGIN_ROOT}/mcp-servers/` in their `.mcp.json` files
-
-## Branch-Aware Security Model
-
-Plugin behavior adapts to the current Git branch to prevent accidental changes:
-
-**Development Mode** (`development`, `feat/*`)
-- Full access to all operations
-- Can create Gitea issues
-- Can modify all files
-
-**Staging Mode** (`staging`)
-- Read-only for application code
-- Can modify `.env` files
-- Can create issues to document needed fixes
-- Warns on attempted code changes
-
-**Production Mode** (`main`)
-- Read-only for application code
-- Emergency-only `.env` modifications
-- Can create incident issues
-- Blocks code changes
-
-This behavior is implemented in both CLAUDE.md (file-level) and plugin agents (tool-level).
-
-## Label Taxonomy System
-
-The project uses a sophisticated 43-label taxonomy at organization level:
-
-**Organization Labels (27):**
-- Agent/2, Complexity/3, Efforts/5, Priority/4, Risk/3, Source/4, Type/6
-
-**Repository Labels (16):**
-- Component/9, Tech/7
-
-**Important Labels:**
-- `Type/Refactor` - For architectural changes and code restructuring (exclusive Type label)
-- Used for service extraction, architecture modifications, technical debt
-
-The label system includes:
-- `skills/label-taxonomy/labels-reference.md` - Local reference synced from Gitea
-- Label suggestion logic that detects appropriate labels from context
-- `/labels-sync` command to review and sync changes from Gitea
+Sync with `/labels sync` command.
 
 ## Lessons Learned System
 
-**Critical Feature:** After 15 sprints without lesson capture, repeated mistakes occurred (e.g., Claude Code infinite loops on similar issues 2-3 times).
-
-**Gitea Wiki Structure:**
-Lessons learned are stored in the Gitea repository's built-in wiki under `lessons-learned/sprints/`.
+Stored in Gitea Wiki under `lessons-learned/sprints/`.
 
 **Workflow:**
-- Orchestrator captures lessons at sprint close via Gitea Wiki MCP tools
-- Planner searches relevant lessons at sprint start using `search_lessons`
-- Tags enable cross-project lesson discovery
-- Focus on preventable repetitions, not every detail
-- Web interface available through Gitea Wiki
+1. Orchestrator captures at sprint close via MCP tools
+2. Planner searches at sprint start using `search_lessons`
+3. Tags enable cross-project discovery
 
-## Development Workflow
+## Common Operations
 
-### Build Order
+### Adding a New Plugin
 
-1. **Phase 1-8:** Build `projman` plugin first (single-repo)
-2. **Phase 9-11:** Build `pmo` plugin second (multi-project)
-3. **Phase 12:** Production deployment
+1. Create `plugins/{name}/.claude-plugin/plugin.json` (standard schema fields only — no custom fields)
+2. Create `plugins/{name}/.claude-plugin/metadata.json` — must include `"domain"` field (`core`, `data`, `saas`, `ops`, or `debug`)
+3. Add entry to `.claude-plugin/marketplace.json` with category, tags, license (no custom fields — Claude Code schema is strict)
+4. Create `claude-md-integration.md`
+5. If using new MCP server, add to root `mcp-servers/` and update `.mcp.json`
+6. Run `./scripts/validate-marketplace.sh` — rejects plugins without valid `domain` field
+7. Update `CHANGELOG.md`
 
-See [docs/reference-material/projman-implementation-plan.md](docs/reference-material/projman-implementation-plan.md) for the complete 12-phase implementation plan.
-
-### Repository Structure (DEFINITIVE)
-
-⚠️ **See `docs/CANONICAL-PATHS.md` for the authoritative path reference - THIS IS THE SINGLE SOURCE OF TRUTH**
-
-```
-personal-projects/support-claude-mktplace/
-├── .claude-plugin/
-│   └── marketplace.json
-├── plugins/                        # ← ALL PLUGINS (with bundled MCP servers)
-│   ├── projman/                    # ← PROJECT PLUGIN
-│   │   ├── .claude-plugin/
-│   │   │   └── plugin.json
-│   │   ├── .mcp.json               # Points to ${CLAUDE_PLUGIN_ROOT}/mcp-servers/
-│   │   ├── mcp-servers/            # ← MCP servers BUNDLED IN plugin
-│   │   │   └── gitea/              # Gitea + Wiki tools
-│   │   │       ├── .venv/
-│   │   │       ├── requirements.txt
-│   │   │       ├── mcp_server/
-│   │   │       └── tests/
-│   │   ├── commands/
-│   │   │   ├── sprint-plan.md
-│   │   │   ├── sprint-start.md
-│   │   │   ├── sprint-status.md
-│   │   │   ├── sprint-close.md
-│   │   │   ├── labels-sync.md
-│   │   │   └── initial-setup.md
-│   │   ├── agents/
-│   │   │   ├── planner.md
-│   │   │   ├── orchestrator.md
-│   │   │   └── executor.md
-│   │   ├── skills/
-│   │   │   └── label-taxonomy/
-│   │   │       └── labels-reference.md
-│   │   ├── README.md
-│   │   └── CONFIGURATION.md
-│   ├── projman-pmo/                # ← PMO PLUGIN
-│   │   ├── .claude-plugin/
-│   │   │   └── plugin.json
-│   │   ├── .mcp.json
-│   │   ├── commands/
-│   │   ├── agents/
-│   │   │   └── pmo-coordinator.md
-│   │   └── README.md
-│   ├── cmdb-assistant/             # ← CMDB PLUGIN
-│   │   ├── .claude-plugin/
-│   │   │   └── plugin.json
-│   │   ├── .mcp.json               # Points to ${CLAUDE_PLUGIN_ROOT}/mcp-servers/
-│   │   ├── mcp-servers/            # ← MCP servers BUNDLED IN plugin
-│   │   │   └── netbox/
-│   │   │       ├── .venv/
-│   │   │       ├── requirements.txt
-│   │   │       └── mcp_server/
-│   │   ├── commands/
-│   │   └── agents/
-│   └── project-hygiene/            # ← CLEANUP PLUGIN
-│       └── ...
-├── scripts/                        # Setup and maintenance scripts
-│   ├── setup.sh
-│   └── post-update.sh
-└── docs/
-```
-
-### Key Design Decisions
-
-**MCP Servers (Bundled in Plugins):**
-- **Gitea MCP**: Issues, labels, wiki, milestones, dependencies (bundled in projman)
-- **NetBox MCP**: Infrastructure management (bundled in cmdb-assistant)
-- Servers are **bundled inside each plugin** that needs them
-- This ensures plugins work when cached by Claude Code
-
-**Python Implementation:**
-- Python chosen over Node.js for MCP servers
-- Better suited for configuration management and modular code
-- Easier to maintain and extend
-- Virtual environment (.venv) per MCP server
-
-**Hybrid Configuration:**
-- **System-level**: `~/.config/claude/gitea.env` (credentials)
-- **Project-level**: `project-root/.env` (repository specification)
-- Merge strategy: project overrides system
-- Benefits: Single token per service, easy multi-project setup
-
-**Skills as Knowledge, Not Orchestrators:**
-- Skills provide supporting knowledge loaded when relevant
-- Agents are the primary interface
-- Reduces token usage
-- Makes knowledge reusable across agents
-
-**Branch Detection:**
-- Two layers: CLAUDE.md (file access) + Plugin agents (tool usage)
-- Defense in depth approach
-- Plugin works with or without CLAUDE.md
-
-## Multi-Project Context (PMO Plugin)
-
-The `projman-pmo` plugin coordinates interdependent projects across an organization. Example use cases:
-- Main product repository
-- Marketing/documentation sites
-- Extracted services
-- Supporting tools
-
-PMO plugin adds:
-- Cross-project issue aggregation (all repos in organization)
-- Dependency tracking and visualization
-- Resource allocation across projects
-- Deployment coordination
-- Multi-project prioritization
-- Company-wide lessons learned search
-
-**Configuration Difference:**
-- PMO operates at company level (no `GITEA_REPO`)
-- Accesses all repositories in organization
-- Aggregates issues and lessons across projects
-
-Build PMO plugin AFTER projman is working and validated.
-
-## Testing Approach
-
-**Local Marketplace:**
-Create local marketplace for plugin development:
-```
-~/projman-dev-marketplace/
-├── .claude-plugin/
-│   └── marketplace.json
-└── projman/              # Symlink to plugin directory
-```
-
-**Integration Testing:**
-Test in a real repository with actual Gitea instance before distribution.
-
-**Success Metrics:**
-- Sprint planning time reduced 40%
-- Manual steps eliminated: 10+ per sprint
-- Lessons learned capture rate: 100% (vs 0% before)
-- Label accuracy on issues: 90%+
-- User satisfaction: Better than current manual workflow
-
-## Important Notes
-
-- **Never modify docker-compose files with 'version' attribute** - It's obsolete
-- **Focus on implementation, not over-engineering** - This system has been validated over 15 sprints
-- **Lessons learned is critical** - Prevents repeated mistakes (e.g., Claude infinite loops)
-- **Type/Refactor label** - Newly implemented at org level for architectural work
-- **Branch detection must be 100% reliable** - Prevents production accidents
-- **Python for MCP servers** - Use Python 3.8+ with virtual environments
-- **CLI tools forbidden** - Use MCP tools exclusively, never CLI tools like `tea` or `gh`
-
-## CRITICAL: Rules You MUST Follow
-
-### DO NOT MODIFY .gitignore Without Explicit Permission
-- This is a **private repository** - credentials in `.env` files are intentional
-- **NEVER** add `.env` or `.env.*` to .gitignore
-- **NEVER** add venv patterns unless explicitly asked
-- If you think something should be ignored, ASK FIRST
-
-### Plugin Structure Requirements
-- **plugin.json MUST be in `.claude-plugin/` directory** - NOT in plugin root
-- Every plugin in the repo MUST be listed in the marketplace.json
-- After creating/modifying a plugin, VERIFY it's in the marketplace
-
-### Hooks Syntax (Claude Code Official)
-- **Valid events**: `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `SessionStart`, `SessionEnd`, `Notification`, `Stop`, `SubagentStop`, `PreCompact`
-- **INVALID events**: `task-completed`, `file-changed`, `git-commit-msg-needed` (these DO NOT exist)
-- Hooks schema:
+**Domain field is required in metadata.json (v8.0.0+, moved from plugin.json in v9.1.2):**
 ```json
 {
-  "hooks": {
-    "EventName": [
-      {
-        "matcher": "optional-pattern",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/path/to/script.sh"
-          }
-        ]
-      }
-    ]
-  }
+  "domain": "core"
 }
 ```
 
-### MCP Server Configuration
-- MCP servers MUST use venv python: `${CLAUDE_PLUGIN_ROOT}/../../mcp-servers/NAME/.venv/bin/python`
-- NEVER use bare `python` command - always use venv path
-- Test MCP servers after any config change
+**Naming convention:** New plugins use domain prefix (`saas-*`, `ops-*`, `data-*`, `debug-*`). Core plugins have no prefix.
 
-### Before Completing Any Plugin Work
-1. Verify plugin.json is in `.claude-plugin/` directory
-2. Verify plugin is listed in marketplace.json
-3. Test MCP server configs load correctly
-4. Verify hooks use valid event types
-5. Check .gitignore wasn't modified inappropriately
+### Domain Assignments
+
+| Domain | Plugins |
+|--------|---------|
+| `core` | projman, git-flow, pr-review, code-sentinel, doc-guardian, clarity-assist, contract-validator, claude-config-maintainer, project-hygiene |
+| `data` | data-platform, viz-platform, data-seed |
+| `saas` | saas-api-platform, saas-db-migrate, saas-react-platform, saas-test-pilot |
+| `ops` | cmdb-assistant, ops-release-manager, ops-deploy-pipeline |
+| `debug` | debug-mcp |
+
+### Adding a Command to projman
+
+1. Create `plugins/projman/commands/{name}.md`
+2. Update marketplace description if significant
+
+### Validation
+
+```bash
+./scripts/validate-marketplace.sh  # Validates all manifests
+```
+
+## Path Verification Protocol
+
+**Before creating any file:**
+
+1. Read `docs/CANONICAL-PATHS.md`
+2. List all paths to be created/modified
+3. Verify each against canonical paths
+4. If not in canonical paths, STOP and ask
 
 ## Documentation Index
 
-This repository contains comprehensive planning documentation:
+| Document | Purpose |
+|----------|---------|
+| `docs/ARCHITECTURE.md` | System architecture and plugin reference |
+| `docs/CANONICAL-PATHS.md` | **Single source of truth** for paths |
+| `docs/COMMANDS-CHEATSHEET.md` | All commands quick reference |
+| `docs/CONFIGURATION.md` | Centralized setup guide |
+| `docs/DEBUGGING-CHECKLIST.md` | Systematic troubleshooting guide |
+| `docs/MIGRATION-v9.md` | v8.x to v9.0.0 migration guide |
+| `docs/UPDATING.md` | Update guide for the marketplace |
+| `plugins/projman/CONFIGURATION.md` | Projman quick reference (links to central) |
 
-- **`docs/CANONICAL-PATHS.md`** - ⚠️ SINGLE SOURCE OF TRUTH for all paths (MANDATORY reading before any file operations)
-- **`docs/DOCUMENT-INDEX.md`** - Complete guide to all planning documents
-- **`docs/projman-implementation-plan-updated.md`** - Full 12-phase implementation plan
-- **`docs/projman-python-quickstart.md`** - Python-specific implementation guide
-- **`docs/two-mcp-architecture-guide.md`** - Deep dive into two-MCP architecture
+## Installation Paths
 
-**Start with:** `docs/DOCUMENT-INDEX.md` for navigation guidance
+Understanding where files live is critical for debugging:
 
-## Recent Updates (Updated: 2025-06-11)
+| Context | Path | Purpose |
+|---------|------|---------|
+| **Source** | `~/claude-plugins-work/` | Development - edit here |
+| **Installed** | `~/.claude/plugins/marketplaces/leo-claude-mktplace/` | Runtime - Claude uses this |
+| **Cache** | `~/.claude/` | Plugin metadata and settings |
 
-### Planning Phase Complete
-- Comprehensive 12-phase implementation plan finalized
-- Architecture decisions documented and validated
-- Two-MCP-server approach confirmed (Gitea + Wiki.js)
-- Python selected for MCP server implementation
-- Hybrid configuration strategy defined (system + project level)
-- Wiki.js structure planned with configurable base path
-- Repository structure designed with shared MCP servers
+**Key insight:** Edits to source require reinstall/update to take effect at runtime.
 
-### Key Architectural Decisions Made
-1. **Shared MCP Servers**: Both plugins use the same MCP codebase at `mcp-servers/`
-2. **Mode Detection**: MCP servers detect project vs company-wide mode via environment variables
-3. **Python Implementation**: MCP servers written in Python (not Node.js) for better configuration handling
-4. **Wiki.js Integration**: Lessons learned and documentation moved to Wiki.js for better collaboration
-5. **Hybrid Config**: System-level credentials + project-level paths for flexibility
+## Debugging & Troubleshooting
 
-### Next Steps
-- Begin Phase 1.1a: Gitea MCP Server implementation
-- Set up Python virtual environments
-- Create configuration loaders
-- Implement core Gitea tools (issues, labels)
-- Write integration tests
+See `docs/DEBUGGING-CHECKLIST.md` for systematic troubleshooting.
+
+**Common Issues:**
+| Symptom | Likely Cause | Fix |
+|---------|--------------|-----|
+| "X MCP servers failed" | Missing venv in installed path | `cd ~/.claude/plugins/marketplaces/leo-claude-mktplace && ./scripts/setup.sh` |
+| MCP tools not available | Venv missing or .mcp.json misconfigured | Run `/cv status` to diagnose |
+| Changes not taking effect | Editing source, not installed | Reinstall plugin or edit installed path |
+
+**Diagnostic Commands:**
+- `/cv status` - Marketplace-wide health check (installation, MCP, configuration)
+- `/hygiene check` - Project file organization and cleanup check
+
+## Versioning Workflow
+
+This project follows [SemVer](https://semver.org/) and [Keep a Changelog](https://keepachangelog.com).
+
+### Version Locations (must stay in sync)
+
+| Location | Format | Example |
+|----------|--------|---------|
+| Git tags | `vX.Y.Z` | `v3.2.0` |
+| README.md title | `# Leo Claude Marketplace - vX.Y.Z` | `v3.2.0` |
+| marketplace.json | `"version": "X.Y.Z"` | `3.2.0` |
+| CHANGELOG.md | `## [X.Y.Z] - YYYY-MM-DD` | `[3.2.0] - 2026-01-24` |
+
+### During Development
+
+**All changes go under `[Unreleased]` in CHANGELOG.md.** Never create a versioned section until release time.
+
+```markdown
+## [Unreleased]
+
+### Added
+- New feature description
+
+### Fixed
+- Bug fix description
+```
+
+### Creating a Release
+
+Use the release script to ensure consistency:
+
+```bash
+./scripts/release.sh 3.2.0
+```
+
+The script will:
+1. Validate `[Unreleased]` section has content
+2. Replace `[Unreleased]` with `[3.2.0] - YYYY-MM-DD`
+3. Update README.md title
+4. Update marketplace.json version
+5. Commit and create git tag
+
+### SemVer Guidelines
+
+| Change Type | Version Bump | Example |
+|-------------|--------------|---------|
+| Bug fixes only | PATCH (x.y.**Z**) | 3.1.1 → 3.1.2 |
+| New features (backwards compatible) | MINOR (x.**Y**.0) | 3.1.2 → 3.2.0 |
+| Breaking changes | MAJOR (**X**.0.0) | 3.2.0 → 4.0.0 |
+
+---
+
+**Last Updated:** 2026-02-07

README.md

@@ -1,85 +1,160 @@
-# Claude Code Marketplace
+# Leo Claude Marketplace — v9.1.2
 
-A collection of Claude Code plugins for project management, infrastructure automation, and development workflows.
+A plugin marketplace for Claude Code providing sprint management, code review, security scanning, infrastructure automation, and development workflow tools. 20 plugins across 5 domains, backed by 5 shared MCP servers.
 
 ## Plugins
 
-### [projman](./plugins/projman/README.md) v2.0.0
-**Sprint Planning and Project Management**
+### Core (9 plugins — v9.0.1)
 
-AI-guided sprint planning with full Gitea integration. Transforms a proven 15-sprint workflow into a distributable plugin.
+| Plugin | Description |
+|--------|-------------|
+| `projman` | Sprint planning and project management with Gitea integration |
+| `git-flow` | Git workflow automation with intelligent commit messages and branch management |
+| `pr-review` | Multi-agent pull request review with confidence scoring |
+| `code-sentinel` | Security scanning and code refactoring tools |
+| `doc-guardian` | Documentation drift detection and synchronization |
+| `clarity-assist` | Prompt optimization with ND-friendly accommodations |
+| `contract-validator` | Cross-plugin compatibility validation and agent verification |
+| `claude-config-maintainer` | CLAUDE.md and settings.local.json optimization |
+| `project-hygiene` | Manual project file cleanup checks |
 
-- Three-agent model: Planner, Orchestrator, Executor
-- Intelligent label suggestions from 43-label taxonomy
-- Lessons learned capture via Gitea Wiki
-- Native issue dependencies with parallel execution
-- Milestone management for sprint organization
-- Branch-aware security (development/staging/production)
+### Data (3 plugins)
 
-**Commands:** `/sprint-plan`, `/sprint-start`, `/sprint-status`, `/sprint-close`, `/labels-sync`, `/initial-setup`
+| Plugin | Version | Description |
+|--------|---------|-------------|
+| `data-platform` | 9.0.1 | pandas, PostgreSQL/PostGIS, and dbt integration |
+| `viz-platform` | 9.0.1 | Dash Mantine Components validation, Plotly charts, and theming |
+| `data-seed` | 0.1.0 — scaffold | Test data generation and database seeding |
 
-### [claude-config-maintainer](./plugins/claude-config-maintainer/README.md)
-**CLAUDE.md Optimization and Maintenance**
+### Ops (3 plugins)
 
-Analyze, optimize, and create CLAUDE.md configuration files for Claude Code projects.
+| Plugin | Version | Description |
+|--------|---------|-------------|
+| `cmdb-assistant` | 9.0.1 | NetBox CMDB integration with data quality validation |
+| `ops-release-manager` | 0.1.0 — scaffold | Release management with SemVer and changelog automation |
+| `ops-deploy-pipeline` | 0.1.0 — scaffold | Deployment pipeline for Docker Compose and systemd |
 
-- Structure and clarity scoring (100-point system)
-- Automatic optimization with preview and backup
-- Project-aware initialization with stack detection
-- Best practices enforcement
+### SaaS (4 plugins — v0.1.0 scaffolds)
 
-**Commands:** `/config-analyze`, `/config-optimize`, `/config-init`
+| Plugin | Description |
+|--------|-------------|
+| `saas-api-platform` | REST/GraphQL API scaffolding for FastAPI and Express |
+| `saas-db-migrate` | Database migration management for Alembic, Prisma, raw SQL |
+| `saas-react-platform` | React frontend toolkit for Next.js and Vite |
+| `saas-test-pilot` | Test automation for pytest, Jest, Vitest, Playwright |
 
-### [cmdb-assistant](./plugins/cmdb-assistant/README.md)
-**NetBox CMDB Integration**
+### Debug (1 plugin — v0.1.0 scaffold)
 
-Full CRUD operations for network infrastructure management directly from Claude Code.
+| Plugin | Description |
+|--------|-------------|
+| `debug-mcp` | MCP server debugging, inspection, and development toolkit |
 
-- Device, IP, site, and rack management
-- Smart search across all NetBox modules
-- Conversational infrastructure queries
-- Audit trail and change tracking
+## Quick Start
 
-**Commands:** `/cmdb-search`, `/cmdb-device`, `/cmdb-ip`, `/cmdb-site`
+### Launch with profiles
 
-### [project-hygiene](./plugins/project-hygiene/README.md)
-**Post-Task Cleanup Automation**
+```bash
+./scripts/claude-launch.sh [profile] [extra-args...]
+```
 
-Hook-based cleanup that runs after Claude completes work.
+| Profile | Plugins Loaded | Use Case |
+|---------|----------------|----------|
+| `sprint` | projman, git-flow, pr-review, code-sentinel, doc-guardian, clarity-assist | Default. Sprint planning and development |
+| `review` | pr-review, code-sentinel | Lightweight code review |
+| `data` | data-platform, viz-platform | Data engineering and visualization |
+| `infra` | cmdb-assistant | Infrastructure/CMDB management |
+| `full` | All 20 plugins | When you need everything |
 
-- Deletes temp files (`*.tmp`, `*.bak`, `__pycache__`, etc.)
-- Warns about unexpected files in project root
-- Identifies orphaned supporting files
-- Configurable via `.hygiene.json`
+```bash
+./scripts/claude-launch.sh                    # Default sprint profile
+./scripts/claude-launch.sh data --model opus  # Data profile with Opus
+./scripts/claude-launch.sh full               # Load all plugins
+```
+
+### Common commands
+
+```bash
+/sprint plan                  # Plan a sprint with architecture analysis
+/sprint start                 # Begin sprint execution
+/gitflow commit --push        # Commit with auto-generated message and push
+/pr review                    # Full multi-agent PR review
+/sentinel scan                # Security audit
+/doc audit                    # Check for documentation drift
+/cv status                    # Marketplace health check
+```
+
+## Repository Structure
+
+```
+leo-claude-mktplace/
+├── .claude-plugin/                # Marketplace manifest
+│   ├── marketplace.json
+│   ├── marketplace-lean.json      # Lean profile (6 core plugins)
+│   └── marketplace-full.json      # Full profile (all plugins)
+├── mcp-servers/                   # Shared MCP servers
+│   ├── gitea/                     # Gitea (issues, PRs, wiki)
+│   ├── netbox/                    # NetBox (DCIM, IPAM)
+│   ├── data-platform/             # pandas, PostgreSQL, dbt
+│   ├── viz-platform/              # DMC, Plotly, theming
+│   └── contract-validator/        # Plugin compatibility validation
+├── plugins/                       # All plugins (20 total)
+│   ├── projman/                   # [core] Sprint management
+│   ├── git-flow/                  # [core] Git workflow automation
+│   ├── pr-review/                 # [core] PR review
+│   ├── clarity-assist/            # [core] Prompt optimization
+│   ├── doc-guardian/              # [core] Documentation drift detection
+│   ├── code-sentinel/             # [core] Security scanning
+│   ├── claude-config-maintainer/  # [core] CLAUDE.md optimization
+│   ├── contract-validator/        # [core] Cross-plugin validation
+│   ├── project-hygiene/           # [core] Manual cleanup checks
+│   ├── cmdb-assistant/            # [ops] NetBox CMDB integration
+│   ├── data-platform/             # [data] Data engineering
+│   ├── viz-platform/              # [data] Visualization
+│   ├── data-seed/                 # [data] Test data generation (scaffold)
+│   ├── saas-api-platform/         # [saas] API scaffolding (scaffold)
+│   ├── saas-db-migrate/           # [saas] DB migrations (scaffold)
+│   ├── saas-react-platform/       # [saas] React toolkit (scaffold)
+│   ├── saas-test-pilot/           # [saas] Test automation (scaffold)
+│   ├── ops-release-manager/       # [ops] Release management (scaffold)
+│   ├── ops-deploy-pipeline/       # [ops] Deployment pipeline (scaffold)
+│   └── debug-mcp/                 # [debug] MCP debugging (scaffold)
+├── scripts/                       # Setup and maintenance
+│   ├── setup.sh                   # Initial setup (create venvs, config)
+│   ├── post-update.sh             # Post-update (clear cache, changelog)
+│   ├── setup-venvs.sh             # MCP server venv management (cache-based)
+│   ├── validate-marketplace.sh    # Marketplace compliance validation
+│   ├── verify-hooks.sh            # Hook inventory verification
+│   ├── release.sh                 # Release automation with version bumping
+│   ├── claude-launch.sh           # Profile-based launcher
+│   ├── install-plugin.sh          # Install plugin to consumer project
+│   ├── list-installed.sh          # Show installed plugins in a project
+│   └── uninstall-plugin.sh        # Remove plugin from consumer project
+├── docs/                          # Documentation
+│   ├── ARCHITECTURE.md            # System architecture & plugin reference
+│   ├── CANONICAL-PATHS.md         # Authoritative path reference
+│   ├── COMMANDS-CHEATSHEET.md     # All commands quick reference
+│   ├── CONFIGURATION.md           # Centralized setup guide
+│   ├── DEBUGGING-CHECKLIST.md     # Systematic troubleshooting guide
+│   ├── MIGRATION-v9.md            # v8.x to v9.0.0 migration guide
+│   └── UPDATING.md               # Update guide
+├── CLAUDE.md                      # Project instructions for Claude Code
+├── README.md
+├── CHANGELOG.md
+├── LICENSE
+└── .gitignore
+```
 
 ## MCP Servers
 
-MCP servers are **bundled inside each plugin** that needs them. This ensures plugins work when cached by Claude Code.
+All MCP servers are shared at repository root and configured in `.mcp.json`.
 
-### Gitea MCP Server (bundled in projman)
-
-Full Gitea API integration for project management.
-
-| Category | Tools |
-|----------|-------|
-| Issues | `list_issues`, `get_issue`, `create_issue`, `update_issue`, `add_comment` |
-| Labels | `get_labels`, `suggest_labels`, `create_label` |
-| Wiki | `list_wiki_pages`, `get_wiki_page`, `create_wiki_page`, `create_lesson`, `search_lessons` |
-| Milestones | `list_milestones`, `get_milestone`, `create_milestone`, `update_milestone` |
-| Dependencies | `list_issue_dependencies`, `create_issue_dependency`, `get_execution_order` |
-| Validation | `validate_repo_org`, `get_branch_protection` |
-
-### NetBox MCP Server (bundled in cmdb-assistant)
-
-Comprehensive NetBox REST API integration for infrastructure management.
-
-| Module | Coverage |
-|--------|----------|
-| DCIM | Sites, Racks, Devices, Interfaces, Cables |
-| IPAM | Prefixes, IPs, VLANs, VRFs |
-| Circuits | Providers, Circuits, Terminations |
-| Virtualization | Clusters, VMs, Interfaces |
-| Extras | Tags, Custom Fields, Audit Log |
+| Server | Used By | External System |
+|--------|---------|-----------------|
+| gitea | projman, pr-review | Gitea (issues, PRs, wiki, milestones) |
+| netbox | cmdb-assistant | NetBox (DCIM, IPAM) |
+| data-platform | data-platform | PostgreSQL, dbt |
+| viz-platform | viz-platform | DMC component registry |
+| contract-validator | contract-validator | Internal validation |
 
 ## Installation
 
@@ -89,126 +164,71 @@ Comprehensive NetBox REST API integration for infrastructure management.
 - Python 3.10+
 - Access to target services (Gitea, NetBox as needed)
 
-### Quick Start
+### Add marketplace to Claude Code
 
-1. **Clone the repository:**
-   ```bash
-   git clone ssh://git@hotserv.tailc9b278.ts.net:2222/personal-projects/support-claude-mktplace.git
-   cd support-claude-mktplace
-   ```
-
-2. **Install MCP server dependencies:**
-   ```bash
-   # Gitea MCP (for projman)
-   cd plugins/projman/mcp-servers/gitea
-   python3 -m venv .venv
-   source .venv/bin/activate
-   pip install -r requirements.txt
-   deactivate
-
-   # NetBox MCP (for cmdb-assistant)
-   cd ../../../cmdb-assistant/mcp-servers/netbox
-   python3 -m venv .venv
-   source .venv/bin/activate
-   pip install -r requirements.txt
-   deactivate
-   ```
-
-3. **Configure system-level credentials:**
-   ```bash
-   mkdir -p ~/.config/claude
-
-   # Gitea credentials
-   cat > ~/.config/claude/gitea.env << 'EOF'
-   GITEA_URL=https://gitea.example.com
-   GITEA_TOKEN=your_token
-   GITEA_ORG=your_org
-   EOF
-
-   # NetBox credentials
-   cat > ~/.config/claude/netbox.env << 'EOF'
-   NETBOX_API_URL=https://netbox.example.com/api
-   NETBOX_API_TOKEN=your_token
-   EOF
-
-   chmod 600 ~/.config/claude/*.env
-   ```
-
-4. **Configure project-level settings:**
-   ```bash
-   # In your target project root
-   cat > .env << 'EOF'
-   GITEA_REPO=your-repository-name
-   EOF
-   ```
-
-5. **Add marketplace to Claude Code:**
-
-   Add to your project's `.claude/settings.json`:
-   ```json
-   {
-     "pluginMarketplace": "/path/to/support-claude-mktplace"
-   }
-   ```
-
-## Repository Structure
-
-```
-support-claude-mktplace/
-├── .claude-plugin/                # Marketplace manifest
-│   └── marketplace.json
-├── plugins/                       # All plugins (with bundled MCP servers)
-│   ├── projman/                   # Sprint management plugin
-│   │   ├── .claude-plugin/
-│   │   ├── .mcp.json
-│   │   ├── mcp-servers/           # Bundled MCP server
-│   │   │   └── gitea/
-│   │   ├── commands/
-│   │   ├── agents/
-│   │   └── skills/
-│   ├── claude-config-maintainer/  # CLAUDE.md optimization plugin
-│   │   ├── .claude-plugin/
-│   │   ├── commands/
-│   │   └── agents/
-│   ├── cmdb-assistant/            # NetBox CMDB integration
-│   │   ├── .claude-plugin/
-│   │   ├── .mcp.json
-│   │   ├── mcp-servers/           # Bundled MCP server
-│   │   │   └── netbox/
-│   │   ├── commands/
-│   │   └── agents/
-│   ├── projman-pmo/               # PMO coordination plugin (planned)
-│   └── project-hygiene/           # Cleanup automation plugin
-├── docs/                          # Reference documentation
-│   ├── CANONICAL-PATHS.md         # Single source of truth for paths
-│   └── references/
-└── scripts/                       # Setup and maintenance scripts
+```bash
+/plugin marketplace add https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git
 ```
 
-## Key Features (v2.0.0)
+Or add to `.claude/settings.json`:
 
-### Parallel Execution
-Tasks are batched by dependency graph for optimal parallel execution:
-```
-Batch 1 (parallel): Task A, Task B, Task C
-Batch 2 (parallel): Task D, Task E  (depend on Batch 1)
-Batch 3 (sequential): Task F        (depends on Batch 2)
+```json
+{
+  "extraKnownMarketplaces": {
+    "leo-claude-mktplace": {
+      "source": {
+        "source": "git",
+        "url": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git"
+      }
+    }
+  }
+}
 ```
 
-### Naming Conventions
-- **Tasks:** `[Sprint XX] <type>: <description>`
-- **Branches:** `feat/`, `fix/`, `debug/` prefixes with issue numbers
+### Setup MCP servers
 
-### CLI Tools Blocked
-All agents use MCP tools exclusively. CLI tools like `tea` or `gh` are forbidden to ensure consistent, auditable operations.
+After installing, create Python venvs for MCP servers:
+
+```bash
+cd ~/.claude/plugins/marketplaces/leo-claude-mktplace && ./scripts/setup.sh
+```
+
+Then restart Claude Code and run the interactive setup:
+
+```
+/projman setup
+```
+
+See [CONFIGURATION.md](./docs/CONFIGURATION.md) for manual setup and advanced options.
+
+### Install to consumer projects
+
+```bash
+./scripts/install-plugin.sh <plugin-name> /path/to/project
+./scripts/list-installed.sh /path/to/project
+./scripts/uninstall-plugin.sh <plugin-name> /path/to/project
+```
 
 ## Documentation
 
 | Document | Description |
 |----------|-------------|
-| [CLAUDE.md](./CLAUDE.md) | Main project instructions |
+| [CLAUDE.md](./CLAUDE.md) | Project instructions for Claude Code |
+| [ARCHITECTURE.md](./docs/ARCHITECTURE.md) | System architecture and plugin reference |
+| [COMMANDS-CHEATSHEET.md](./docs/COMMANDS-CHEATSHEET.md) | All commands quick reference |
+| [CONFIGURATION.md](./docs/CONFIGURATION.md) | Centralized setup guide |
+| [DEBUGGING-CHECKLIST.md](./docs/DEBUGGING-CHECKLIST.md) | Systematic troubleshooting guide |
+| [UPDATING.md](./docs/UPDATING.md) | Update guide for the marketplace |
+| [MIGRATION-v9.md](./docs/MIGRATION-v9.md) | v8.x to v9.0.0 migration guide |
 | [CANONICAL-PATHS.md](./docs/CANONICAL-PATHS.md) | Authoritative path reference |
-| [projman/CONFIGURATION.md](./plugins/projman/CONFIGURATION.md) | Projman setup guide |
+| [CHANGELOG.md](./CHANGELOG.md) | Version history |
+
+## Validation
+
+```bash
+./scripts/validate-marketplace.sh    # Marketplace compliance (manifests, domains, paths)
+./scripts/verify-hooks.sh            # Hook inventory (4 PreToolUse + 1 UserPromptSubmit)
+```
 
 ## License
 
@@ -216,5 +236,4 @@ MIT License
 
 ## Support
 
-- **Issues**: Contact repository maintainer
-- **Repository**: `ssh://git@hotserv.tailc9b278.ts.net:2222/personal-projects/support-claude-mktplace.git`
+- **Repository**: https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git

docs/ARCHITECTURE.md

@@ -0,0 +1,184 @@
+# Architecture — Leo Claude Marketplace v9.1.0
+
+## Overview
+
+Plugin marketplace for Claude Code. 20 plugins across 5 domains, 5 shared MCP servers,
+4 PreToolUse safety hooks + 1 UserPromptSubmit quality hook.
+
+## System Architecture
+
+### Plugin Domains
+
+| Domain | Purpose | Plugins |
+|--------|---------|---------|
+| core | Development workflow | projman, git-flow, pr-review, code-sentinel, doc-guardian, clarity-assist, contract-validator, claude-config-maintainer, project-hygiene |
+| data | Data engineering | data-platform, viz-platform, data-seed |
+| saas | SaaS development | saas-api-platform, saas-db-migrate, saas-react-platform, saas-test-pilot |
+| ops | Operations | cmdb-assistant, ops-release-manager, ops-deploy-pipeline |
+| debug | Diagnostics | debug-mcp |
+
+### MCP Servers (Shared at Root)
+
+| Server | Plugins Using It | External System |
+|--------|-------------------|-----------------|
+| gitea | projman, pr-review | Gitea (issues, PRs, wiki) — uses published `gitea-mcp` package |
+| netbox | cmdb-assistant | NetBox (DCIM, IPAM) |
+| data-platform | data-platform | PostgreSQL, dbt |
+| viz-platform | viz-platform | DMC registry |
+| contract-validator | contract-validator | (internal validation) |
+
+### Hook Architecture
+
+| Plugin | Event | Trigger | Script |
+|--------|-------|---------|--------|
+| code-sentinel | PreToolUse | Write\|Edit\|MultiEdit | security-check.sh |
+| git-flow | PreToolUse | Bash (branch naming) | branch-check.sh |
+| git-flow | PreToolUse | Bash (git commit) | commit-msg-check.sh |
+| cmdb-assistant | PreToolUse | MCP create/update | validate-input.sh |
+| clarity-assist | UserPromptSubmit | All prompts | vagueness-check.sh |
+
+No other hook types permitted. All workflow automation is via explicit commands.
+
+### Agent Model (projman)
+
+| Agent | Model | Permission Mode | Role |
+|-------|-------|-----------------|------|
+| Planner | opus | default | Sprint planning, architecture analysis, issue creation |
+| Orchestrator | sonnet | acceptEdits | Sprint execution, parallel batching, lesson capture |
+| Executor | sonnet | bypassPermissions | Code implementation, branch management |
+| Code Reviewer | opus | default | Pre-close quality review, security, tests |
+
+### Config Hierarchy
+
+| Level | Location | Contains |
+|-------|----------|----------|
+| System | ~/.config/claude/{service}.env | Credentials |
+| Project | .env in project root | Repo-specific config |
+
+### Branch Security
+
+| Pattern | Access |
+|---------|--------|
+| development, feat/*, fix/* | Full |
+| staging, stage/* | Read-only code, can create issues |
+| main, master, prod/* | READ-ONLY. Emergency only. |
+
+### Launch Profiles
+
+| Profile | Plugins |
+|---------|---------|
+| sprint | projman, git-flow, pr-review, code-sentinel, doc-guardian, clarity-assist |
+| data | data-platform, viz-platform, data-seed |
+| saas | saas-api-platform, saas-react-platform, saas-db-migrate, saas-test-pilot |
+| ops | cmdb-assistant, ops-release-manager, ops-deploy-pipeline |
+| review | pr-review, code-sentinel |
+| debug | debug-mcp |
+| full | all plugins |
+
+---
+
+## Plugin Reference
+
+### Core Domain
+
+#### projman (v9.0.1)
+Sprint planning and project management with Gitea integration.
+- **Commands:** /sprint (plan|start|status|close|review|test), /project (initiation|plan|status|close), /adr (create|list|update|supersede), /rfc (create|list|review|approve|reject), /labels sync, /projman setup
+- **Agents:** planner, orchestrator, executor, code-reviewer
+- **MCP:** gitea
+
+#### git-flow (v9.0.1)
+Git workflow automation with smart commits and branch management.
+- **Commands:** /gitflow (commit|branch-start|branch-cleanup|status|config)
+- **Commit flags:** --push, --merge, --sync
+- **Agents:** git-assistant
+- **Hooks:** PreToolUse (branch-check.sh, commit-msg-check.sh)
+
+#### pr-review (v9.0.1)
+Multi-agent PR review with confidence scoring.
+- **Commands:** /pr (review|summary|findings|diff|setup|init|sync)
+- **Agents:** coordinator, security-reviewer, performance-analyst, maintainability-auditor, test-validator
+- **MCP:** gitea
+
+#### code-sentinel (v9.0.1)
+Security scanning and code refactoring.
+- **Commands:** /sentinel (scan|refactor|refactor-dry)
+- **Agents:** security-reviewer, refactor-advisor
+- **Hooks:** PreToolUse (security-check.sh)
+
+#### doc-guardian (v9.0.1)
+Documentation drift detection and synchronization.
+- **Commands:** /doc (audit|sync|changelog-gen|coverage|stale-docs)
+- **Agents:** doc-analyzer
+
+#### clarity-assist (v9.0.1)
+Prompt optimization with ND-friendly accommodations.
+- **Commands:** /clarity (clarify|quick-clarify)
+- **Agents:** clarity-coach
+- **Hooks:** UserPromptSubmit (vagueness-check.sh)
+
+#### contract-validator (v9.0.1)
+Cross-plugin compatibility validation.
+- **Commands:** /cv (validate|check-agent|list-interfaces|dependency-graph|setup|status)
+- **Agents:** full-validation, agent-check
+- **MCP:** contract-validator
+
+#### claude-config-maintainer (v9.0.1)
+CLAUDE.md and settings optimization.
+- **Commands:** /claude-config (analyze|optimize|init|diff|lint|audit-settings|optimize-settings|permissions-map)
+- **Agents:** maintainer
+
+#### project-hygiene (v9.0.1)
+Manual project file cleanup checks.
+- **Commands:** /hygiene check (--fix flag for auto-fix)
+
+### Data Domain
+
+#### data-platform (v9.0.1)
+pandas, PostgreSQL, and dbt integration.
+- **Commands:** /data (ingest|profile|schema|explain|lineage|lineage-viz|run|dbt-test|quality|review|gate|setup)
+- **Agents:** data-advisor, data-analysis, data-ingestion
+- **MCP:** data-platform
+
+#### viz-platform (v9.0.1)
+DMC validation, Plotly charts, and theming.
+- **Commands:** /viz (setup|chart|chart-export|dashboard|theme|theme-new|theme-css|component|accessibility-check|breakpoints|design-review|design-gate)
+- **Agents:** design-reviewer, layout-builder, component-check, theme-setup
+- **MCP:** viz-platform
+
+#### data-seed (v0.1.0)
+Test data generation and database seeding. *Scaffold — not yet implemented.*
+
+### SaaS Domain
+
+#### saas-api-platform (v0.1.0)
+REST/GraphQL API scaffolding for FastAPI and Express. *Scaffold.*
+
+#### saas-db-migrate (v0.1.0)
+Database migration management for Alembic, Prisma, raw SQL. *Scaffold.*
+
+#### saas-react-platform (v0.1.0)
+React frontend toolkit for Next.js and Vite. *Scaffold.*
+
+#### saas-test-pilot (v0.1.0)
+Test automation for pytest, Jest, Vitest, Playwright. *Scaffold.*
+
+### Ops Domain
+
+#### cmdb-assistant (v9.0.1)
+NetBox CMDB integration for infrastructure management.
+- **Commands:** /cmdb (search|device|ip|site|audit|register|sync|topology|change-audit|ip-conflicts|setup)
+- **Agents:** cmdb-assistant
+- **MCP:** netbox
+- **Hooks:** PreToolUse (validate-input.sh)
+
+#### ops-release-manager (v0.1.0)
+Release management with SemVer and changelog automation. *Scaffold.*
+
+#### ops-deploy-pipeline (v0.1.0)
+Deployment pipeline for Docker Compose and systemd. *Scaffold.*
+
+### Debug Domain
+
+#### debug-mcp (v0.1.0)
+MCP server debugging and diagnostics. *Scaffold.*

docs/CANONICAL-PATHS.md

@@ -2,51 +2,207 @@
 
 **This file defines ALL valid paths in this repository. No exceptions. No inference. No assumptions.**
 
-Last Updated: 2025-12-15
+Last Updated: 2026-02-07 (v9.1.0)
 
 ---
 
 ## Repository Root Structure
 
 ```
-support-claude-mktplace/
+leo-claude-mktplace/
 ├── .claude/                    # Claude Code local settings
-├── .claude-plugin/             # Marketplace manifest (claude-code-marketplace)
-│   └── marketplace.json
+├── .claude-plugin/             # Marketplace manifest
+│   ├── marketplace.json
+│   ├── marketplace-lean.json   # Lean profile (6 core plugins)
+│   └── marketplace-full.json   # Full profile (all plugins)
+├── .mcp-lean.json              # Lean profile MCP config (gitea only)
+├── .mcp-full.json              # Full profile MCP config (all servers)
 ├── .scratch/                   # Transient work (auto-cleaned)
 ├── docs/                       # All documentation
-│   ├── architecture/           # Draw.io diagrams and specs
-│   ├── references/             # Reference specifications
-│   └── workflows/              # Workflow documentation
-├── hooks/                      # Shared hooks (if any)
-├── plugins/                    # ALL plugins with bundled MCP servers
-│   ├── projman/
+│   ├── ARCHITECTURE.md         # System architecture and plugin reference
+│   ├── CANONICAL-PATHS.md      # This file - single source of truth
+│   ├── COMMANDS-CHEATSHEET.md  # All commands quick reference
+│   ├── CONFIGURATION.md        # Centralized configuration guide
+│   ├── DEBUGGING-CHECKLIST.md  # Systematic troubleshooting guide
+│   ├── MIGRATION-v9.md         # v8.x → v9.0.0 migration guide
+│   └── UPDATING.md             # Update guide
+├── mcp-servers/                # SHARED MCP servers (v3.0.0+)
+│   ├── gitea/                  # Gitea MCP server
+│   │   ├── mcp_server/
+│   │   │   ├── server.py
+│   │   │   ├── gitea_client.py
+│   │   │   ├── config.py
+│   │   │   └── tools/
+│   │   │       ├── issues.py
+│   │   │       ├── labels.py
+│   │   │       ├── wiki.py
+│   │   │       ├── milestones.py
+│   │   │       ├── dependencies.py
+│   │   │       └── pull_requests.py  # NEW in v3.0.0
+│   │   ├── requirements.txt
+│   │   └── .venv/
+│   ├── netbox/                 # NetBox MCP server
+│   │   ├── mcp_server/
+│   │   ├── requirements.txt
+│   │   └── .venv/
+│   ├── data-platform/          # Data engineering MCP (NEW v4.0.0)
+│   │   ├── mcp_server/
+│   │   │   ├── server.py
+│   │   │   ├── pandas_tools.py
+│   │   │   ├── postgres_tools.py
+│   │   │   └── dbt_tools.py
+│   │   ├── requirements.txt
+│   │   └── .venv/
+│   ├── contract-validator/     # Contract validation MCP (NEW v5.0.0)
+│   │   ├── mcp_server/
+│   │   │   ├── server.py
+│   │   │   ├── parse_tools.py
+│   │   │   ├── validation_tools.py
+│   │   │   └── report_tools.py
+│   │   ├── tests/
+│   │   ├── requirements.txt
+│   │   └── .venv/
+│   └── viz-platform/           # Visualization MCP (NEW v4.1.0)
+│       ├── mcp_server/
+│       │   ├── server.py
+│       │   ├── config.py
+│       │   ├── component_registry.py
+│       │   ├── dmc_tools.py
+│       │   ├── chart_tools.py
+│       │   ├── layout_tools.py
+│       │   ├── theme_tools.py
+│       │   ├── theme_store.py
+│       │   └── page_tools.py
+│       ├── registry/           # DMC component JSON registries
+│       ├── tests/              # 94 tests
+│       ├── requirements.txt
+│       └── .venv/
+├── plugins/                    # ALL plugins
+│   ├── projman/                # Sprint management
 │   │   ├── .claude-plugin/
-│   │   ├── mcp-servers/        # MCP servers bundled IN plugin
-│   │   │   └── gitea/          # Gitea + Wiki tools
 │   │   ├── commands/
 │   │   ├── agents/
 │   │   ├── skills/
-│   │   └── claude-md-integration.md  # CLAUDE.md integration snippet
-│   ├── projman-pmo/
-│   ├── project-hygiene/
-│   ├── cmdb-assistant/
+│   │   └── claude-md-integration.md
+│   ├── doc-guardian/           # Documentation drift detection
 │   │   ├── .claude-plugin/
-│   │   ├── mcp-servers/        # MCP servers bundled IN plugin
-│   │   │   └── netbox/
 │   │   ├── commands/
 │   │   ├── agents/
-│   │   └── claude-md-integration.md  # CLAUDE.md integration snippet
+│   │   ├── skills/
+│   │   └── claude-md-integration.md
+│   ├── code-sentinel/          # Security scanning & refactoring
+│   │   ├── .claude-plugin/
+│   │   ├── hooks/
+│   │   ├── commands/
+│   │   ├── agents/
+│   │   ├── skills/
+│   │   └── claude-md-integration.md
+│   ├── cmdb-assistant/         # NetBox CMDB integration
+│   │   ├── .claude-plugin/
+│   │   ├── commands/
+│   │   ├── agents/
+│   │   └── claude-md-integration.md
 │   ├── claude-config-maintainer/
 │   │   ├── .claude-plugin/
 │   │   ├── commands/
 │   │   ├── agents/
-│   │   └── claude-md-integration.md  # CLAUDE.md integration snippet
-│   └── project-hygiene/
+│   │   └── claude-md-integration.md
+│   ├── project-hygiene/
+│   │   ├── .claude-plugin/
+│   │   ├── commands/
+│   │   └── claude-md-integration.md
+│   ├── clarity-assist/
+│   │   ├── .claude-plugin/
+│   │   ├── commands/
+│   │   ├── agents/
+│   │   ├── skills/
+│   │   └── claude-md-integration.md
+│   ├── git-flow/
+│   │   ├── .claude-plugin/
+│   │   ├── commands/
+│   │   ├── agents/
+│   │   ├── skills/
+│   │   └── claude-md-integration.md
+│   ├── pr-review/
+│   │   ├── .claude-plugin/
+│   │   ├── commands/
+│   │   ├── agents/
+│   │   ├── skills/
+│   │   └── claude-md-integration.md
+│   ├── data-platform/
+│   │   ├── .claude-plugin/
+│   │   ├── commands/
+│   │   ├── agents/
+│   │   └── claude-md-integration.md
+│   ├── contract-validator/
+│   │   ├── .claude-plugin/
+│   │   ├── commands/
+│   │   ├── agents/
+│   │   └── claude-md-integration.md
+│   ├── viz-platform/
+│   │   ├── .claude-plugin/
+│   │   ├── commands/
+│   │   ├── agents/
+│   │   └── claude-md-integration.md
+│   ├── saas-api-platform/       # REST/GraphQL API scaffolding (scaffold)
+│   │   ├── .claude-plugin/
+│   │   ├── commands/
+│   │   ├── agents/
+│   │   ├── skills/
+│   │   └── claude-md-integration.md
+│   ├── saas-db-migrate/         # Database migration management (scaffold)
+│   │   ├── .claude-plugin/
+│   │   ├── commands/
+│   │   ├── agents/
+│   │   ├── skills/
+│   │   └── claude-md-integration.md
+│   ├── saas-react-platform/     # React frontend toolkit (scaffold)
+│   │   ├── .claude-plugin/
+│   │   ├── commands/
+│   │   ├── agents/
+│   │   ├── skills/
+│   │   └── claude-md-integration.md
+│   ├── saas-test-pilot/         # Test automation (scaffold)
+│   │   ├── .claude-plugin/
+│   │   ├── commands/
+│   │   ├── agents/
+│   │   ├── skills/
+│   │   └── claude-md-integration.md
+│   ├── data-seed/               # Test data generation (scaffold)
+│   │   ├── .claude-plugin/
+│   │   ├── commands/
+│   │   ├── agents/
+│   │   ├── skills/
+│   │   └── claude-md-integration.md
+│   ├── ops-release-manager/     # Release management (scaffold)
+│   │   ├── .claude-plugin/
+│   │   ├── commands/
+│   │   ├── agents/
+│   │   ├── skills/
+│   │   └── claude-md-integration.md
+│   ├── ops-deploy-pipeline/     # Deployment pipeline (scaffold)
+│   │   ├── .claude-plugin/
+│   │   ├── commands/
+│   │   ├── agents/
+│   │   ├── skills/
+│   │   └── claude-md-integration.md
+│   └── debug-mcp/               # MCP debugging toolkit (scaffold)
 │       ├── .claude-plugin/
-│       ├── hooks/
-│       └── claude-md-integration.md  # CLAUDE.md integration snippet
+│       ├── commands/
+│       ├── agents/
+│       ├── skills/
+│       └── claude-md-integration.md
 ├── scripts/                    # Setup and maintenance scripts
+│   ├── setup.sh                # Initial setup (create venvs, config templates)
+│   ├── post-update.sh          # Post-update (clear cache, show changelog)
+│   ├── setup-venvs.sh          # Setup MCP server venvs (create only, never delete)
+│   ├── validate-marketplace.sh # Marketplace compliance validation
+│   ├── verify-hooks.sh         # Verify all hooks use correct event types
+│   ├── release.sh              # Release automation with version bumping
+│   ├── claude-launch.sh        # Task-specific launcher with profile selection
+│   ├── install-plugin.sh       # Install plugin to consumer project
+│   ├── list-installed.sh       # Show installed plugins in a project
+│   └── uninstall-plugin.sh     # Remove plugin from consumer project
 ├── CLAUDE.md
 ├── README.md
 ├── LICENSE
@@ -58,42 +214,103 @@ support-claude-mktplace/
 
 ## Path Patterns (MANDATORY)
 
+### Phase 1a Paths (v8.1.0)
+
+New files added in v8.1.0:
+
+```
+plugins/projman/commands/project.md
+plugins/projman/commands/project-initiation.md
+plugins/projman/commands/project-plan.md
+plugins/projman/commands/project-status.md
+plugins/projman/commands/project-close.md
+plugins/projman/commands/adr.md
+plugins/projman/commands/adr-create.md
+plugins/projman/commands/adr-list.md
+plugins/projman/commands/adr-update.md
+plugins/projman/commands/adr-supersede.md
+plugins/projman/skills/source-analysis.md
+plugins/projman/skills/project-charter.md
+plugins/projman/skills/adr-conventions.md
+plugins/projman/skills/epic-conventions.md
+plugins/projman/skills/wbs.md
+plugins/projman/skills/risk-register.md
+plugins/projman/skills/sprint-roadmap.md
+plugins/projman/skills/wiki-conventions.md
+plugins/project-hygiene/commands/hygiene-check.md
+plugins/contract-validator/commands/cv-status.md
+```
+
 ### Plugin Paths
 
 | Context | Pattern | Example |
 |---------|---------|---------|
 | Plugin location | `plugins/{plugin-name}/` | `plugins/projman/` |
 | Plugin manifest | `plugins/{plugin-name}/.claude-plugin/plugin.json` | `plugins/projman/.claude-plugin/plugin.json` |
+| Plugin MCP mapping (optional) | `plugins/{plugin-name}/.claude-plugin/metadata.json` | `plugins/projman/.claude-plugin/metadata.json` |
 | Plugin commands | `plugins/{plugin-name}/commands/` | `plugins/projman/commands/` |
 | Plugin agents | `plugins/{plugin-name}/agents/` | `plugins/projman/agents/` |
-| Plugin .mcp.json | `plugins/{plugin-name}/.mcp.json` | `plugins/projman/.mcp.json` |
+| Plugin skills | `plugins/{plugin-name}/skills/` | `plugins/projman/skills/` |
 | Plugin integration snippet | `plugins/{plugin-name}/claude-md-integration.md` | `plugins/projman/claude-md-integration.md` |
 
-### MCP Server Paths (Bundled in Plugins)
+### MCP Server Paths
 
-MCP servers are now **bundled inside each plugin** to ensure they work when plugins are cached.
+MCP servers are **shared at repository root** and configured in `.mcp.json`.
 
 | Context | Pattern | Example |
 |---------|---------|---------|
-| MCP server location | `plugins/{plugin}/mcp-servers/{server}/` | `plugins/projman/mcp-servers/gitea/` |
-| MCP server code | `plugins/{plugin}/mcp-servers/{server}/mcp_server/` | `plugins/projman/mcp-servers/gitea/mcp_server/` |
-| MCP venv | `plugins/{plugin}/mcp-servers/{server}/.venv/` | `plugins/projman/mcp-servers/gitea/.venv/` |
+| MCP configuration | `.mcp.json` | `.mcp.json` (at repo root) |
+| Shared MCP server | `mcp-servers/{server}/` | `mcp-servers/gitea/` |
+| MCP server code | `mcp-servers/{server}/mcp_server/` | `mcp-servers/netbox/mcp_server/` |
+| MCP venv (local) | `mcp-servers/{server}/.venv/` | `mcp-servers/gitea/.venv/` |
 
-### Relative Path Patterns (CRITICAL)
+**Note:** `mcp-servers/gitea/` is a thin wrapper — source code is in the published `gitea-mcp` package (Gitea PyPI). Other MCP servers still have local source code.
 
-| From | To | Pattern |
-|------|----|---------|
-| Plugin .mcp.json | Bundled MCP server | `${CLAUDE_PLUGIN_ROOT}/mcp-servers/{server}` |
-| marketplace.json | Plugin | `./plugins/{plugin-name}` |
+**Note:** Plugins do NOT have their own `mcp-servers/` directories. All MCP servers are shared at root and configured via `.mcp.json`.
+
+### MCP Venv Paths - CRITICAL
+
+**Venvs live in a CACHE directory that SURVIVES marketplace updates.**
+
+When checking for venvs, ALWAYS check in this order:
+
+| Priority | Path | Survives Updates? |
+|----------|------|-------------------|
+| 1 (CHECK FIRST) | `~/.cache/claude-mcp-venvs/leo-claude-mktplace/{server}/.venv/` | YES |
+| 2 (fallback) | `{marketplace}/mcp-servers/{server}/.venv/` | NO |
+
+**Why cache first?**
+- Marketplace directory gets WIPED on every update/reinstall
+- Cache directory SURVIVES updates
+- False "venv missing" errors waste hours of debugging
+
+**Pattern for hooks checking venvs:**
+```bash
+CACHE_VENV="$HOME/.cache/claude-mcp-venvs/leo-claude-mktplace/{server}/.venv/bin/python"
+LOCAL_VENV="$MARKETPLACE_ROOT/mcp-servers/{server}/.venv/bin/python"
+
+if [[ -f "$CACHE_VENV" ]]; then
+    VENV_PATH="$CACHE_VENV"
+elif [[ -f "$LOCAL_VENV" ]]; then
+    VENV_PATH="$LOCAL_VENV"
+else
+    echo "venv missing"
+fi
+```
+
+**See lesson learned:** [Startup Hooks Must Check Venv Cache Path First](https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/wiki/lessons/patterns/startup-hooks-must-check-venv-cache-path-first)
 
 ### Documentation Paths
 
 | Type | Location |
 |------|----------|
-| Reference specs | `docs/references/` |
-| Architecture diagrams | `docs/architecture/` |
-| Workflow docs | `docs/workflows/` |
+| Architecture & plugin reference | `docs/ARCHITECTURE.md` |
 | This file | `docs/CANONICAL-PATHS.md` |
+| Update guide | `docs/UPDATING.md` |
+| Configuration guide | `docs/CONFIGURATION.md` |
+| Commands cheat sheet | `docs/COMMANDS-CHEATSHEET.md` |
+| Debugging checklist | `docs/DEBUGGING-CHECKLIST.md` |
+| Migration guide (v8→v9) | `docs/MIGRATION-v9.md` |
 
 ---
 
@@ -113,13 +330,10 @@ MCP servers are now **bundled inside each plugin** to ensure they work when plug
 
 ### Relative Path Calculation
 
-From `plugins/projman/.mcp.json` to bundled `mcp-servers/gitea/`:
+From `.mcp.json` (at root) to `mcp-servers/gitea/`:
 ```
-plugins/projman/.mcp.json
-  → MCP servers are IN the plugin at mcp-servers/
-
-Result: mcp-servers/gitea/
-With variable: ${CLAUDE_PLUGIN_ROOT}/mcp-servers/gitea/
+.mcp.json (at repository root)
+  → Uses absolute installed path: ~/.claude/plugins/marketplaces/.../mcp-servers/gitea/run.sh
 ```
 
 From `.claude-plugin/marketplace.json` to `plugins/projman/`:
@@ -138,18 +352,78 @@ Result: ./plugins/projman
 | Wrong | Why | Correct |
 |-------|-----|---------|
 | `projman/` at root | Plugins go in `plugins/` | `plugins/projman/` |
-| `mcp-servers/` at root | MCP servers are bundled in plugins | `plugins/{plugin}/mcp-servers/` |
-| `../../mcp-servers/` from plugin | Old pattern, doesn't work with caching | `${CLAUDE_PLUGIN_ROOT}/mcp-servers/` |
-| `./../../../plugins/projman` in marketplace | Wrong (old nested structure) | `./plugins/projman` |
+| `mcp-servers/` inside plugins | MCP servers are shared at root | Use root `mcp-servers/` |
+| Plugin-level `.mcp.json` | MCP config is at root | Use root `.mcp.json` |
+| Hardcoding absolute paths in source | Breaks portability | Use relative paths or `${CLAUDE_PLUGIN_ROOT}` |
 
 ---
 
 ## Architecture Note
 
-MCP servers are bundled inside each plugin (not shared at root) because:
-- Claude Code caches only the plugin directory when installed
-- Relative paths to parent directories break in the cache
-- Each plugin must be self-contained to work properly
+MCP servers are **shared at repository root** and configured in a single `.mcp.json` file.
+
+**Benefits:**
+- Single source of truth for each MCP server
+- Updates apply to all plugins automatically
+- No duplication - clean plugin structure
+- Simple configuration in one place
+
+**Configuration:**
+All MCP servers are defined in `.mcp.json` at repository root:
+```json
+{
+  "mcpServers": {
+    "gitea": { "command": ".../mcp-servers/gitea/run.sh" },
+    "netbox": { "command": ".../mcp-servers/netbox/run.sh" },
+    "data-platform": { "command": ".../mcp-servers/data-platform/run.sh" },
+    "viz-platform": { "command": ".../mcp-servers/viz-platform/run.sh" },
+    "contract-validator": { "command": ".../mcp-servers/contract-validator/run.sh" }
+  }
+}
+```
+
+---
+
+## Domain Metadata
+
+### Domain Field Location
+
+Domain metadata is stored in `metadata.json` (v9.1.2+, moved from plugin.json/marketplace.json for Claude Code schema compliance):
+
+| Location | Field | Example |
+|----------|-------|---------|
+| `plugins/{name}/.claude-plugin/metadata.json` | `"domain": "core"` | `plugins/projman/.claude-plugin/metadata.json` |
+
+### Allowed Domain Values
+
+| Domain | Purpose | Existing Plugins |
+|--------|---------|-----------------|
+| `core` | Development workflow plugins | projman, git-flow, pr-review, code-sentinel, doc-guardian, clarity-assist, contract-validator, claude-config-maintainer, project-hygiene |
+| `data` | Data engineering and visualization | data-platform, viz-platform, data-seed |
+| `ops` | Operations and infrastructure | cmdb-assistant, ops-release-manager, ops-deploy-pipeline |
+| `saas` | SaaS application development | saas-api-platform, saas-db-migrate, saas-react-platform, saas-test-pilot |
+| `debug` | Debugging and diagnostics | debug-mcp |
+
+### Plugin Naming Convention
+
+- **Core plugins:** No prefix (existing names never change)
+- **New plugins:** Domain prefix: `saas-*`, `ops-*`, `data-*`, `debug-*`
+- Domain is always in metadata — prefix is a naming convention, not a requirement
+
+### Domain Query Examples
+
+```bash
+# List all plugins in a domain
+for p in plugins/*; do
+  d=$(jq -r '.domain // empty' "$p/.claude-plugin/metadata.json" 2>/dev/null)
+  [[ "$d" == "saas" ]] && basename "$p"
+done
+
+# Count plugins per domain
+for p in plugins/*; do
+  jq -r '.domain // empty' "$p/.claude-plugin/metadata.json" 2>/dev/null
+done | sort | uniq -c | sort -rn
+```
 
 ---
 
@@ -157,6 +431,19 @@ MCP servers are bundled inside each plugin (not shared at root) because:
 
 | Date | Change | By |
 |------|--------|-----|
-| 2026-01-19 | Added claude-md-integration.md path pattern for plugin integration snippets | Claude Code |
-| 2025-12-15 | Restructured: MCP servers now bundled in plugins | Claude Code |
+| 2026-02-07 | v9.1.2: Moved domain field from plugin.json/marketplace.json to metadata.json for Claude Code schema compliance | Claude Code |
+| 2026-02-07 | v9.1.0: Removed deleted dirs (architecture/, prompts/, project-lessons-learned/), added Phase 3 plugins, added ARCHITECTURE.md, MIGRATION-v9.md, updated Domain table, removed stale hooks/ dirs | Claude Code |
+| 2026-02-06 | v8.0.0: Added domain metadata section, Phase 1a paths, future plugin paths | Claude Code |
+| 2026-02-04 | v7.1.0: Added profile configs, prompts/, project-lessons-learned/, metadata.json, deprecated switch-profile.sh | Claude Code |
+| 2026-01-30 | v5.5.0: Removed plugin-level mcp-servers symlinks - all MCP config now in root .mcp.json | Claude Code |
+| 2026-01-26 | v5.0.0: Added contract-validator plugin and MCP server | Claude Code |
+| 2026-01-26 | v4.1.0: Added viz-platform plugin and MCP server | Claude Code |
+| 2026-01-25 | v4.0.0: Added data-platform plugin and MCP server | Claude Code |
+| 2026-01-20 | v3.0.0: MCP servers moved to root with symlinks | Claude Code |
+| 2026-01-20 | v3.0.0: Added clarity-assist, git-flow, pr-review plugins | Claude Code |
+| 2026-01-20 | v3.0.0: Added docs/CONFIGURATION.md | Claude Code |
+| 2026-01-20 | v3.0.0: Renamed marketplace to leo-claude-mktplace | Claude Code |
+| 2026-01-20 | Removed docs/references/ (obsolete planning docs) | Claude Code |
+| 2026-01-19 | Added claude-md-integration.md path pattern | Claude Code |
+| 2025-12-15 | Restructured: MCP servers bundled in plugins | Claude Code |
 | 2025-12-12 | Initial creation | Claude Code |

docs/COMMANDS-CHEATSHEET.md

@@ -0,0 +1,323 @@
+# Plugin Commands Cheat Sheet
+
+Quick reference for all commands in the Leo Claude Marketplace (v9.0.0+).
+
+All commands follow the `/<noun> <action>` sub-command pattern.
+
+## Invocation
+
+Commands can be invoked in two ways:
+
+1. **Via dispatch file:** `/doc audit` (routes through dispatch file to invoke `/doc-guardian:doc-audit`)
+2. **Direct plugin-prefixed:** `/doc-guardian:doc-audit` (invokes command directly)
+
+Both methods work identically. The dispatch file provides a user-friendly interface with `$ARGUMENTS` parsing, while the direct format bypasses the dispatcher.
+
+If dispatch routing fails, use the direct plugin-prefixed format: `/<plugin-name>:<command-name>`.
+
+**Examples:**
+- `/sprint plan` → routes to `/projman:sprint-plan`
+- `/doc audit` → routes to `/doc-guardian:doc-audit`
+- `/pr review` → routes to `/pr-review:pr-review`
+
+---
+
+## Command Reference Table
+
+| Plugin | Command | Auto | Manual | Description |
+|--------|---------|:----:|:------:|-------------|
+| **projman** | `/sprint plan` | | X | Start sprint planning with AI-guided architecture analysis and issue creation |
+| **projman** | `/sprint start` | | X | Begin sprint execution with dependency analysis and parallel task coordination (requires approval or `--force`) |
+| **projman** | `/sprint status` | | X | Check current sprint progress (add `--diagram` for Mermaid visualization) |
+| **projman** | `/sprint review` | | X | Pre-sprint-close code quality review (debug artifacts, security, error handling) |
+| **projman** | `/sprint test` | | X | Run tests (`/sprint test run`) or generate tests (`/sprint test gen <target>`) |
+| **projman** | `/sprint close` | | X | Complete sprint and capture lessons learned to Gitea Wiki |
+| **projman** | `/labels sync` | | X | Synchronize label taxonomy from Gitea |
+| **projman** | `/projman setup` | | X | Auto-detect mode or use `--full`, `--quick`, `--sync`, `--clear-cache` |
+| **projman** | `/rfc create` | | X | Create new RFC from conversation or spec |
+| **projman** | `/rfc list` | | X | List all RFCs grouped by status |
+| **projman** | `/rfc review` | | X | Submit RFC for maintainer review |
+| **projman** | `/rfc approve` | | X | Approve RFC for sprint planning |
+| **projman** | `/rfc reject` | | X | Reject RFC with documented reason |
+| **projman** | `/project initiation` | | X | Discovery, source analysis, project charter |
+| **projman** | `/project plan` | | X | WBS, risk register, sprint roadmap |
+| **projman** | `/project status` | | X | Project health check across all sprints |
+| **projman** | `/project close` | | X | Final retrospective and archival |
+| **projman** | `/adr create` | | X | Create new Architecture Decision Record |
+| **projman** | `/adr list` | | X | List all ADRs with status |
+| **projman** | `/adr update` | | X | Update existing ADR |
+| **projman** | `/adr supersede` | | X | Supersede ADR with new decision |
+| **git-flow** | `/gitflow commit` | | X | Create commit with auto-generated conventional message. Flags: `--push`, `--merge`, `--sync` |
+| **git-flow** | `/gitflow branch-start` | | X | Create new feature/fix/chore branch with naming conventions |
+| **git-flow** | `/gitflow branch-cleanup` | | X | Remove merged branches locally and optionally on remote |
+| **git-flow** | `/gitflow status` | | X | Enhanced git status with recommendations |
+| **git-flow** | `/gitflow config` | | X | Configure git-flow settings for the project |
+| **pr-review** | `/pr setup` | | X | Setup wizard for pr-review (shares Gitea MCP with projman) |
+| **pr-review** | `/pr init` | | X | Quick project setup for PR reviews |
+| **pr-review** | `/pr sync` | | X | Sync config with git remote after repo move/rename |
+| **pr-review** | `/pr review` | | X | Full multi-agent PR review with confidence scoring |
+| **pr-review** | `/pr summary` | | X | Quick summary of PR changes |
+| **pr-review** | `/pr findings` | | X | List and filter review findings by category/severity |
+| **pr-review** | `/pr diff` | | X | Formatted diff with inline review comments and annotations |
+| **clarity-assist** | `/clarity clarify` | | X | Full 4-D prompt optimization with ND accommodations |
+| **clarity-assist** | `/clarity quick-clarify` | | X | Rapid single-pass clarification for simple requests |
+| **doc-guardian** | `/doc audit` | | X | Full documentation audit - scans for doc drift |
+| **doc-guardian** | `/doc sync` | | X | Synchronize pending documentation updates |
+| **doc-guardian** | `/doc changelog-gen` | | X | Generate changelog from conventional commits |
+| **doc-guardian** | `/doc coverage` | | X | Documentation coverage metrics by function/class |
+| **doc-guardian** | `/doc stale-docs` | | X | Flag documentation behind code changes |
+| **code-sentinel** | `/sentinel scan` | | X | Full security audit (SQL injection, XSS, secrets, etc.) |
+| **code-sentinel** | `/sentinel refactor` | | X | Apply refactoring patterns to improve code |
+| **code-sentinel** | `/sentinel refactor-dry` | | X | Preview refactoring without applying changes |
+| **code-sentinel** | *PreToolUse hook* | X | | Scans code before writing; blocks critical issues |
+| **claude-config-maintainer** | `/claude-config analyze` | | X | Analyze CLAUDE.md for optimization opportunities |
+| **claude-config-maintainer** | `/claude-config optimize` | | X | Optimize CLAUDE.md structure with preview/backup |
+| **claude-config-maintainer** | `/claude-config init` | | X | Initialize new CLAUDE.md for a project |
+| **claude-config-maintainer** | `/claude-config diff` | | X | Track CLAUDE.md changes over time with behavioral impact |
+| **claude-config-maintainer** | `/claude-config lint` | | X | Lint CLAUDE.md for anti-patterns and best practices |
+| **claude-config-maintainer** | `/claude-config audit-settings` | | X | Audit settings.local.json permissions (100-point score) |
+| **claude-config-maintainer** | `/claude-config optimize-settings` | | X | Optimize permissions (profiles, consolidation, dry-run) |
+| **claude-config-maintainer** | `/claude-config permissions-map` | | X | Visual review layer + permission coverage map |
+| **cmdb-assistant** | `/cmdb setup` | | X | Setup wizard for NetBox MCP server |
+| **cmdb-assistant** | `/cmdb search` | | X | Search NetBox for devices, IPs, sites |
+| **cmdb-assistant** | `/cmdb device` | | X | Manage network devices (create, view, update, delete) |
+| **cmdb-assistant** | `/cmdb ip` | | X | Manage IP addresses and prefixes |
+| **cmdb-assistant** | `/cmdb site` | | X | Manage sites, locations, racks, and regions |
+| **cmdb-assistant** | `/cmdb audit` | | X | Data quality analysis (VMs, devices, naming, roles) |
+| **cmdb-assistant** | `/cmdb register` | | X | Register current machine into NetBox with running apps |
+| **cmdb-assistant** | `/cmdb sync` | | X | Sync machine state with NetBox (detect drift, update) |
+| **cmdb-assistant** | `/cmdb topology` | | X | Infrastructure topology diagrams (rack, network, site views) |
+| **cmdb-assistant** | `/cmdb change-audit` | | X | NetBox audit trail queries with filtering |
+| **cmdb-assistant** | `/cmdb ip-conflicts` | | X | Detect IP conflicts and overlapping prefixes |
+| **project-hygiene** | `/hygiene check` | | X | Project file organization and cleanup check |
+| **data-platform** | `/data ingest` | | X | Load data from CSV, Parquet, JSON into DataFrame |
+| **data-platform** | `/data profile` | | X | Generate data profiling report with statistics |
+| **data-platform** | `/data schema` | | X | Explore database schemas, tables, columns |
+| **data-platform** | `/data explain` | | X | Explain query execution plan |
+| **data-platform** | `/data lineage` | | X | Show dbt model lineage and dependencies |
+| **data-platform** | `/data run` | | X | Run dbt models with validation |
+| **data-platform** | `/data lineage-viz` | | X | dbt lineage visualization as Mermaid diagrams |
+| **data-platform** | `/data dbt-test` | | X | Formatted dbt test runner with summary and failure details |
+| **data-platform** | `/data quality` | | X | DataFrame quality checks (nulls, duplicates, types, outliers) |
+| **data-platform** | `/data review` | | X | Comprehensive data integrity audits |
+| **data-platform** | `/data gate` | | X | Binary pass/fail data integrity gates |
+| **data-platform** | `/data setup` | | X | Setup wizard for data-platform MCP servers |
+| **viz-platform** | `/viz setup` | | X | Setup wizard for viz-platform MCP server |
+| **viz-platform** | `/viz chart` | | X | Create Plotly charts with theme integration |
+| **viz-platform** | `/viz chart-export` | | X | Export charts to PNG, SVG, PDF via kaleido |
+| **viz-platform** | `/viz dashboard` | | X | Create dashboard layouts with filters and grids |
+| **viz-platform** | `/viz theme` | | X | Apply existing theme to visualizations |
+| **viz-platform** | `/viz theme-new` | | X | Create new custom theme with design tokens |
+| **viz-platform** | `/viz theme-css` | | X | Export theme as CSS custom properties |
+| **viz-platform** | `/viz component` | | X | Inspect DMC component props and validation |
+| **viz-platform** | `/viz accessibility-check` | | X | Color blind validation (WCAG contrast ratios) |
+| **viz-platform** | `/viz breakpoints` | | X | Configure responsive layout breakpoints |
+| **viz-platform** | `/viz design-review` | | X | Detailed design system audits |
+| **viz-platform** | `/viz design-gate` | | X | Binary pass/fail design system validation gates |
+| **contract-validator** | `/cv validate` | | X | Full marketplace compatibility validation |
+| **contract-validator** | `/cv check-agent` | | X | Validate single agent definition |
+| **contract-validator** | `/cv list-interfaces` | | X | Show all plugin interfaces |
+| **contract-validator** | `/cv dependency-graph` | | X | Mermaid visualization of plugin dependencies |
+| **contract-validator** | `/cv setup` | | X | Setup wizard for contract-validator MCP |
+| **contract-validator** | `/cv status` | | X | Marketplace-wide health check (installation, MCP, configuration) |
+
+---
+
+## Migration from v8.x
+
+All commands were renamed in v9.0.0 to follow `/<noun> <action>` pattern. See [MIGRATION-v9.md](./MIGRATION-v9.md) for the complete old-to-new mapping.
+
+---
+
+## Plugins by Category
+
+| Category | Plugins | Primary Use |
+|----------|---------|-------------|
+| **Setup** | projman, pr-review, cmdb-assistant, data-platform, viz-platform, contract-validator | `/projman setup`, `/pr setup`, `/cmdb setup`, `/data setup`, `/viz setup`, `/cv setup` |
+| **Task Planning** | projman, clarity-assist | Sprint management, requirement clarification |
+| **Code Quality** | code-sentinel, pr-review | Security scanning, PR reviews |
+| **Documentation** | doc-guardian, claude-config-maintainer | Doc sync, CLAUDE.md maintenance |
+| **Git Operations** | git-flow | Commits, branches, workflow automation |
+| **Infrastructure** | cmdb-assistant | NetBox CMDB management |
+| **Data Engineering** | data-platform | pandas, PostgreSQL, dbt operations |
+| **Visualization** | viz-platform | DMC validation, Plotly charts, theming |
+| **Validation** | contract-validator | Cross-plugin compatibility checks |
+| **Maintenance** | project-hygiene | Manual cleanup via `/hygiene check` |
+
+---
+
+## Hook-Based Automation Summary
+
+| Plugin | Hook Event | Behavior |
+|--------|------------|----------|
+| **code-sentinel** | PreToolUse (Write/Edit/MultiEdit) | Scans code before writing; blocks critical security issues |
+| **git-flow** | PreToolUse (Bash) | Validates branch naming and commit message conventions |
+| **cmdb-assistant** | PreToolUse (MCP create/update) | Validates input data before NetBox writes |
+| **clarity-assist** | UserPromptSubmit | Detects vague prompts and suggests clarification |
+
+---
+
+## Dev Workflow Examples
+
+### Example 0: RFC-Driven Feature Development
+
+Full workflow from idea to implementation using RFCs:
+
+```
+1. /clarity clarify            # Clarify the feature idea
+2. /rfc create                 # Create RFC from clarified spec
+   ... refine RFC content ...
+3. /rfc review 0001            # Submit RFC for review
+   ... review discussion ...
+4. /rfc approve 0001           # Approve RFC for implementation
+5. /sprint plan                # Select approved RFC for sprint
+   ... implement feature ...
+6. /sprint close               # Complete sprint, RFC marked Implemented
+```
+
+### Example 1: Starting a New Feature Sprint
+
+A typical workflow for planning and executing a feature sprint:
+
+```
+1. /clarity clarify             # Clarify requirements if vague
+2. /sprint plan                 # Plan the sprint with architecture analysis
+3. /labels sync                 # Ensure labels are up-to-date
+4. /sprint start                # Begin execution with dependency ordering
+5. /gitflow branch-start feat/...  # Create feature branch
+   ... implement features ...
+6. /gitflow commit              # Commit with conventional message
+7. /sprint status --diagram     # Check progress with visualization
+8. /sprint review               # Pre-close quality review
+9. /sprint test run             # Verify test coverage
+10. /sprint close               # Capture lessons learned
+```
+
+### Example 2: Daily Development Cycle
+
+Quick daily workflow with git-flow:
+
+```
+1. /gitflow status              # Check current state
+2. /gitflow branch-start fix/...  # Start bugfix branch
+   ... make changes ...
+3. /gitflow commit              # Auto-generate commit message
+4. /gitflow commit --push       # Commit and push to remote
+5. /gitflow branch-cleanup      # Clean merged branches
+```
+
+### Example 3: Pull Request Review Workflow
+
+Reviewing a PR before merge:
+
+```
+1. /pr summary                  # Quick overview of changes
+2. /pr review                   # Full multi-agent review
+3. /pr findings                 # Filter findings by severity
+4. /sentinel scan               # Deep security audit if needed
+```
+
+### Example 4: Documentation Maintenance
+
+Keeping docs in sync:
+
+```
+1. /doc audit                   # Scan for documentation drift
+2. /doc sync                    # Apply pending updates
+3. /claude-config analyze       # Check CLAUDE.md health
+4. /claude-config optimize      # Optimize if needed
+```
+
+### Example 5: Code Refactoring Session
+
+Safe refactoring with preview:
+
+```
+1. /sentinel refactor-dry       # Preview opportunities
+2. /sentinel scan               # Baseline security check
+3. /sentinel refactor           # Apply improvements
+4. /sprint test run             # Verify nothing broke
+5. /gitflow commit              # Commit with descriptive message
+```
+
+### Example 6: Infrastructure Documentation
+
+Managing infrastructure with CMDB:
+
+```
+1. /cmdb search "server"        # Find existing devices
+2. /cmdb device view X          # Check device details
+3. /cmdb ip list                # List available IPs
+4. /cmdb site view Y            # Check site info
+```
+
+### Example 6b: Data Engineering Workflow
+
+Working with data pipelines:
+
+```
+1. /data ingest file.csv        # Load data into DataFrame
+2. /data profile                # Generate data profiling report
+3. /data schema                 # Explore database schemas
+4. /data lineage model_name     # View dbt model dependencies
+5. /data run model_name         # Execute dbt models
+6. /data explain "SELECT ..."   # Analyze query execution plan
+```
+
+### Example 7: First-Time Setup (New Machine)
+
+Setting up the marketplace for the first time:
+
+```
+1. /projman setup --full        # Full setup: MCP + system config + project
+   # → Follow prompts for Gitea URL, org
+   # → Add token manually when prompted
+   # → Confirm repository name
+2. # Restart Claude Code session
+3. /labels sync                 # Sync Gitea labels
+4. /sprint plan                 # Plan first sprint
+```
+
+### Example 8: New Project Setup (System Already Configured)
+
+Adding a new project when system config exists:
+
+```
+1. /projman setup --quick       # Quick project setup (auto-detected)
+   # → Confirms detected repo name
+   # → Creates .env
+2. /labels sync                 # Sync Gitea labels
+3. /sprint plan                 # Plan first sprint
+```
+
+---
+
+## Quick Tips
+
+- **Hooks run automatically** - code-sentinel and git-flow protect you without manual invocation
+- **Use `/gitflow commit` over `git commit`** - generates better commit messages following conventions
+- **Run `/sprint review` before `/sprint close`** - catches issues before closing the sprint
+- **Use `/clarity clarify` for vague requests** - especially helpful for complex requirements
+- **`/sentinel refactor-dry` is safe** - always preview before applying refactoring changes
+- **`/gitflow commit --push`** replaces the old `/git-commit-push` - fewer commands to remember
+
+---
+
+## MCP Server Requirements
+
+Some plugins require MCP server connectivity:
+
+| Plugin | MCP Server | Purpose |
+|--------|------------|---------|
+| projman | Gitea | Issues, PRs, wiki, labels, milestones |
+| pr-review | Gitea | PR operations and reviews |
+| cmdb-assistant | NetBox | Infrastructure CMDB |
+| data-platform | pandas, PostgreSQL, dbt | DataFrames, database queries, dbt builds |
+| viz-platform | viz-platform | DMC validation, charts, layouts, themes, pages |
+| contract-validator | contract-validator | Plugin interface parsing, compatibility validation |
+
+Ensure credentials are configured in `~/.config/claude/gitea.env`, `~/.config/claude/netbox.env`, or `~/.config/claude/postgres.env`.
+
+---
+
+*Last Updated: 2026-02-06*

docs/CONFIGURATION.md

@@ -0,0 +1,752 @@
+# Configuration Guide
+
+Centralized configuration documentation for all plugins and MCP servers in the Leo Claude Marketplace.
+
+---
+
+## Quick Start
+
+**After installing the marketplace and plugins via Claude Code:**
+
+```
+/projman setup
+```
+
+The interactive wizard auto-detects what's needed and handles everything except manually adding your API tokens.
+
+---
+
+## Setup Flow Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           FIRST TIME SETUP                                  │
+│                         (once per machine)                                  │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    ▼
+                             /projman setup --full
+                         (or /projman setup auto-detects)
+                                    │
+     ┌──────────────────────────────┼──────────────────────────────┐
+     ▼                              ▼                              ▼
+┌─────────────┐            ┌─────────────────┐            ┌─────────────────┐
+│  PHASE 1    │            │    PHASE 2      │            │    PHASE 3      │
+│  Automated  │───────────▶│    Automated    │───────────▶│   Interactive   │
+│             │            │                 │            │                 │
+│ • Check     │            │ • Find MCP path │            │ • Ask Gitea URL │
+│   Python    │            │ • Create venv   │            │ • Ask Org name  │
+│   version   │            │ • Install deps  │            │ • Create config │
+└─────────────┘            └─────────────────┘            └─────────────────┘
+                                                                   │
+                                                                   ▼
+                                                   ┌───────────────────────────┐
+                                                   │        PHASE 4            │
+                                                   │     USER ACTION           │
+                                                   │                           │
+                                                   │  Edit config file to add  │
+                                                   │  API token (for security) │
+                                                   │                           │
+                                                   │  nano ~/.config/claude/   │
+                                                   │       gitea.env           │
+                                                   └───────────────────────────┘
+                                                                   │
+                                                                   ▼
+     ┌──────────────────────────────┬──────────────────────────────┐
+     ▼                              ▼                              ▼
+┌─────────────┐            ┌─────────────────┐            ┌─────────────────┐
+│  PHASE 5    │            │    PHASE 6      │            │    PHASE 7      │
+│ Interactive │            │    Automated    │            │    Automated    │
+│             │            │                 │            │                 │
+│ • Confirm   │            │ • Create .env   │            │ • Test API      │
+│   repo name │            │ • Check         │            │ • Show summary  │
+│   from git  │            │   .gitignore    │            │ • Restart note  │
+└─────────────┘            └─────────────────┘            └─────────────────┘
+                                                                   │
+                                                                   ▼
+                                                   ┌───────────────────────────┐
+                                                   │      RESTART SESSION      │
+                                                   │                           │
+                                                   │  MCP tools available      │
+                                                   │  after restart            │
+                                                   └───────────────────────────┘
+
+
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                          NEW PROJECT SETUP                                  │
+│                        (once per project)                                   │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                    │
+                    ┌───────────────┴───────────────┐
+                    ▼                               ▼
+            /projman setup --quick                  /projman setup
+             (explicit mode)               (auto-detects mode)
+                    │                               │
+                    │                    ┌──────────┴──────────┐
+                    │                    ▼                     ▼
+                    │              "Quick setup"         "Full setup"
+                    │               (skips to              (re-runs
+                    │              project config)          everything)
+                    │                    │                     │
+                    └────────────────────┴─────────────────────┘
+                                         │
+                                         ▼
+                              ┌─────────────────────┐
+                              │   PROJECT CONFIG    │
+                              │                     │
+                              │ • Detect repo from  │
+                              │   git remote        │
+                              │ • Confirm with user │
+                              │ • Create .env       │
+                              │ • Check .gitignore  │
+                              └─────────────────────┘
+                                         │
+                                         ▼
+                                      Done!
+```
+
+---
+
+## What Runs Automatically vs User Interaction
+
+### `/projman setup --full` - Full Setup
+
+| Phase | Type | What Happens |
+|-------|------|--------------|
+| **1. Environment Check** | Automated | Verifies Python 3.10+ is installed |
+| **2. MCP Server Setup** | Automated | Finds plugin path, creates venv, installs dependencies |
+| **3. System Config Creation** | Interactive | Asks for Gitea URL and organization name |
+| **4. Token Entry** | **User Action** | User manually edits config file to add API token |
+| **5. Project Detection** | Interactive | Shows detected repo name, asks for confirmation |
+| **6. Project Config** | Automated | Creates `.env` file, checks `.gitignore` |
+| **7. Validation** | Automated | Tests API connectivity, shows summary |
+
+### `/projman setup --quick` - Quick Project Setup
+
+| Phase | Type | What Happens |
+|-------|------|--------------|
+| **1. Pre-flight Check** | Automated | Verifies system config exists |
+| **2. Project Detection** | Interactive | Shows detected repo name, asks for confirmation |
+| **3. Project Config** | Automated | Creates/updates `.env` file |
+| **4. Gitignore Check** | Interactive | Asks to add `.env` to `.gitignore` if missing |
+
+---
+
+## One Command, Three Modes
+
+| Mode | When to Use | What It Does |
+|------|-------------|--------------|
+| `/projman setup` | Any time | Auto-detects: runs full, quick, or sync as needed |
+| `/projman setup --full` | First time on a machine | Full setup: MCP server + system config + project config |
+| `/projman setup --quick` | Starting a new project | Quick setup: project config only (assumes system is ready) |
+| `/projman setup --sync` | After repo move/rename | Updates .env to match current git remote |
+
+**Auto-detection logic:**
+1. No system config → **full** mode
+2. System config exists, no project config → **quick** mode
+3. Both exist, git remote differs → **sync** mode
+4. Both exist, match → already configured, offer to reconfigure
+
+**Typical workflow:**
+1. Install plugin → run `/projman setup` (auto-runs full mode)
+2. Start new project → run `/projman setup` (auto-runs quick mode)
+3. Repository moved? → run `/projman setup` (auto-runs sync mode)
+
+---
+
+## Configuration Architecture
+
+This marketplace uses a **hybrid configuration** approach:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    SYSTEM-LEVEL (once per machine)             │
+│                    ~/.config/claude/                            │
+├─────────────────────────────────────────────────────────────────┤
+│  gitea.env     │  GITEA_API_URL, GITEA_API_TOKEN                       │
+│  netbox.env    │  NETBOX_API_URL, NETBOX_API_TOKEN                     │
+│  git-flow.env  │  GIT_WORKFLOW_STYLE, GIT_DEFAULT_BASE, etc.   │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              │ Shared across all projects
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                  PROJECT-LEVEL (once per project)              │
+│                  <project-root>/.env                            │
+├─────────────────────────────────────────────────────────────────┤
+│  GITEA_REPO              │  Repository as owner/repo format    │
+│  GIT_WORKFLOW_STYLE      │  (optional) Override system default │
+│  PR_REVIEW_*             │  (optional) PR review settings      │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Benefits:**
+- Single token per service (update once, use everywhere)
+- Easy multi-project setup (just run `/projman setup` in each project)
+- Security (tokens never committed to git, never typed into AI chat)
+- Project isolation (each project can override defaults)
+
+---
+
+## Prerequisites
+
+Before running `/projman setup`:
+
+1. **Python 3.10+** installed
+   ```bash
+   python3 --version  # Should be 3.10.0 or higher
+   ```
+
+2. **Git repository** initialized (for project setup)
+   ```bash
+   git status  # Should show initialized repository
+   ```
+
+3. **Claude Code** installed and working with the marketplace
+
+---
+
+## Setup Methods
+
+### Method 1: Interactive Wizard (Recommended)
+
+Run the setup wizard in Claude Code:
+
+```
+/projman setup
+```
+
+The wizard will guide you through each step interactively and auto-detect the appropriate mode.
+
+**Note:** After first-time setup, you'll need to restart your Claude Code session for MCP tools to become available.
+
+### Method 2: Manual Setup
+
+If you prefer to set up manually or need to troubleshoot:
+
+#### Step 1: MCP Server Setup
+
+```bash
+# Navigate to marketplace directory
+cd /path/to/leo-claude-mktplace
+
+# Set up Gitea MCP server
+cd mcp-servers/gitea
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+deactivate
+
+# (Optional) Set up NetBox MCP server
+cd ../netbox
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+deactivate
+```
+
+#### Step 2: System Configuration
+
+```bash
+mkdir -p ~/.config/claude
+
+# Gitea configuration (credentials only)
+cat > ~/.config/claude/gitea.env << 'EOF'
+GITEA_API_URL=https://gitea.example.com
+GITEA_API_TOKEN=your_token_here
+EOF
+chmod 600 ~/.config/claude/gitea.env
+```
+
+#### Step 3: Project Configuration
+
+In each project root:
+
+```bash
+cat > .env << 'EOF'
+GITEA_REPO=your-organization/your-repo-name
+EOF
+```
+
+Add `.env` to `.gitignore` if not already there.
+
+### Method 3: Automation Script (CI/Scripting)
+
+For automated setups or CI environments:
+
+```bash
+cd /path/to/leo-claude-mktplace
+./scripts/setup.sh
+```
+
+This script is useful for CI/CD pipelines and bulk provisioning.
+
+---
+
+## Configuration Reference
+
+### System-Level Files
+
+Located in `~/.config/claude/`:
+
+| File | Required By | Purpose |
+|------|-------------|---------|
+| `gitea.env` | projman, pr-review | Gitea API credentials |
+| `netbox.env` | cmdb-assistant | NetBox API credentials |
+| `git-flow.env` | git-flow | Default git workflow settings |
+
+### Gitea Configuration
+
+```bash
+# ~/.config/claude/gitea.env
+GITEA_API_URL=https://gitea.example.com/api/v1
+GITEA_API_TOKEN=your_gitea_token_here
+```
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `GITEA_API_URL` | Gitea API endpoint (with `/api/v1`) | `https://gitea.example.com/api/v1` |
+| `GITEA_API_TOKEN` | Personal access token | `abc123...` |
+
+**Note:** `GITEA_REPO` is configured at the project level in `owner/repo` format since different projects may belong to different organizations.
+
+**Generating a Gitea Token:**
+1. Log into Gitea → **User Icon** → **Settings**
+2. **Applications** tab → **Manage Access Tokens**
+3. **Generate New Token** with permissions:
+   - `repo` (all sub-permissions)
+   - `read:org`
+   - `read:user`
+   - `write:repo` (for wiki access)
+4. Copy token immediately (shown only once)
+
+### NetBox Configuration
+
+```bash
+# ~/.config/claude/netbox.env
+NETBOX_API_URL=https://netbox.example.com
+NETBOX_API_TOKEN=your_netbox_token_here
+```
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `NETBOX_API_URL` | NetBox base URL | `https://netbox.example.com` |
+| `NETBOX_API_TOKEN` | API token | `abc123...` |
+
+### Git-Flow Configuration
+
+```bash
+# ~/.config/claude/git-flow.env
+GIT_WORKFLOW_STYLE=feature-branch
+GIT_DEFAULT_BASE=development
+GIT_AUTO_DELETE_MERGED=true
+GIT_AUTO_PUSH=false
+GIT_PROTECTED_BRANCHES=main,master,development,staging,production
+GIT_COMMIT_STYLE=conventional
+GIT_CO_AUTHOR=true
+```
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `GIT_WORKFLOW_STYLE` | `feature-branch` | Branching strategy |
+| `GIT_DEFAULT_BASE` | `development` | Default base branch |
+| `GIT_AUTO_DELETE_MERGED` | `true` | Delete merged branches |
+| `GIT_AUTO_PUSH` | `false` | Auto-push after commit |
+| `GIT_PROTECTED_BRANCHES` | `main,master,...` | Protected branches |
+| `GIT_COMMIT_STYLE` | `conventional` | Commit message style |
+| `GIT_CO_AUTHOR` | `true` | Include Claude co-author |
+
+---
+
+## Project-Level Configuration
+
+Create `.env` in each project root:
+
+```bash
+# Required for projman, pr-review (use owner/repo format)
+GITEA_REPO=your-organization/your-repo-name
+
+# Optional: Override git-flow defaults
+GIT_WORKFLOW_STYLE=pr-required
+GIT_DEFAULT_BASE=main
+
+# Optional: PR review settings
+PR_REVIEW_CONFIDENCE_THRESHOLD=0.5
+PR_REVIEW_AUTO_SUBMIT=false
+```
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `GITEA_REPO` | Yes | Repository in `owner/repo` format (e.g., `my-org/my-repo`) |
+| `GIT_WORKFLOW_STYLE` | No | Override system default |
+| `PR_REVIEW_*` | No | PR review settings |
+
+---
+
+## Plugin Configuration Summary
+
+| Plugin | System Config | Project Config | Setup Command |
+|--------|---------------|----------------|---------------|
+| **projman** | gitea.env | .env (GITEA_REPO=owner/repo) | `/projman setup` |
+| **pr-review** | gitea.env | .env (GITEA_REPO=owner/repo) | `/pr setup` |
+| **git-flow** | git-flow.env (optional) | .env (optional) | None needed |
+| **clarity-assist** | None | None | None needed |
+| **cmdb-assistant** | netbox.env | None | `/cmdb setup` |
+| **data-platform** | postgres.env | .env (optional) | `/data setup` |
+| **viz-platform** | None | .env (optional DMC_VERSION) | `/viz setup` |
+| **doc-guardian** | None | None | None needed |
+| **code-sentinel** | None | None | None needed |
+| **project-hygiene** | None | None | None needed |
+| **claude-config-maintainer** | None | None | None needed |
+| **contract-validator** | None | None | `/cv setup` |
+
+---
+
+## Multi-Project Workflow
+
+Once system-level config is set up, adding new projects is simple:
+
+```
+cd ~/projects/new-project
+/projman setup
+```
+
+The command auto-detects that system config exists and runs quick project setup.
+
+---
+
+## Installing Plugins to Consumer Projects
+
+The marketplace provides scripts to install plugins into consumer projects. This sets up the MCP server connections and adds CLAUDE.md integration snippets.
+
+### Install a Plugin
+
+```bash
+cd /path/to/leo-claude-mktplace
+./scripts/install-plugin.sh <plugin-name> <target-project-path>
+```
+
+**Examples:**
+```bash
+# Install data-platform to a portfolio project
+./scripts/install-plugin.sh data-platform ~/projects/personal-portfolio
+
+# Install multiple plugins
+./scripts/install-plugin.sh viz-platform ~/projects/personal-portfolio
+./scripts/install-plugin.sh projman ~/projects/personal-portfolio
+```
+
+**What it does:**
+1. Validates the plugin exists in the marketplace
+2. Adds MCP server entry to target's `.mcp.json` (if plugin has MCP server)
+3. Appends integration snippet to target's `CLAUDE.md`
+4. Reports changes and lists available commands
+
+**After installation:** Restart your Claude Code session for MCP tools to become available.
+
+### Uninstall a Plugin
+
+```bash
+./scripts/uninstall-plugin.sh <plugin-name> <target-project-path>
+```
+
+Removes the MCP server entry and CLAUDE.md integration section.
+
+### List Installed Plugins
+
+```bash
+./scripts/list-installed.sh <target-project-path>
+```
+
+Shows which marketplace plugins are installed, partially installed, or available.
+
+**Output example:**
+```
+✓ Fully Installed:
+  PLUGIN                   VERSION    DESCRIPTION
+  ------                   -------    -----------
+  data-platform            1.3.0      pandas, PostgreSQL, and dbt integration...
+  viz-platform             1.1.0      DMC validation, Plotly charts, and theming...
+
+○ Available (not installed):
+  projman                  3.4.0      Sprint planning and project management...
+```
+
+### Plugins with MCP Servers
+
+Not all plugins have MCP servers. The install script handles this automatically:
+
+| Plugin | Has MCP Server | Notes |
+|--------|---------------|-------|
+| data-platform | ✓ | pandas, PostgreSQL, dbt tools |
+| viz-platform | ✓ | DMC validation, chart, theme tools |
+| contract-validator | ✓ | Plugin compatibility validation |
+| cmdb-assistant | ✓ (via netbox) | NetBox CMDB tools |
+| projman | ✓ (via gitea) | Issue, wiki, PR tools |
+| pr-review | ✓ (via gitea) | PR review tools |
+| git-flow | ✗ | Commands only |
+| doc-guardian | ✗ | Commands only |
+| code-sentinel | ✗ | Commands and hooks only |
+| clarity-assist | ✗ | Commands only |
+
+### Script Requirements
+
+- **jq** must be installed (`sudo apt install jq`)
+- Scripts are idempotent (safe to run multiple times)
+
+---
+
+## Agent Frontmatter Configuration
+
+Agents specify their configuration in frontmatter using Claude Code's supported fields. Reference: https://code.claude.com/docs/en/sub-agents
+
+### Supported Frontmatter Fields
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `name` | Yes | — | Unique identifier, lowercase + hyphens |
+| `description` | Yes | — | When Claude should delegate to this subagent |
+| `model` | No | `inherit` | `sonnet`, `opus`, `haiku`, or `inherit` |
+| `permissionMode` | No | `default` | Controls permission prompts: `default`, `acceptEdits`, `dontAsk`, `bypassPermissions`, `plan` |
+| `disallowedTools` | No | none | Comma-separated tools to remove from agent's toolset |
+| `skills` | No | none | Comma-separated skills auto-injected into context at startup |
+| `hooks` | No | none | Lifecycle hooks scoped to this subagent |
+
+### Complete Agent Matrix
+
+| Plugin | Agent | `model` | `permissionMode` | `disallowedTools` | `skills` |
+|--------|-------|---------|-------------------|--------------------|----------|
+| projman | planner | opus | default | — | frontmatter (2) + body text (12) |
+| projman | orchestrator | sonnet | acceptEdits | — | frontmatter (2) + body text (10) |
+| projman | executor | sonnet | bypassPermissions | — | frontmatter (7) |
+| projman | code-reviewer | opus | default | Write, Edit, MultiEdit | frontmatter (4) |
+| pr-review | coordinator | sonnet | plan | Write, Edit, MultiEdit | — |
+| pr-review | security-reviewer | sonnet | plan | Write, Edit, MultiEdit | — |
+| pr-review | performance-analyst | sonnet | plan | Write, Edit, MultiEdit | — |
+| pr-review | maintainability-auditor | haiku | plan | Write, Edit, MultiEdit | — |
+| pr-review | test-validator | haiku | plan | Write, Edit, MultiEdit | — |
+| data-platform | data-advisor | sonnet | default | — | — |
+| data-platform | data-analysis | sonnet | plan | Write, Edit, MultiEdit | — |
+| data-platform | data-ingestion | haiku | acceptEdits | — | — |
+| viz-platform | design-reviewer | sonnet | plan | Write, Edit, MultiEdit | — |
+| viz-platform | layout-builder | sonnet | default | — | — |
+| viz-platform | component-check | haiku | plan | Write, Edit, MultiEdit | — |
+| viz-platform | theme-setup | haiku | acceptEdits | — | — |
+| contract-validator | full-validation | sonnet | default | — | — |
+| contract-validator | agent-check | haiku | plan | Write, Edit, MultiEdit | — |
+| code-sentinel | security-reviewer | sonnet | plan | Write, Edit, MultiEdit | — |
+| code-sentinel | refactor-advisor | sonnet | acceptEdits | — | — |
+| doc-guardian | doc-analyzer | sonnet | acceptEdits | — | — |
+| clarity-assist | clarity-coach | sonnet | default | Write, Edit, MultiEdit | — |
+| git-flow | git-assistant | haiku | acceptEdits | — | — |
+| claude-config-maintainer | maintainer | sonnet | acceptEdits | — | frontmatter (2) |
+| cmdb-assistant | cmdb-assistant | sonnet | default | — | — |
+
+### Design Principles
+
+- `bypassPermissions` is granted to exactly ONE agent (Executor) which has code-sentinel PreToolUse hook + Code Reviewer downstream as safety nets.
+- `plan` mode is assigned to all pure analysis agents (pr-review, read-only validators).
+- `disallowedTools: Write, Edit, MultiEdit` provides defense-in-depth on agents that should never write files.
+- `skills` frontmatter is used for agents with ≤7 skills where guaranteed loading is safety-critical. Agents with 8+ skills use body text `## Skills to Load` for selective loading.
+- `hooks` (agent-scoped) is reserved for future use (v6.0+).
+
+Override any field by editing the agent's `.md` file in `plugins/{plugin}/agents/`.
+
+### permissionMode Guide
+
+| Value | Prompts for file ops? | Prompts for Bash? | Prompts for MCP? | Use when |
+|-------|-----------------------|-------------------|-------------------|----------|
+| `default` | Yes | Yes | No (MCP bypasses permissions) | You want full visibility |
+| `acceptEdits` | No | Yes | No | Core job is file read/write, Bash visibility useful |
+| `dontAsk` | No | No (most) | No | Even Bash prompts are friction |
+| `bypassPermissions` | No | No | No | Agent has downstream safety layers |
+| `plan` | N/A (read-only) | N/A (read-only) | No | Pure analysis, no modifications |
+
+### disallowedTools Guide
+
+Use `disallowedTools` to remove specific tools from an agent's toolset. This is a blacklist — the agent inherits all tools from the main thread, then the listed tools are removed.
+
+Prefer `disallowedTools` over `tools` (whitelist) because:
+- New MCP servers are automatically available without updating every agent.
+- Less configuration to maintain.
+- Easier to audit — you only list what's blocked.
+
+Common patterns:
+- `disallowedTools: Write, Edit, MultiEdit` — read-only agent, cannot modify files.
+- `disallowedTools: Bash` — no shell access (rare, most agents need at least read-only Bash).
+
+### skills Frontmatter Guide
+
+The `skills` field auto-injects skill file contents into the agent's context window at startup. The agent does NOT need to read the files — they are already present.
+
+**When to use frontmatter `skills`:**
+- Agent has ≤7 skills.
+- Skills are safety-critical (e.g., `branch-security`, `runaway-detection`).
+- You need guaranteed loading — no risk of the agent skipping a skill.
+
+**When to keep body text `## Skills to Load`:**
+- Agent has 8+ skills (context window cost too high for full injection).
+- Skills are situational — not all needed for every invocation.
+- Agent benefits from selective loading based on the specific task.
+
+Skill names in frontmatter are resolved relative to the plugin's `skills/` directory. Use the filename without the `.md` extension.
+
+### Phase-Based Skill Loading (Body Text)
+
+For agents with 8+ skills, use **phase-based loading** in the agent body text. This structures skill reads into logical phases, with explicit instructions to read each skill exactly once.
+
+**Pattern:**
+
+```markdown
+## Skill Loading Protocol
+
+**Frontmatter skills (auto-injected, always available — DO NOT re-read these):**
+- `skill-a` — description
+- `skill-b` — description
+
+**Phase 1 skills — read ONCE at session start:**
+- skills/validation-skill.md
+- skills/safety-skill.md
+
+**Phase 2 skills — read ONCE when entering main work:**
+- skills/workflow-skill.md
+- skills/domain-skill.md
+
+**CRITICAL: Read each skill file exactly ONCE. Do NOT re-read skill files between MCP API calls.**
+```
+
+**Benefits:**
+- Frontmatter skills (always needed) are auto-injected — zero file read cost
+- Phase skills are read once at the appropriate time — not re-read per API call
+- `batch-execution` skill provides protocol for API-heavy phases
+- ~76-83% reduction in skill-related token consumption for typical sprints
+
+**Currently applied to:**
+- Planner agent: 2 frontmatter + 12 body text (3 phases)
+- Orchestrator agent: 2 frontmatter + 10 body text (2 phases)
+
+---
+
+## Automatic Validation Features
+
+### API Validation
+
+When running `/projman setup`, the command:
+
+1. **Detects** organization and repository from git remote URL
+2. **Validates** via Gitea API: `GET /api/v1/repos/{org}/{repo}`
+3. **Auto-fills** if repository exists and is accessible (no confirmation needed)
+4. **Asks for confirmation** only if validation fails (404 or permission error)
+
+This catches typos and permission issues before saving configuration.
+
+### Mismatch Detection (SessionStart Hook)
+
+When you start a Claude Code session, a hook automatically:
+
+1. Reads `GITEA_REPO` (in `owner/repo` format) from `.env`
+2. Compares with current `git remote get-url origin`
+3. **Warns** if mismatch detected: "Repository location mismatch. Run `/projman setup --sync` to update."
+
+This helps when you:
+- Move a repository to a different organization
+- Rename a repository
+- Clone a repo but forget to update `.env`
+
+---
+
+## Verification
+
+### Test Gitea Connection
+
+```bash
+source ~/.config/claude/gitea.env
+curl -H "Authorization: token $GITEA_API_TOKEN" "$GITEA_API_URL/user"
+```
+
+### Verify Project Setup
+
+In Claude Code, after restarting your session:
+```
+/labels sync
+```
+
+If this works, your setup is complete.
+
+---
+
+## Troubleshooting
+
+### MCP tools not available
+
+**Cause:** Session wasn't restarted after setup.
+**Solution:** Exit Claude Code and start a new session.
+
+### "Configuration not found" error
+
+```bash
+# Check system config exists
+ls -la ~/.config/claude/gitea.env
+
+# Check permissions (should be 600)
+stat ~/.config/claude/gitea.env
+```
+
+### Authentication failed
+
+```bash
+# Test token directly
+source ~/.config/claude/gitea.env
+curl -H "Authorization: token $GITEA_API_TOKEN" "$GITEA_API_URL/user"
+```
+
+If you get 401, regenerate your token in Gitea.
+
+### MCP server won't start
+
+```bash
+# Check venv exists
+ls /path/to/mcp-servers/gitea/.venv
+
+# If missing, create venv (do NOT delete existing venvs)
+cd /path/to/mcp-servers/gitea
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+deactivate
+```
+
+### Wrong repository
+
+```bash
+# Check project .env
+cat .env
+
+# Verify GITEA_REPO is in owner/repo format and matches Gitea exactly
+# Example: GITEA_REPO=my-org/my-repo
+```
+
+---
+
+## Security Best Practices
+
+1. **Never commit tokens**
+   - Keep credentials in `~/.config/claude/` only
+   - Add `.env` to `.gitignore`
+
+2. **Secure configuration files**
+   ```bash
+   chmod 600 ~/.config/claude/*.env
+   ```
+
+3. **Never type tokens into AI chat**
+   - Always edit config files directly in your editor
+   - The `/projman setup` wizard respects this
+
+4. **Rotate tokens periodically**
+   - Every 6-12 months
+   - Immediately if compromised
+
+5. **Minimum permissions**
+   - Only grant required token permissions
+   - Use separate tokens for different environments

docs/DEBUGGING-CHECKLIST.md

@@ -0,0 +1,291 @@
+# Debugging Checklist for Marketplace Troubleshooting
+
+**Purpose:** Systematic approach to diagnose and fix plugin loading issues.
+
+Last Updated: 2026-02-08
+
+---
+
+## Step 1: Identify the Loading Path
+
+Claude Code loads plugins from different locations depending on context:
+
+| Location | Path | When Used |
+|----------|------|-----------|
+| **Source** | `~/claude-plugins-work/` | When developing in this directory |
+| **Installed** | `~/.claude/plugins/marketplaces/leo-claude-mktplace/` | After marketplace install |
+| **Cache** | `~/.claude/` | Plugin metadata, settings |
+
+**Determine which path Claude is using:**
+
+```bash
+# Check if installed marketplace exists
+ls -la ~/.claude/plugins/marketplaces/leo-claude-mktplace/
+
+# Check Claude's current plugin loading
+cat ~/.claude/settings.local.json | grep -A5 "mcpServers"
+```
+
+**Key insight:** If you're editing source but Claude uses installed, your changes won't take effect.
+
+---
+
+## Step 2: Verify Files Exist at Runtime Location
+
+Check the files Claude will actually load:
+
+```bash
+# For installed marketplace
+RUNTIME=~/.claude/plugins/marketplaces/leo-claude-mktplace
+
+# Check MCP server exists
+ls -la $RUNTIME/mcp-servers/gitea/
+ls -la $RUNTIME/mcp-servers/netbox/
+
+# Check plugin manifests
+ls -la $RUNTIME/plugins/projman/.claude-plugin/plugin.json
+ls -la $RUNTIME/plugins/pr-review/.claude-plugin/plugin.json
+
+# Check .mcp.json files
+cat $RUNTIME/plugins/projman/.mcp.json
+```
+
+---
+
+## Step 3: Verify Virtual Environments Exist
+
+**This is the most common failure point after installation.**
+
+MCP servers require Python venvs to exist at the INSTALLED location:
+
+```bash
+RUNTIME=~/.claude/plugins/marketplaces/leo-claude-mktplace
+
+# Check venvs exist
+ls -la $RUNTIME/mcp-servers/gitea/.venv/bin/python
+ls -la $RUNTIME/mcp-servers/netbox/.venv/bin/python
+
+# If missing, create them:
+cd $RUNTIME && ./scripts/setup.sh
+```
+
+**Common error:** "X MCP servers failed to start" = venvs don't exist in installed path.
+
+---
+
+## Step 4: Verify MCP Configuration
+
+Check `.mcp.json` at marketplace root is correctly configured:
+
+```bash
+RUNTIME=~/.claude/plugins/marketplaces/leo-claude-mktplace
+
+# Check .mcp.json exists and has valid content
+cat $RUNTIME/.mcp.json | jq '.mcpServers | keys'
+
+# Should list: gitea, netbox, data-platform, viz-platform, contract-validator
+```
+
+---
+
+## Step 5: Test MCP Server Startup
+
+Manually test if the MCP server can start:
+
+```bash
+RUNTIME=~/.claude/plugins/marketplaces/leo-claude-mktplace
+
+# Test Gitea MCP (uses gitea-mcp package from registry)
+cd $RUNTIME/mcp-servers/gitea
+.venv/bin/python -c "from gitea_mcp.server import main; print('OK')"
+
+# Test NetBox MCP
+cd $RUNTIME/mcp-servers/netbox
+PYTHONPATH=. .venv/bin/python -c "from mcp_server.server import main; print('OK')"
+```
+
+**If import fails:** Check requirements.txt installed, check Python version compatibility.
+
+---
+
+## Step 6: Verify Configuration Files
+
+Check environment variables are set:
+
+```bash
+# System-level credentials (should exist)
+cat ~/.config/claude/gitea.env
+# Should contain: GITEA_API_URL, GITEA_API_TOKEN
+
+cat ~/.config/claude/netbox.env
+# Should contain: NETBOX_API_URL, NETBOX_API_TOKEN
+
+# Project-level config (in target project)
+cat /path/to/project/.env
+# Should contain: GITEA_REPO=owner/repo (e.g., my-org/my-repo)
+```
+
+---
+
+## Step 7: Verify Hooks Configuration
+
+Check hooks are valid:
+
+```bash
+RUNTIME=~/.claude/plugins/marketplaces/leo-claude-mktplace
+
+# List all hooks.json files
+find $RUNTIME/plugins -name "hooks.json" -exec echo "=== {} ===" \; -exec cat {} \;
+
+# Verify hook events are valid
+# Valid: PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, SessionEnd,
+#        Notification, Stop, SubagentStop, PreCompact
+# INVALID: task-completed, file-changed, git-commit-msg-needed
+```
+
+---
+
+## Quick Diagnostic Commands
+
+Run these to quickly identify issues:
+
+```bash
+RUNTIME=~/.claude/plugins/marketplaces/leo-claude-mktplace
+
+echo "=== Installation Status ==="
+[ -d "$RUNTIME" ] && echo "Installed: YES" || echo "Installed: NO"
+
+echo -e "\n=== Virtual Environments ==="
+[ -f "$RUNTIME/mcp-servers/gitea/.venv/bin/python" ] && echo "Gitea venv: OK" || echo "Gitea venv: MISSING"
+[ -f "$RUNTIME/mcp-servers/netbox/.venv/bin/python" ] && echo "NetBox venv: OK" || echo "NetBox venv: MISSING"
+
+echo -e "\n=== MCP Configuration ==="
+[ -f "$RUNTIME/.mcp.json" ] && echo ".mcp.json: OK" || echo ".mcp.json: MISSING"
+
+echo -e "\n=== Config Files ==="
+[ -f ~/.config/claude/gitea.env ] && echo "gitea.env: OK" || echo "gitea.env: MISSING"
+[ -f ~/.config/claude/netbox.env ] && echo "netbox.env: OK" || echo "netbox.env: MISSING"
+```
+
+---
+
+## Common Issues and Fixes
+
+| Issue | Symptom | Fix |
+|-------|---------|-----|
+| Missing venvs | "X MCP servers failed" | `cd ~/.claude/plugins/marketplaces/leo-claude-mktplace && ./scripts/setup.sh` |
+| Missing .mcp.json | MCP tools not available | Check `.mcp.json` exists at marketplace root |
+| Wrong path edits | Changes don't take effect | Edit installed path or reinstall after source changes |
+| Missing credentials | MCP connection errors | Create `~/.config/claude/gitea.env` with API credentials |
+| Invalid hook events | Hooks don't fire | Use only valid event names (see Step 7) |
+| Gitea issues not closing | Merged to non-default branch | Manually close issues (see below) |
+| MCP changes not taking effect | Session caching | Restart Claude Code session (see below) |
+
+### Gitea Auto-Close Behavior
+
+**Issue:** Using `Closes #XX` or `Fixes #XX` in commit/PR messages does NOT auto-close issues when merging to `development`.
+
+**Root Cause:** Gitea only auto-closes issues when merging to the **default branch** (typically `main` or `master`). Merging to `development`, `staging`, or any other branch will NOT trigger auto-close.
+
+**Workaround:**
+1. Use the Gitea MCP tool to manually close issues after merging to development:
+   ```
+   mcp__plugin_projman_gitea__update_issue(issue_number=XX, state="closed")
+   ```
+2. Or close issues via the Gitea web UI
+3. The auto-close keywords will still work when the changes are eventually merged to `main`
+
+**Recommendation:** Include the `Closes #XX` keywords in commits anyway - they'll work when the final merge to `main` happens.
+
+### MCP Session Restart Requirement
+
+**Issue:** Changes to MCP servers, hooks, or plugin configuration don't take effect immediately.
+
+**Root Cause:** Claude Code loads MCP tools and plugin configuration at session start. These are cached in session memory and not reloaded dynamically.
+
+**What requires a session restart:**
+- MCP server code changes (Python files in `mcp-servers/`)
+- Changes to `.mcp.json` files
+- Changes to `hooks/hooks.json`
+- Changes to `plugin.json`
+- Adding new MCP tools or modifying tool signatures
+
+**What does NOT require a restart:**
+- Command/skill markdown files (`.md`) - these are read on invocation
+- Agent markdown files - read when agent is invoked
+
+**Correct workflow after plugin changes:**
+1. Make changes to source files
+2. Run `./scripts/verify-hooks.sh` to validate
+3. Inform user: "Please restart Claude Code for changes to take effect"
+4. **Do NOT clear cache mid-session** - see "Cache Clearing" section
+
+---
+
+## After Fixing Issues
+
+1. **Restart Claude Code** - Plugins are loaded at startup
+2. **Verify fix works** - Run a simple command that uses the MCP
+3. **Document the issue** - If it's a new failure mode, add to this checklist
+
+---
+
+## Cache Clearing: When It's Safe vs Destructive
+
+**⚠️ CRITICAL: Never clear plugin cache mid-session.**
+
+### Why Cache Clearing Breaks MCP Tools
+
+When Claude Code starts a session:
+1. MCP tools are loaded from the cache directory
+2. Tool definitions include **absolute paths** to the venv (e.g., `~/.claude/plugins/cache/.../venv/`)
+3. These paths are cached in the session memory
+4. Deleting the cache removes the venv, but the session still references the old paths
+5. Any MCP tool making HTTP requests fails with TLS certificate errors
+
+### When Cache Clearing is SAFE
+
+| Scenario | Safe? | Action |
+|----------|-------|--------|
+| Before starting Claude Code | ✅ Yes | Clear cache, then start session |
+| Between sessions | ✅ Yes | Clear cache after `/exit`, before next session |
+| During a session | ❌ NO | Never - will break MCP tools |
+| After plugin source edits | ❌ NO | Restart session instead |
+
+### Recovery: MCP Tools Broken Mid-Session
+
+If you accidentally cleared cache during a session and MCP tools fail:
+
+```
+Error: Could not find a suitable TLS CA certificate bundle, invalid path:
+/home/.../.claude/plugins/cache/.../certifi/cacert.pem
+```
+
+**Fix:**
+1. Exit the current session (`/exit` or Ctrl+C)
+2. Start a new Claude Code session
+3. MCP tools will reload from the reinstalled cache
+
+### Correct Workflow for Plugin Development
+
+1. Make changes to plugin source files
+2. Run `./scripts/verify-hooks.sh` (verifies hook types)
+3. Tell user: "Please restart Claude Code for changes to take effect"
+4. **Do NOT clear cache** - session restart handles reloading
+
+---
+
+## Automated Diagnostics
+
+Use these commands for automated checking:
+
+- `/cv status` - Marketplace-wide health check (installation, MCP, configuration)
+- `/hygiene check` - Project file organization and cleanup check
+
+---
+
+## Related Documentation
+
+- `CLAUDE.md` - Installation Paths and Troubleshooting sections
+- `docs/CONFIGURATION.md` - Setup and configuration guide
+- `docs/UPDATING.md` - Update procedures

docs/MIGRATION-v9.md

@@ -0,0 +1,249 @@
+# Migration Guide: v8.x → v9.0.0
+
+## Overview
+
+v9.0.0 standardizes all commands to the `/<noun> <action>` sub-command pattern. Every command in the marketplace now follows this convention.
+
+**Breaking change:** All old command names are removed. Update your workflows, scripts, and CLAUDE.md references.
+
+---
+
+## Command Invocation
+
+The `/<noun> <action>` pattern is a **display convention** for user-friendly command invocation. Under the hood, Claude Code resolves commands by filename using hyphens.
+
+### How It Works
+
+| You Type | What Happens | Actual Command Loaded |
+|----------|--------------|----------------------|
+| `/doc audit` | Dispatch file `doc.md` receives `$ARGUMENTS="audit"` | Routes to `/doc-guardian:doc-audit` (file: `doc-audit.md`) |
+| `/sprint plan` | Dispatch file `sprint.md` receives `$ARGUMENTS="plan"` | Routes to `/projman:sprint-plan` (file: `sprint-plan.md`) |
+| `/doc-guardian:doc-audit` | Direct invocation (bypasses dispatch) | Loads `doc-audit.md` directly |
+
+### Two Invocation Methods
+
+1. **User-friendly (via dispatch):** `/doc audit` — space-separated, routes through dispatch file
+2. **Direct (plugin-prefixed):** `/doc-guardian:doc-audit` — bypasses dispatch, invokes command directly
+
+Both methods work identically. The dispatch file provides `$ARGUMENTS` parsing and a menu interface when invoked without arguments.
+
+### Command Name Mapping
+
+**Pattern:** Spaces in display names become hyphens in filenames.
+
+| Display Name | Filename | Plugin-Prefixed |
+|--------------|----------|-----------------|
+| `/doc audit` | `doc-audit.md` | `/doc-guardian:doc-audit` |
+| `/sprint plan` | `sprint-plan.md` | `/projman:sprint-plan` |
+| `/pr review` | `pr-review.md` | `/pr-review:pr-review` |
+| `/gitflow commit` | `gitflow-commit.md` | `/git-flow:gitflow-commit` |
+
+If dispatch routing fails, use the direct plugin-prefixed format.
+
+---
+
+## Complete Command Mapping
+
+### projman
+
+| Old (v8.x) | New (v9.0.0) | Notes |
+|-------------|--------------|-------|
+| `/sprint-plan` | `/sprint plan` | |
+| `/sprint-start` | `/sprint start` | |
+| `/sprint-status` | `/sprint status` | |
+| `/sprint-close` | `/sprint close` | |
+| `/pm-review` | `/sprint review` | Moved under `/sprint` |
+| `/pm-test` | `/sprint test` | Moved under `/sprint` |
+| `/pm-setup` | `/projman setup` | Moved under `/projman` |
+| `/pm-debug` | **Removed** | Deleted in v8.1.0 — migrated to `debug-mcp` plugin (Decision #11) |
+| `/labels-sync` | `/labels sync` | |
+| `/suggest-version` | **Removed** | Deleted in v8.1.0 — migrated to `ops-release-manager` plugin (Decision #18) |
+| `/proposal-status` | **Removed** | Deleted in v8.1.0 — absorbed into `/project status` (Decision #19) |
+| `/rfc <sub>` | `/rfc <sub>` | Unchanged |
+| `/project <sub>` | `/project <sub>` | Unchanged |
+| `/adr <sub>` | `/adr <sub>` | Unchanged |
+
+### git-flow
+
+| Old (v8.x) | New (v9.0.0) | Notes |
+|-------------|--------------|-------|
+| `/git-commit` | `/gitflow commit` | |
+| `/git-commit-push` | `/gitflow commit --push` | **Consolidated** into flag |
+| `/git-commit-merge` | `/gitflow commit --merge` | **Consolidated** into flag |
+| `/git-commit-sync` | `/gitflow commit --sync` | **Consolidated** into flag |
+| `/branch-start` | `/gitflow branch-start` | |
+| `/branch-cleanup` | `/gitflow branch-cleanup` | |
+| `/git-status` | `/gitflow status` | |
+| `/git-config` | `/gitflow config` | |
+
+**Note:** The three commit variants (`-push`, `-merge`, `-sync`) are now flags on `/gitflow commit`. This reduces 8 commands to 5.
+
+### pr-review
+
+| Old (v8.x) | New (v9.0.0) | Notes |
+|-------------|--------------|-------|
+| `/pr-review` | `/pr review` | |
+| `/pr-summary` | `/pr summary` | |
+| `/pr-findings` | `/pr findings` | |
+| `/pr-diff` | `/pr diff` | |
+| `/pr-setup` | `/pr setup` | |
+| `/project-init` | `/pr init` | Renamed |
+| `/project-sync` | `/pr sync` | Renamed |
+
+### clarity-assist
+
+| Old (v8.x) | New (v9.0.0) | Notes |
+|-------------|--------------|-------|
+| `/clarify` | `/clarity clarify` | |
+| `/quick-clarify` | `/clarity quick-clarify` | |
+
+### doc-guardian
+
+| Old (v8.x) | New (v9.0.0) | Notes |
+|-------------|--------------|-------|
+| `/doc-audit` | `/doc audit` | |
+| `/doc-sync` | `/doc sync` | |
+| `/changelog-gen` | `/doc changelog-gen` | Moved under `/doc` |
+| `/doc-coverage` | `/doc coverage` | |
+| `/stale-docs` | `/doc stale-docs` | Moved under `/doc` |
+
+### code-sentinel
+
+| Old (v8.x) | New (v9.0.0) | Notes |
+|-------------|--------------|-------|
+| `/security-scan` | `/sentinel scan` | |
+| `/refactor` | `/sentinel refactor` | |
+| `/refactor-dry` | `/sentinel refactor-dry` | |
+
+### claude-config-maintainer
+
+| Old (v8.x) | New (v9.0.0) | Notes |
+|-------------|--------------|-------|
+| `/config-analyze` (or `/analyze`) | `/claude-config analyze` | |
+| `/config-optimize` (or `/optimize`) | `/claude-config optimize` | |
+| `/config-init` (or `/init`) | `/claude-config init` | |
+| `/config-diff` | `/claude-config diff` | |
+| `/config-lint` | `/claude-config lint` | |
+| `/config-audit-settings` | `/claude-config audit-settings` | |
+| `/config-optimize-settings` | `/claude-config optimize-settings` | |
+| `/config-permissions-map` | `/claude-config permissions-map` | |
+
+### contract-validator
+
+| Old (v8.x) | New (v9.0.0) | Notes |
+|-------------|--------------|-------|
+| `/validate-contracts` | `/cv validate` | |
+| `/check-agent` | `/cv check-agent` | |
+| `/list-interfaces` | `/cv list-interfaces` | |
+| `/dependency-graph` | `/cv dependency-graph` | |
+| `/cv-setup` | `/cv setup` | |
+| `/cv status` | `/cv status` | Unchanged |
+
+### cmdb-assistant
+
+| Old (v8.x) | New (v9.0.0) | Notes |
+|-------------|--------------|-------|
+| `/cmdb-setup` | `/cmdb setup` | |
+| `/cmdb-search` | `/cmdb search` | |
+| `/cmdb-device` | `/cmdb device` | |
+| `/cmdb-ip` | `/cmdb ip` | |
+| `/cmdb-site` | `/cmdb site` | |
+| `/cmdb-audit` | `/cmdb audit` | |
+| `/cmdb-register` | `/cmdb register` | |
+| `/cmdb-sync` | `/cmdb sync` | |
+| `/cmdb-topology` | `/cmdb topology` | |
+| `/change-audit` | `/cmdb change-audit` | Moved under `/cmdb` |
+| `/ip-conflicts` | `/cmdb ip-conflicts` | Moved under `/cmdb` |
+
+### data-platform
+
+| Old (v8.x) | New (v9.0.0) | Notes |
+|-------------|--------------|-------|
+| `/data-ingest` | `/data ingest` | |
+| `/data-profile` | `/data profile` | |
+| `/data-schema` | `/data schema` | |
+| `/data-explain` | `/data explain` | |
+| `/data-lineage` | `/data lineage` | |
+| `/data-run` | `/data run` | |
+| `/lineage-viz` | `/data lineage-viz` | Moved under `/data` |
+| `/dbt-test` | `/data dbt-test` | Moved under `/data` |
+| `/data-quality` | `/data quality` | |
+| `/data-review` | `/data review` | |
+| `/data-gate` | `/data gate` | |
+| `/data-setup` | `/data setup` | |
+
+### viz-platform
+
+| Old (v8.x) | New (v9.0.0) | Notes |
+|-------------|--------------|-------|
+| `/viz-setup` | `/viz setup` | |
+| `/viz-chart` | `/viz chart` | |
+| `/viz-chart-export` | `/viz chart-export` | |
+| `/viz-dashboard` | `/viz dashboard` | |
+| `/viz-theme` | `/viz theme` | |
+| `/viz-theme-new` | `/viz theme-new` | |
+| `/viz-theme-css` | `/viz theme-css` | |
+| `/viz-component` | `/viz component` | |
+| `/accessibility-check` | `/viz accessibility-check` | Moved under `/viz` |
+| `/viz-breakpoints` | `/viz breakpoints` | |
+| `/design-review` | `/viz design-review` | Moved under `/viz` |
+| `/design-gate` | `/viz design-gate` | Moved under `/viz` |
+
+### project-hygiene
+
+No changes — already used `/<noun> <action>` pattern.
+
+| Command | Status |
+|---------|--------|
+| `/hygiene check` | Unchanged |
+
+---
+
+## Verifying Plugin Installation (v9.0.0)
+
+Test commands use the new format:
+
+| Plugin | Test Command |
+|--------|--------------|
+| git-flow | `/git-flow:gitflow-status` |
+| projman | `/projman:sprint-status` |
+| pr-review | `/pr-review:pr-summary` |
+| clarity-assist | `/clarity-assist:clarity-clarify` |
+| doc-guardian | `/doc-guardian:doc-audit` |
+| code-sentinel | `/code-sentinel:sentinel-scan` |
+| claude-config-maintainer | `/claude-config-maintainer:claude-config-analyze` |
+| cmdb-assistant | `/cmdb-assistant:cmdb-search` |
+| data-platform | `/data-platform:data-ingest` |
+| viz-platform | `/viz-platform:viz-chart` |
+| contract-validator | `/contract-validator:cv-validate` |
+
+---
+
+## CLAUDE.md Updates
+
+If your project's CLAUDE.md references old command names, update them:
+
+**Find old references:**
+```bash
+grep -rn '/sprint-plan\|/pm-setup\|/git-commit\|/pr-review\|/security-scan\|/config-analyze\|/validate-contracts\|/cmdb-search\|/data-ingest\|/viz-chart\b\|/clarify\b\|/doc-audit' CLAUDE.md
+```
+
+**Key patterns to search and replace:**
+- `/sprint-plan` → `/sprint plan`
+- `/pm-setup` → `/projman setup`
+- `/pm-review` → `/sprint review`
+- `/git-commit` → `/gitflow commit`
+- `/pr-review` → `/pr review`
+- `/security-scan` → `/sentinel scan`
+- `/refactor` → `/sentinel refactor`
+- `/config-analyze` → `/claude-config analyze`
+- `/validate-contracts` → `/cv validate`
+- `/clarify` → `/clarity clarify`
+- `/doc-audit` → `/doc audit`
+- `/cmdb-search` → `/cmdb search`
+- `/data-ingest` → `/data ingest`
+- `/viz-chart` → `/viz chart`
+
+---
+
+*Last Updated: 2026-02-06*

docs/UPDATING.md

@@ -1,24 +1,71 @@
-# Updating support-claude-mktplace
+# Updating Leo Claude Marketplace
 
 This guide covers how to update your local installation when new versions are released.
 
-## Quick Update
+---
+
+## ⚠️ CRITICAL: Run Setup in Installed Location
+
+When Claude Code installs a marketplace, it copies files to `~/.claude/plugins/marketplaces/` but **does NOT create Python virtual environments**. You must run setup manually after installation or update.
+
+**After installing or updating the marketplace:**
 
 ```bash
-# 1. Pull latest changes
-cd /path/to/support-claude-mktplace
+cd ~/.claude/plugins/marketplaces/leo-claude-mktplace && ./scripts/setup.sh
+```
+
+This creates the required `.venv` directories for MCP servers. Without this step, **all MCP servers will fail to start**.
+
+---
+
+## Quick Update (Source Repository)
+
+```bash
+# 1. Pull latest changes to source
+cd /path/to/leo-claude-mktplace
 git pull origin main
 
-# 2. Run post-update script
+# 2. Run post-update script (updates source repo venvs)
 ./scripts/post-update.sh
+
+# 3. CRITICAL: Run setup in installed marketplace location
+cd ~/.claude/plugins/marketplaces/leo-claude-mktplace && ./scripts/setup.sh
 ```
 
+**Then restart your Claude Code session** to load any changes.
+
+---
+
 ## What the Post-Update Script Does
 
-1. **Updates Python dependencies** for Gitea and Wiki.js MCP servers
+1. **Updates Python dependencies** for all 5 MCP servers (gitea, netbox, data-platform, viz-platform, contract-validator)
 2. **Shows recent changelog entries** so you know what changed
 3. **Validates your configuration** is still compatible
 
+---
+
+## After Updating: Re-run Setup if Needed
+
+### When to Re-run Setup
+
+You typically **don't need** to re-run setup after updates. However, re-run your plugin's setup command (e.g., `/projman setup`, `/pr setup`, `/cmdb setup`) if:
+
+- Changelog mentions **new required environment variables**
+- Changelog mentions **breaking changes** to configuration
+- MCP tools stop working after update
+
+### For Existing Projects
+
+If an update requires new project-level configuration:
+
+```
+/pr init
+```
+
+This will detect existing settings and only add what's missing.
+
+---
+
 ## Manual Steps After Update
 
 Some updates may require manual configuration changes:
@@ -29,8 +76,7 @@ If the changelog mentions new environment variables:
 
 1. Check the variable name and purpose in the changelog
 2. Add it to the appropriate config file:
-   - Gitea variables → `~/.config/claude/gitea.env`
-   - Wiki.js variables → `~/.config/claude/wikijs.env`
+   - System variables → `~/.config/claude/gitea.env` or `netbox.env`
    - Project variables → `.env` in your project root
 
 ### New MCP Server Features
@@ -38,30 +84,56 @@ If the changelog mentions new environment variables:
 If a new MCP server tool is added:
 
 1. The post-update script handles dependency installation
-2. Check `docs/references/MCP-*.md` for usage documentation
-3. New tools are available immediately after update
+2. Check plugin documentation for usage
+3. New tools are available immediately after session restart
 
 ### Breaking Changes
 
 Breaking changes will be clearly marked in CHANGELOG.md with migration instructions.
 
-## Troubleshooting
+### Setup Script and Configuration Workflow Changes
+
+When updating, review if changes affect the setup workflow:
+
+1. **Check for setup command changes:**
+   ```bash
+   git diff HEAD~1 plugins/*/commands/*-setup.md
+   git diff HEAD~1 plugins/*/commands/pr-init.md
+   git diff HEAD~1 plugins/*/commands/pr-sync.md
+   ```
+
+2. **Check for hook changes:**
+   ```bash
+   git diff HEAD~1 plugins/*/hooks/hooks.json
+   ```
+
+3. **Check for configuration structure changes:**
+   ```bash
+   git diff HEAD~1 docs/CONFIGURATION.md
+   ```
+
+**If setup commands changed:**
+- Review what's new (new validation steps, new prompts, etc.)
+- Consider re-running your plugin's setup command or `/pr init` to benefit from improvements
+- Existing configurations remain valid unless changelog notes breaking changes
+
+**If hooks changed:**
+- Restart your Claude Code session to load new hooks
+- New hooks (like SessionStart validation) activate automatically
+
+**If configuration structure changed:**
+- Check if new variables are required
+- Run `/pr sync` if repository detection logic improved
+
+---
+
+## Troubleshooting Updates
 
 ### Dependencies fail to install
 
 ```bash
-# Rebuild virtual environment
+# Install missing dependencies (do NOT delete .venv)
 cd mcp-servers/gitea
-rm -rf .venv
-python3 -m venv .venv
-source .venv/bin/activate
-pip install -r requirements.txt
-deactivate
-
-# Repeat for wikijs
-cd ../wikijs
-rm -rf .venv
-python3 -m venv .venv
 source .venv/bin/activate
 pip install -r requirements.txt
 deactivate
@@ -70,14 +142,48 @@ deactivate
 ### Configuration no longer works
 
 1. Check CHANGELOG.md for breaking changes
-2. Compare your config files with updated `.env.example` (if provided)
-3. Run `./scripts/setup.sh` to validate configuration
+2. Run your plugin's setup command (e.g., `/projman setup`) to re-validate and fix configuration
+3. Compare your config files with documentation in `docs/CONFIGURATION.md`
 
-### MCP server won't start
+### MCP server won't start after update
+
+**Most common cause:** Virtual environments don't exist in the installed marketplace.
+
+```bash
+# Fix: Run setup in installed location
+cd ~/.claude/plugins/marketplaces/leo-claude-mktplace && ./scripts/setup.sh
+```
+
+If that doesn't work:
 
 1. Check Python version: `python3 --version` (requires 3.10+)
-2. Verify venv exists: `ls mcp-servers/gitea/.venv`
-3. Check logs for specific errors
+2. Verify venvs exist in INSTALLED location:
+   ```bash
+   for server in gitea netbox data-platform viz-platform contract-validator; do
+     ls ~/.claude/plugins/marketplaces/leo-claude-mktplace/mcp-servers/$server/.venv && echo "$server: OK" || echo "$server: MISSING"
+   done
+   ```
+3. If missing, run setup.sh as shown above.
+4. Restart Claude Code session
+5. Check logs for specific errors
+
+### "X MCP servers failed" on startup
+
+This almost always means the venvs don't exist in the installed marketplace:
+
+```bash
+cd ~/.claude/plugins/marketplaces/leo-claude-mktplace && ./scripts/setup.sh
+```
+
+Then restart Claude Code.
+
+### New commands not available
+
+1. Restart your Claude Code session
+2. Verify the plugin is still installed
+3. Check if the command requires additional setup
+
+---
 
 ## Version Pinning
 
@@ -88,14 +194,28 @@ To stay on a specific version:
 git tag
 
 # Checkout specific version
-git checkout v1.0.0
+git checkout v3.0.0
 
 # Run post-update
 ./scripts/post-update.sh
 ```
 
+---
+
+## Checking Current Version
+
+The version is displayed in the main README.md title and in `CHANGELOG.md`.
+
+```bash
+# Check version from changelog
+head -20 CHANGELOG.md
+```
+
+---
+
 ## Getting Help
 
-- Check `docs/references/` for component documentation
-- Review CHANGELOG.md for recent changes
+- Check `docs/CONFIGURATION.md` for setup guide
+- Check `docs/COMMANDS-CHEATSHEET.md` for command reference
+- Review `CHANGELOG.md` for recent changes
 - Search existing issues in Gitea

docs/architecture/agent-workflow.spec.md

@@ -1,221 +0,0 @@
-# Agent Workflow - Draw.io Specification
-
-**Target File:** `docs/architecture/agent-workflow.drawio`
-
-**Purpose:** Shows when Planner, Orchestrator, and Executor agents trigger during sprint lifecycle.
-
-**Diagram Type:** Swimlane / Sequence Diagram
-
----
-
-## SWIMLANES
-
-| ID | Label | Color | Position |
-|----|-------|-------|----------|
-| user-lane | User | #E3F2FD | 1 (leftmost) |
-| planner-lane | Planner Agent | #4A90D9 | 2 |
-| orchestrator-lane | Orchestrator Agent | #7CB342 | 3 |
-| executor-lane | Executor Agent | #FF9800 | 4 |
-| gitea-lane | Gitea | #9E9E9E | 5 |
-| wikijs-lane | Wiki.js | #9E9E9E | 6 (rightmost) |
-
----
-
-## PHASE 1: SPRINT PLANNING
-
-### Nodes
-
-| ID | Label | Type | Lane | Sequence |
-|----|-------|------|------|----------|
-| p1-start | /sprint-plan | rounded-rect | user-lane | 1 |
-| p1-activate | Planner Activates | rectangle | planner-lane | 2 |
-| p1-search-lessons | Search Lessons Learned | rectangle | planner-lane | 3 |
-| p1-wikijs-query | Query Past Lessons | rectangle | wikijs-lane | 4 |
-| p1-return-lessons | Return Relevant Lessons | rectangle | planner-lane | 5 |
-| p1-clarify | Ask Clarifying Questions | diamond | planner-lane | 6 |
-| p1-user-answers | Provide Answers | rectangle | user-lane | 7 |
-| p1-create-issues | Create Issues with Labels | rectangle | planner-lane | 8 |
-| p1-gitea-create | Store Issues | rectangle | gitea-lane | 9 |
-| p1-plan-complete | Planning Complete | rounded-rect | planner-lane | 10 |
-
-### Edges
-
-| From | To | Label | Style |
-|------|----|-------|-------|
-| p1-start | p1-activate | invokes | solid |
-| p1-activate | p1-search-lessons | | solid |
-| p1-search-lessons | p1-wikijs-query | GraphQL search | solid |
-| p1-wikijs-query | p1-return-lessons | lessons data | dashed |
-| p1-return-lessons | p1-clarify | | solid |
-| p1-clarify | p1-user-answers | questions | solid |
-| p1-user-answers | p1-clarify | answers | dashed |
-| p1-clarify | p1-create-issues | | solid |
-| p1-create-issues | p1-gitea-create | REST API | solid |
-| p1-gitea-create | p1-plan-complete | confirm | dashed |
-
----
-
-## PHASE 2: SPRINT EXECUTION
-
-### Nodes
-
-| ID | Label | Type | Lane | Sequence |
-|----|-------|------|------|----------|
-| p2-start | /sprint-start | rounded-rect | user-lane | 11 |
-| p2-orch-activate | Orchestrator Activates | rectangle | orchestrator-lane | 12 |
-| p2-fetch-issues | Fetch Sprint Issues | rectangle | orchestrator-lane | 13 |
-| p2-gitea-list | List Open Issues | rectangle | gitea-lane | 14 |
-| p2-sequence | Sequence Work | rectangle | orchestrator-lane | 15 |
-| p2-dispatch | Dispatch Task | rectangle | orchestrator-lane | 16 |
-| p2-exec-activate | Executor Activates | rectangle | executor-lane | 17 |
-| p2-implement | Implement Task | rectangle | executor-lane | 18 |
-| p2-update-status | Update Issue Status | rectangle | executor-lane | 19 |
-| p2-gitea-update | Update Issue | rectangle | gitea-lane | 20 |
-| p2-report | Report Completion | rectangle | executor-lane | 21 |
-| p2-loop | More Tasks? | diamond | orchestrator-lane | 22 |
-| p2-exec-complete | Execution Complete | rounded-rect | orchestrator-lane | 23 |
-
-### Edges
-
-| From | To | Label | Style |
-|------|----|-------|-------|
-| p2-start | p2-orch-activate | invokes | solid |
-| p2-orch-activate | p2-fetch-issues | | solid |
-| p2-fetch-issues | p2-gitea-list | REST API | solid |
-| p2-gitea-list | p2-sequence | issues data | dashed |
-| p2-sequence | p2-dispatch | | solid |
-| p2-dispatch | p2-exec-activate | execution prompt | solid |
-| p2-exec-activate | p2-implement | | solid |
-| p2-implement | p2-update-status | | solid |
-| p2-update-status | p2-gitea-update | REST API | solid |
-| p2-gitea-update | p2-report | confirm | dashed |
-| p2-report | p2-loop | | solid |
-| p2-loop | p2-dispatch | yes | solid |
-| p2-loop | p2-exec-complete | no | solid |
-
----
-
-## PHASE 3: SPRINT CLOSE
-
-### Nodes
-
-| ID | Label | Type | Lane | Sequence |
-|----|-------|------|------|----------|
-| p3-start | /sprint-close | rounded-rect | user-lane | 24 |
-| p3-orch-activate | Orchestrator Activates | rectangle | orchestrator-lane | 25 |
-| p3-review | Review Sprint | rectangle | orchestrator-lane | 26 |
-| p3-gitea-status | Get Final Status | rectangle | gitea-lane | 27 |
-| p3-capture | Capture Lessons Learned | rectangle | orchestrator-lane | 28 |
-| p3-user-input | Confirm Lessons | diamond | user-lane | 29 |
-| p3-create-wiki | Create Wiki Pages | rectangle | orchestrator-lane | 30 |
-| p3-wikijs-create | Store Lessons | rectangle | wikijs-lane | 31 |
-| p3-close-issues | Close Issues | rectangle | orchestrator-lane | 32 |
-| p3-gitea-close | Mark Closed | rectangle | gitea-lane | 33 |
-| p3-complete | Sprint Closed | rounded-rect | orchestrator-lane | 34 |
-
-### Edges
-
-| From | To | Label | Style |
-|------|----|-------|-------|
-| p3-start | p3-orch-activate | invokes | solid |
-| p3-orch-activate | p3-review | | solid |
-| p3-review | p3-gitea-status | REST API | solid |
-| p3-gitea-status | p3-capture | status data | dashed |
-| p3-capture | p3-user-input | proposed lessons | solid |
-| p3-user-input | p3-create-wiki | confirmed | solid |
-| p3-create-wiki | p3-wikijs-create | GraphQL mutation | solid |
-| p3-wikijs-create | p3-close-issues | confirm | dashed |
-| p3-close-issues | p3-gitea-close | REST API | solid |
-| p3-gitea-close | p3-complete | confirm | dashed |
-
----
-
-## LAYOUT NOTES
-
-```
-+--------+------------+---------------+------------+--------+----------+
-|  User  |  Planner   | Orchestrator  |  Executor  | Gitea  | Wiki.js  |
-+--------+------------+---------------+------------+--------+----------+
-|        |            |               |            |        |          |
-| PHASE 1: SPRINT PLANNING                                             |
-|---------------------------------------------------------------------+
-|  O     |            |               |            |        |          |
-|  |     |            |               |            |        |          |
-|  +---->| O          |               |            |        |          |
-|        | |          |               |            |        |          |
-|        | +----------|---------------|------------|------->| O        |
-|        | |<---------|---------------|------------|--------+ |        |
-|        | |          |               |            |        |          |
-|        | O<>        |               |            |        |          |
-|  O<--->+ |          |               |            |        |          |
-|        | |          |               |            |        |          |
-|        | +----------|---------------|----------->| O      |          |
-|        | O          |               |            |        |          |
-|        |            |               |            |        |          |
-|---------------------------------------------------------------------+
-| PHASE 2: SPRINT EXECUTION                                            |
-|---------------------------------------------------------------------+
-|  O     |            |               |            |        |          |
-|  |     |            |               |            |        |          |
-|  +-----|----------->| O             |            |        |          |
-|        |            | |             |            |        |          |
-|        |            | +-------------|----------->| O      |          |
-|        |            | |<------------|------------+ |      |          |
-|        |            | |             |            |        |          |
-|        |            | +------------>| O          |        |          |
-|        |            |               | |          |        |          |
-|        |            |               | +--------->| O      |          |
-|        |            |               | |<---------+ |      |          |
-|        |            | O<------------+ |          |        |          |
-|        |            | |             |            |        |          |
-|        |            | O (loop)      |            |        |          |
-|        |            |               |            |        |          |
-|---------------------------------------------------------------------+
-| PHASE 3: SPRINT CLOSE                                                |
-|---------------------------------------------------------------------+
-|  O     |            |               |            |        |          |
-|  |     |            |               |            |        |          |
-|  +-----|----------->| O             |            |        |          |
-|        |            | +-------------|----------->| O      |          |
-|        |            | |<------------|------------+ |      |          |
-|        |            | |             |            |        |          |
-|  O<----|-----------<+ |             |            |        |          |
-|  +-----|----------->| |             |            |        |          |
-|        |            | +-------------|------------|------->| O        |
-|        |            | |<------------|------------|--------+ |        |
-|        |            | +-------------|----------->| O      |          |
-|        |            | O             |            |        |          |
-+--------+------------+---------------+------------+--------+----------+
-```
-
----
-
-## COLOR LEGEND
-
-| Color | Hex | Meaning |
-|-------|-----|---------|
-| Light Blue | #E3F2FD | User actions |
-| Blue | #4A90D9 | Planner Agent |
-| Green | #7CB342 | Orchestrator Agent |
-| Orange | #FF9800 | Executor Agent |
-| Gray | #9E9E9E | External Services |
-
----
-
-## SHAPE LEGEND
-
-| Shape | Meaning |
-|-------|---------|
-| Rounded Rectangle | Start/End points (commands) |
-| Rectangle | Process/Action |
-| Diamond | Decision point |
-| Cylinder | Data store (in component map) |
-
----
-
-## ARROW LEGEND
-
-| Style | Meaning |
-|-------|---------|
-| Solid | Action/Request |
-| Dashed | Response/Data return |

docs/architecture/component-map.spec.md

@@ -1,133 +0,0 @@
-# Component Map - Draw.io Specification
-
-**Target File:** `docs/architecture/component-map.drawio`
-
-**Purpose:** Shows all plugins, MCP servers, hooks and their relationships.
-
----
-
-## NODES
-
-### Plugins (Blue - #4A90D9)
-
-| ID | Label | Type | Color | Position |
-|----|-------|------|-------|----------|
-| projman | projman | rectangle | #4A90D9 | top-center |
-| projman-pmo | projman-pmo | rectangle | #4A90D9 | top-right |
-| project-hygiene | project-hygiene | rectangle | #4A90D9 | top-left |
-
-### MCP Servers (Green - #7CB342)
-
-| ID | Label | Type | Color | Position |
-|----|-------|------|-------|----------|
-| gitea-mcp | Gitea MCP Server | rectangle | #7CB342 | middle-left |
-| wikijs-mcp | Wiki.js MCP Server | rectangle | #7CB342 | middle-right |
-
-### External Systems (Gray - #9E9E9E)
-
-| ID | Label | Type | Color | Position |
-|----|-------|------|-------|----------|
-| gitea-instance | Gitea\ngitea.hotserv.cloud | cylinder | #9E9E9E | bottom-left |
-| wikijs-instance | Wiki.js\nwikijs.hotserv.cloud | cylinder | #9E9E9E | bottom-right |
-
-### Configuration (Orange - #FF9800)
-
-| ID | Label | Type | Color | Position |
-|----|-------|------|-------|----------|
-| system-config | System Config\n~/.config/claude/ | rectangle | #FF9800 | far-left |
-| project-config | Project Config\n.env | rectangle | #FF9800 | far-right |
-
----
-
-## EDGES
-
-### Plugin to MCP Server Connections
-
-| From | To | Label | Style | Arrow |
-|------|----|-------|-------|-------|
-| projman | gitea-mcp | uses | solid | forward |
-| projman | wikijs-mcp | uses | solid | forward |
-| projman-pmo | gitea-mcp | uses (company-wide) | solid | forward |
-| projman-pmo | wikijs-mcp | uses (company-wide) | solid | forward |
-
-### Plugin Dependencies
-
-| From | To | Label | Style | Arrow |
-|------|----|-------|-------|-------|
-| projman-pmo | projman | depends on | dashed | forward |
-
-### MCP Server to External System Connections
-
-| From | To | Label | Style | Arrow |
-|------|----|-------|-------|-------|
-| gitea-mcp | gitea-instance | REST API | solid | forward |
-| wikijs-mcp | wikijs-instance | GraphQL | solid | forward |
-
-### Configuration Connections
-
-| From | To | Label | Style | Arrow |
-|------|----|-------|-------|-------|
-| system-config | gitea-mcp | credentials | dashed | forward |
-| system-config | wikijs-mcp | credentials | dashed | forward |
-| project-config | gitea-mcp | repo context | dashed | forward |
-| project-config | wikijs-mcp | project path | dashed | forward |
-
----
-
-## GROUPS
-
-| ID | Label | Contains | Style |
-|----|-------|----------|-------|
-| plugins-group | Plugins | projman, projman-pmo, project-hygiene | light blue border |
-| mcp-group | Shared MCP Servers | gitea-mcp, wikijs-mcp | light green border |
-| external-group | External Services | gitea-instance, wikijs-instance | light gray border |
-| config-group | Configuration | system-config, project-config | light orange border |
-
----
-
-## LAYOUT NOTES
-
-```
-+------------------------------------------------------------------+
-|                         PLUGINS GROUP                             |
-|  +----------------+  +----------------+  +-------------------+    |
-|  | project-       |  |    projman     |  |   projman-pmo    |    |
-|  | hygiene        |  |                |  |                   |    |
-|  +----------------+  +-------+--------+  +--------+----------+    |
-|                              |                    |               |
-+------------------------------------------------------------------+
-                               |                    |
-                               v                    v
-+------------------------------------------------------------------+
-|                      MCP SERVERS GROUP                            |
-|  +-------------------+              +-------------------+         |
-|  |  Gitea MCP Server |              | Wiki.js MCP Server|         |
-|  +--------+----------+              +---------+---------+         |
-+------------------------------------------------------------------+
-           |                                     |
-           v                                     v
-+------------------------------------------------------------------+
-|                    EXTERNAL SERVICES GROUP                        |
-|  +-------------------+              +-------------------+         |
-|  |      Gitea        |              |     Wiki.js       |         |
-|  | gitea.hotserv.cloud              | wikijs.hotserv.cloud        |
-|  +-------------------+              +-------------------+         |
-+------------------------------------------------------------------+
-
-CONFIG GROUP (left side):           CONFIG GROUP (right side):
-+-------------------+               +-------------------+
-| System Config     |               | Project Config    |
-| ~/.config/claude/ |               | .env              |
-+-------------------+               +-------------------+
-```
-
----
-
-## COLOR LEGEND
-
-| Color | Hex | Meaning |
-|-------|-----|---------|
-| Blue | #4A90D9 | Plugins |
-| Green | #7CB342 | MCP Servers |
-| Gray | #9E9E9E | External Systems |
-| Orange | #FF9800 | Configuration |

docs/references/PROJECT-SUMMARY.md

@@ -1,692 +0,0 @@
-# Project Management Plugins - Project Summary
-
-## Overview
-
-This project builds two Claude Code plugins that transform a proven 15-sprint workflow into reusable, distributable tools for managing software development with Gitea, Wiki.js, and agile methodologies.
-
-**Status:** Planning phase complete, ready for implementation
-
----
-
-## The Two Plugins
-
-### 1. projman (Single-Repository)
-
-**Purpose:** Project management for individual repositories
-**Users:** Developers, Team Leads
-**Build Order:** Build FIRST
-
-**Key Features:**
-- Sprint planning with AI agents
-- Issue creation with 43-label taxonomy
-- Lessons learned capture in Wiki.js
-- Branch-aware security model
-- Hybrid configuration system
-
-**Reference:** [PLUGIN-PROJMAN.md](./PLUGIN-PROJMAN.md)
-
-### 2. projman-pmo (Multi-Project)
-
-**Purpose:** PMO coordination across organization
-**Users:** PMO Coordinators, Engineering Managers, CTOs
-**Build Order:** Build SECOND (after projman validated)
-
-**Key Features:**
-- Cross-project status aggregation
-- Dependency tracking and visualization
-- Resource conflict detection
-- Release coordination
-- Company-wide lessons learned search
-
-**Reference:** [PLUGIN-PMO.md](./PLUGIN-PMO.md)
-
----
-
-## Core Architecture
-
-### Shared MCP Servers
-
-Both plugins share the same MCP server codebase at repository root (`mcp-servers/`):
-
-**1. Gitea MCP Server**
-- Issue management (CRUD operations)
-- Label taxonomy system (43 labels)
-- Mode detection (project vs company-wide)
-
-**Reference:** [MCP-GITEA.md](./MCP-GITEA.md)
-
-**2. Wiki.js MCP Server**
-- Documentation management
-- Lessons learned capture and search
-- GraphQL API integration
-- Company-wide knowledge base
-
-**Reference:** [MCP-WIKIJS.md](./MCP-WIKIJS.md)
-
-### Mode Detection
-
-The MCP servers detect their operating mode based on environment variables:
-
-**Project Mode (projman):**
-- `GITEA_REPO` present → operates on single repository
-- `WIKIJS_PROJECT` present → operates on single project path
-
-**Company Mode (pmo):**
-- No `GITEA_REPO` → operates on all repositories
-- No `WIKIJS_PROJECT` → operates on entire company namespace
-
----
-
-## Repository Structure
-
-```
-personal-projects/support-claude-mktplace/
-├── mcp-servers/                    # ← SHARED BY BOTH PLUGINS
-│   ├── gitea/                      # Gitea MCP Server
-│   │   ├── .venv/
-│   │   ├── requirements.txt
-│   │   ├── mcp_server/
-│   │   └── tests/
-│   └── wikijs/                     # Wiki.js MCP Server
-│       ├── .venv/
-│       ├── requirements.txt
-│       ├── mcp_server/
-│       └── tests/
-├── projman/                        # ← PROJECT PLUGIN
-│   ├── .claude-plugin/
-│   │   └── plugin.json
-│   ├── .mcp.json                   # Points to ../mcp-servers/
-│   ├── commands/
-│   │   ├── sprint-plan.md
-│   │   ├── sprint-start.md
-│   │   ├── sprint-status.md
-│   │   ├── sprint-close.md
-│   │   └── labels-sync.md
-│   ├── agents/
-│   │   ├── planner.md
-│   │   ├── orchestrator.md
-│   │   └── executor.md
-│   ├── skills/
-│   │   └── label-taxonomy/
-│   ├── README.md
-│   └── CONFIGURATION.md
-└── projman-pmo/                    # ← PMO PLUGIN
-    ├── .claude-plugin/
-    │   └── plugin.json
-    ├── .mcp.json                   # Points to ../mcp-servers/
-    ├── commands/
-    │   ├── pmo-status.md
-    │   ├── pmo-priorities.md
-    │   ├── pmo-dependencies.md
-    │   └── pmo-schedule.md
-    ├── agents/
-    │   └── pmo-coordinator.md
-    └── README.md
-```
-
----
-
-## Configuration Architecture
-
-### Hybrid Configuration System
-
-The plugins use a hybrid configuration approach that balances security and flexibility:
-
-**System-Level (Once per machine):**
-- `~/.config/claude/gitea.env` - Gitea credentials
-- `~/.config/claude/wikijs.env` - Wiki.js credentials
-
-**Project-Level (Per repository):**
-- `project-root/.env` - Repository and project paths
-
-**Benefits:**
-- Single token per service (update once)
-- Project isolation
-- Security (tokens never committed)
-- Easy multi-project setup
-
-### Configuration Example
-
-**System-Level:**
-```bash
-# ~/.config/claude/gitea.env
-GITEA_API_URL=https://gitea.example.com/api/v1
-GITEA_API_TOKEN=your_token
-GITEA_OWNER=bandit
-
-# ~/.config/claude/wikijs.env
-WIKIJS_API_URL=https://wiki.your-company.com/graphql
-WIKIJS_API_TOKEN=your_token
-WIKIJS_BASE_PATH=/your-org
-```
-
-**Project-Level:**
-```bash
-# project-root/.env (for projman)
-GITEA_REPO=cuisineflow
-WIKIJS_PROJECT=projects/cuisineflow
-
-# No .env needed for pmo (company-wide mode)
-```
-
----
-
-## Key Architectural Decisions
-
-### 1. Two MCP Servers (Shared)
-
-**Decision:** Separate Gitea and Wiki.js servers at repository root
-**Why:**
-- Clear separation of concerns
-- Independent configuration
-- Better maintainability
-- Professional architecture
-
-### 2. Python Implementation
-
-**Decision:** Python 3.10+ for MCP servers
-**Why:**
-- Modern async/await improvements
-- Better type hints support
-- Good balance of compatibility vs features
-- Widely available (released Oct 2021)
-- Most production servers have 3.10+ by now
-
-### 3. Wiki.js for Lessons Learned
-
-**Decision:** Use Wiki.js instead of Git-based Wiki
-**Why:**
-- Rich editor and search
-- Built-in tag system
-- Version history
-- Web-based collaboration
-- GraphQL API
-- Company-wide accessibility
-
-### 4. Hybrid Configuration
-
-**Decision:** System-level + project-level configuration
-**Why:**
-- Single token per service (security)
-- Per-project customization (flexibility)
-- Easy multi-project setup
-- Never commit tokens to git
-
-### 5. Mode Detection in MCP Servers
-
-**Decision:** Detect mode based on environment variables
-**Why:**
-- Same codebase for both plugins
-- No code duplication
-- Fix bugs once, both benefit
-- Clear separation of concerns
-
-### 6. Build Order: projman First
-
-**Decision:** Build projman completely before starting pmo
-**Why:**
-- Validate core functionality
-- Establish patterns
-- Reduce risk
-- PMO builds on projman foundation
-
----
-
-## The Three-Agent Model
-
-### Projman Agents
-
-**Planner Agent:**
-- Sprint planning and architecture analysis
-- Asks clarifying questions
-- Suggests appropriate labels
-- Creates Gitea issues
-- Searches relevant lessons learned
-
-**Orchestrator Agent:**
-- Sprint progress monitoring
-- Task coordination
-- Blocker identification
-- Git operations
-- Generates lean execution prompts
-
-**Executor Agent:**
-- Implementation guidance
-- Code review suggestions
-- Testing strategy
-- Quality standards enforcement
-- Documentation
-
-### PMO Agent
-
-**PMO Coordinator:**
-- Strategic view across all projects
-- Cross-project dependency tracking
-- Resource conflict detection
-- Release coordination
-- Delegates to projman agents for details
-
----
-
-## Wiki.js Structure
-
-```
-Wiki.js: https://wiki.your-company.com
-└── /your-org/
-    ├── projects/                       # Project-specific
-    │   ├── project-a/
-    │   │   ├── lessons-learned/
-    │   │   │   ├── sprints/
-    │   │   │   ├── patterns/
-    │   │   │   └── INDEX.md
-    │   │   └── documentation/
-    │   ├── project-b/
-    │   ├── project-c/
-    │   └── company-site/
-    ├── company/                        # Company-wide
-    │   ├── processes/
-    │   ├── standards/
-    │   └── tools/
-    └── shared/                         # Cross-project
-        ├── architecture-patterns/
-        ├── best-practices/
-        └── tech-stack/
-```
-
-**Reference:** [MCP-WIKIJS.md](./MCP-WIKIJS.md#wiki-js-structure)
-
----
-
-## Label Taxonomy System
-
-### Dynamic Label System (44 labels currently)
-
-Labels are **fetched dynamically from Gitea** at runtime via the `/labels-sync` command:
-
-**Organization Labels (28):**
-- Agent/2
-- Complexity/3
-- Efforts/5
-- Priority/4
-- Risk/3
-- Source/4
-- Type/6 (Bug, Feature, Refactor, Documentation, Test, Chore)
-
-**Repository Labels (16):**
-- Component/9 (Backend, Frontend, API, Database, Auth, Deploy, Testing, Docs, Infra)
-- Tech/7 (Python, JavaScript, Docker, PostgreSQL, Redis, Vue, FastAPI)
-
-### Type/Refactor Label
-
-**Organization-level label** for architectural work:
-- Service extraction
-- Architecture modifications
-- Code restructuring
-- Technical debt reduction
-
-**Note:** Label count may change. Always sync from Gitea using `/labels-sync` command. When new labels are detected, the command will explain changes and update suggestion logic.
-
-**Reference:** [PLUGIN-PROJMAN.md](./PLUGIN-PROJMAN.md#label-taxonomy-system)
-
----
-
-## Build Order & Phases
-
-### Build projman First (Phases 1-8)
-
-**Phase 1:** Core Infrastructure (MCP servers)
-**Phase 2:** Sprint Planning Commands
-**Phase 3:** Agent System
-**Phase 4:** Lessons Learned System
-**Phase 5:** Testing & Validation
-**Phase 6:** Documentation & Refinement
-**Phase 7:** Marketplace Preparation
-**Phase 8:** Production Hardening
-
-**Reference:** [PLUGIN-PROJMAN.md](./PLUGIN-PROJMAN.md#implementation-phases)
-
-### Build pmo Second (Phases 9-12)
-
-**Phase 9:** PMO Plugin Foundation
-**Phase 10:** PMO Commands & Workflows
-**Phase 11:** PMO Testing & Integration
-**Phase 12:** Production Deployment
-
-**Reference:** [PLUGIN-PMO.md](./PLUGIN-PMO.md#implementation-phases)
-
----
-
-## Quick Start Guide
-
-### 1. System Configuration
-
-```bash
-# Create config directory
-mkdir -p ~/.config/claude
-
-# Gitea config
-cat > ~/.config/claude/gitea.env << EOF
-GITEA_API_URL=https://gitea.example.com/api/v1
-GITEA_API_TOKEN=your_gitea_token
-GITEA_OWNER=bandit
-EOF
-
-# Wiki.js config
-cat > ~/.config/claude/wikijs.env << EOF
-WIKIJS_API_URL=https://wiki.your-company.com/graphql
-WIKIJS_API_TOKEN=your_wikijs_token
-WIKIJS_BASE_PATH=/your-org
-EOF
-
-# Secure files
-chmod 600 ~/.config/claude/*.env
-```
-
-### 2. Project Configuration
-
-```bash
-# In each project root (for projman)
-cat > .env << EOF
-GITEA_REPO=cuisineflow
-WIKIJS_PROJECT=projects/cuisineflow
-EOF
-
-# Add to .gitignore
-echo ".env" >> .gitignore
-```
-
-### 3. MCP Server Setup
-
-```bash
-# Gitea MCP Server
-cd mcp-servers/gitea
-python -m venv .venv
-source .venv/bin/activate
-pip install -r requirements.txt
-
-# Wiki.js MCP Server
-cd mcp-servers/wikijs
-python -m venv .venv
-source .venv/bin/activate
-pip install -r requirements.txt
-```
-
-### 4. Validate Setup
-
-```bash
-# Test MCP servers
-python -m mcp_server.server --test  # In each MCP directory
-
-# Test plugin loading
-claude plugin test projman
-claude plugin test projman-pmo
-```
-
----
-
-## Document Organization
-
-This documentation is organized into 4 focused files plus this summary:
-
-### 1. Gitea MCP Server Reference
-
-**File:** [MCP-GITEA.md](./MCP-GITEA.md)
-
-**Contains:**
-- Configuration setup
-- Python implementation
-- API client code
-- Issue and label tools
-- Testing strategies
-- Mode detection
-- Performance optimization
-
-**Use when:** Implementing or troubleshooting Gitea integration
-
-### 2. Wiki.js MCP Server Reference
-
-**File:** [MCP-WIKIJS.md](./MCP-WIKIJS.md)
-
-**Contains:**
-- Configuration setup
-- GraphQL client implementation
-- Wiki.js structure
-- Lessons learned system
-- Documentation tools
-- Company-wide patterns
-- PMO multi-project methods
-
-**Use when:** Implementing or troubleshooting Wiki.js integration
-
-### 3. Projman Plugin Reference
-
-**File:** [PLUGIN-PROJMAN.md](./PLUGIN-PROJMAN.md)
-
-**Contains:**
-- Plugin structure
-- Commands (sprint-plan, sprint-start, sprint-status, sprint-close, labels-sync)
-- Three agents (planner, orchestrator, executor)
-- Sprint workflow
-- Label taxonomy
-- Branch-aware security
-- Implementation phases 1-8
-
-**Use when:** Building or using the projman plugin
-
-### 4. PMO Plugin Reference
-
-**File:** [PLUGIN-PMO.md](./PLUGIN-PMO.md)
-
-**Contains:**
-- PMO plugin structure
-- Multi-project commands
-- PMO coordinator agent
-- Cross-project coordination
-- Dependency tracking
-- Resource conflict detection
-- Implementation phases 9-12
-
-**Use when:** Building or using the projman-pmo plugin
-
-### 5. This Summary
-
-**File:** PROJECT-SUMMARY.md (this document)
-
-**Contains:**
-- Project overview
-- Architecture decisions
-- Configuration approach
-- Quick start guide
-- References to detailed docs
-
-**Use when:** Getting started or need high-level overview
-
----
-
-## Key Success Metrics
-
-### Technical Metrics
-
-- Sprint planning time reduced by 40%
-- Manual steps eliminated: 10+ per sprint
-- Lessons learned capture rate: 100% (vs 0% before)
-- Label accuracy on issues: 90%+
-- Configuration setup time: < 5 minutes
-
-### User Metrics
-
-- User satisfaction: Better than current manual workflow
-- Learning curve: < 1 hour to basic proficiency
-- Error rate: < 5% incorrect operations
-- Adoption rate: 100% team adoption within 1 month
-
-### PMO Metrics
-
-- Cross-project visibility: 100% (vs fragmented before)
-- Dependency detection: Automated (vs manual tracking)
-- Resource conflict identification: Proactive (vs reactive)
-- Release coordination: Streamlined (vs ad-hoc)
-
----
-
-## Critical Lessons from 15 Sprints
-
-### Why Lessons Learned Is Critical
-
-After 15 sprints without systematic lesson capture, repeated mistakes occurred:
-- Claude Code infinite loops on similar issues: 2-3 times
-- Same architectural mistakes: Multiple occurrences
-- Forgotten optimizations: Re-discovered each time
-
-**Solution:** Mandatory lessons learned capture at sprint close, searchable at sprint start
-
-### Branch Detection Must Be 100% Reliable
-
-Production accidents are unacceptable. Branch-aware security prevents:
-- Accidental code changes on production branch
-- Sprint planning on wrong branch
-- Deployment mistakes
-
-**Implementation:** Two layers - CLAUDE.md (file-level) + Plugin agents (tool-level)
-
-### Configuration Complexity Is a Blocker
-
-Previous attempts failed due to:
-- Complex per-project setup
-- Token management overhead
-- Multiple configuration files
-
-**Solution:** Hybrid approach - system-level tokens + simple project-level paths
-
----
-
-## Next Steps
-
-### Immediate Actions
-
-1. **Set up system configuration** (Gitea + Wiki.js tokens)
-2. **Create Wiki.js base structure** at `/your-org`
-3. **Begin Phase 1.1a** - Gitea MCP Server implementation
-4. **Begin Phase 1.1b** - Wiki.js MCP Server implementation
-
-### Phase Execution
-
-1. **Phases 1-4:** Build core projman functionality
-2. **Phase 5:** Validate with real sprint (e.g., Intuit Engine extraction)
-3. **Phases 6-8:** Polish, document, and harden projman
-4. **Phases 9-12:** Build and validate pmo plugin
-
-### Validation Points
-
-- **After Phase 1:** MCP servers working and tested
-- **After Phase 4:** Complete projman workflow end-to-end
-- **After Phase 5:** Real sprint successfully managed
-- **After Phase 8:** Production-ready projman
-- **After Phase 11:** Multi-project coordination validated
-- **After Phase 12:** Complete system operational
-
----
-
-## Implementation Decisions (Pre-Development)
-
-These decisions were finalized before development:
-
-### 1. Python Version: 3.10+
-- **Rationale:** Balance of modern features and wide availability
-- **Benefits:** Modern async, good type hints, widely deployed
-- **Minimum:** Python 3.10.0
-
-### 2. Wiki.js Base Structure: Needs Creation
-- **Status:** `/your-org` structure does NOT exist yet
-- **Action:** Run `setup_wiki_structure.py` during Phase 1.1b
-- **Script:** See MCP-WIKIJS.md for complete setup script
-- **Post-setup:** Verify at https://wiki.your-company.com/your-org
-
-### 3. Testing Strategy: Both Mocks and Real APIs
-- **Unit tests:** Use mocks for fast feedback during development
-- **Integration tests:** Use real Gitea/Wiki.js APIs for validation
-- **CI/CD:** Run both test suites
-- **Developers:** Can skip integration tests locally if needed
-- **Markers:** Use pytest markers (`@pytest.mark.integration`)
-
-### 4. Token Permissions: Confirmed
-- **Gitea token:**
-  - `repo` (all) - Read/write repositories, issues, labels
-  - `read:org` - Organization information and labels
-  - `read:user` - User information
-- **Wiki.js token:**
-  - Read/create/update pages
-  - Manage tags
-  - Search access
-
-### 5. Label System: Dynamic (44 labels)
-- **Current count:** 44 labels (28 org + 16 repo)
-- **Approach:** Fetch dynamically via API, never hardcode
-- **Sync:** `/labels-sync` command updates local reference and suggestion logic
-- **New labels:** Command explains changes and asks for confirmation
-
-### 6. Branch Detection: Defense in Depth
-- **Layer 1:** MCP tools check branch and block operations
-- **Layer 2:** Agent prompts check branch and warn users
-- **Layer 3:** CLAUDE.md provides context (third layer)
-- **Rationale:** Multiple layers prevent production accidents
-
----
-
-## Important Reminders
-
-1. **Build projman FIRST** - Don't start pmo until projman is validated
-2. **MCP servers are SHARED** - Located at `mcp-servers/`, not inside plugins
-3. **Lessons learned is critical** - Prevents repeated mistakes
-4. **Test with real work** - Validate with actual sprints, not just unit tests
-5. **Security first** - Branch detection must be 100% reliable
-6. **Keep it simple** - Avoid over-engineering, focus on proven workflow
-7. **Python 3.10+** - Minimum version requirement
-8. **Wiki.js setup** - Must run setup script before projman works
-
----
-
-## Getting Help
-
-### Documentation Structure
-
-**Need details on:**
-- Gitea integration → [MCP-GITEA.md](./MCP-GITEA.md)
-- Wiki.js integration → [MCP-WIKIJS.md](./MCP-WIKIJS.md)
-- Projman usage → [PLUGIN-PROJMAN.md](./PLUGIN-PROJMAN.md)
-- PMO usage → [PLUGIN-PMO.md](./PLUGIN-PMO.md)
-- Overview → This document
-
-### Quick Reference
-
-| Question | Reference |
-|----------|-----------|
-| How do I set up configuration? | This document, "Quick Start Guide" |
-| What's the repository structure? | This document, "Repository Structure" |
-| How do Gitea tools work? | [MCP-GITEA.md](./MCP-GITEA.md) |
-| How do Wiki.js tools work? | [MCP-WIKIJS.md](./MCP-WIKIJS.md) |
-| How do I use sprint commands? | [PLUGIN-PROJMAN.md](./PLUGIN-PROJMAN.md#commands) |
-| How do agents work? | [PLUGIN-PROJMAN.md](./PLUGIN-PROJMAN.md#three-agent-model) |
-| How do I coordinate multiple projects? | [PLUGIN-PMO.md](./PLUGIN-PMO.md) |
-| What's the build order? | This document, "Build Order & Phases" |
-
----
-
-## Project Timeline
-
-**Planning:** Complete ✅
-**Phase 1-8 (projman):** 6-8 weeks estimated
-**Phase 9-12 (pmo):** 2-4 weeks estimated
-**Total:** 8-12 weeks from start to production
-
-**Note:** No fixed deadlines - work at sustainable pace and validate thoroughly
-
----
-
-## You're Ready!
-
-You have everything you need to build the projman and projman-pmo plugins. All architectural decisions are finalized and documented.
-
-**Start here:** [MCP-GITEA.md](./MCP-GITEA.md) - Set up Gitea MCP Server
-
-Good luck with the build! 🚀

mcp-servers/contract-validator/.doc-guardian-queue

@@ -0,0 +1,20 @@
+2026-01-26T14:36:42 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/mcp_server/parse_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
+2026-01-26T14:37:38 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/mcp_server/parse_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
+2026-01-26T14:37:48 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/mcp_server/parse_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
+2026-01-26T14:38:05 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/mcp_server/parse_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
+2026-01-26T14:38:55 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/mcp_server/parse_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
+2026-01-26T14:39:35 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/mcp_server/parse_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
+2026-01-26T14:40:19 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/mcp_server/parse_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
+2026-01-26T15:02:30 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/tests/test_parse_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
+2026-01-26T15:02:37 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/tests/test_parse_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
+2026-01-26T15:03:41 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/tests/test_report_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
+2026-02-02T10:56:19 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/mcp_server/validation_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
+2026-02-02T10:57:49 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/tests/test_validation_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
+2026-02-02T10:58:22 | skills | /home/lmiranda/claude-plugins-work/plugins/contract-validator/skills/mcp-tools-reference.md | README.md
+2026-02-02T10:58:38 | skills | /home/lmiranda/claude-plugins-work/plugins/contract-validator/skills/validation-rules.md | README.md
+2026-02-02T10:59:13 | .claude-plugin | /home/lmiranda/claude-plugins-work/.claude-plugin/marketplace.json | CLAUDE.md .claude-plugin/marketplace.json
+2026-02-02T13:55:33 | skills | /home/lmiranda/claude-plugins-work/plugins/projman/skills/visual-output.md | README.md
+2026-02-02T13:55:41 | agents | /home/lmiranda/claude-plugins-work/plugins/projman/agents/planner.md | README.md CLAUDE.md
+2026-02-02T13:55:55 | agents | /home/lmiranda/claude-plugins-work/plugins/projman/agents/orchestrator.md | README.md CLAUDE.md
+2026-02-02T13:56:14 | agents | /home/lmiranda/claude-plugins-work/plugins/projman/agents/executor.md | README.md CLAUDE.md
+2026-02-02T13:56:34 | agents | /home/lmiranda/claude-plugins-work/plugins/projman/agents/code-reviewer.md | README.md CLAUDE.md

mcp-servers/contract-validator/mcp_server/__init__.py

@@ -0,0 +1,3 @@
+"""Contract Validator MCP Server - Cross-plugin compatibility validation."""
+
+__version__ = "1.0.0"

mcp-servers/contract-validator/mcp_server/parse_tools.py

@@ -0,0 +1,415 @@
+"""
+Parse tools for extracting interfaces from plugin documentation.
+
+Provides structured extraction of:
+- Plugin interfaces from README.md (commands, agents, tools)
+- Agent definitions from CLAUDE.md (tool sequences, workflows)
+"""
+import re
+import os
+from pathlib import Path
+from typing import Optional
+from pydantic import BaseModel
+
+
+class ToolInfo(BaseModel):
+    """Information about a single tool"""
+    name: str
+    category: Optional[str] = None
+    description: Optional[str] = None
+
+
+class CommandInfo(BaseModel):
+    """Information about a plugin command"""
+    name: str
+    description: Optional[str] = None
+
+
+class AgentInfo(BaseModel):
+    """Information about a plugin agent"""
+    name: str
+    description: Optional[str] = None
+    tools: list[str] = []
+
+
+class PluginInterface(BaseModel):
+    """Structured plugin interface extracted from README"""
+    plugin_name: str
+    description: Optional[str] = None
+    commands: list[CommandInfo] = []
+    agents: list[AgentInfo] = []
+    tools: list[ToolInfo] = []
+    tool_categories: dict[str, list[str]] = {}
+    features: list[str] = []
+
+
+class ClaudeMdAgent(BaseModel):
+    """Agent definition extracted from CLAUDE.md"""
+    name: str
+    personality: Optional[str] = None
+    responsibilities: list[str] = []
+    tool_refs: list[str] = []
+    workflow_steps: list[str] = []
+
+
+class ParseTools:
+    """Tools for parsing plugin documentation"""
+
+    async def parse_plugin_interface(self, plugin_path: str) -> dict:
+        """
+        Parse plugin README.md to extract interface declarations.
+
+        Args:
+            plugin_path: Path to plugin directory or README.md file
+
+        Returns:
+            Structured interface with commands, agents, tools, etc.
+        """
+        # Resolve path to README
+        path = Path(plugin_path)
+        if path.is_dir():
+            readme_path = path / "README.md"
+        else:
+            readme_path = path
+
+        if not readme_path.exists():
+            return {
+                "error": f"README.md not found at {readme_path}",
+                "plugin_path": plugin_path
+            }
+
+        content = readme_path.read_text()
+        plugin_name = self._extract_plugin_name(content, path)
+
+        interface = PluginInterface(
+            plugin_name=plugin_name,
+            description=self._extract_description(content),
+            commands=self._extract_commands(content),
+            agents=self._extract_agents_from_readme(content),
+            tools=self._extract_tools(content),
+            tool_categories=self._extract_tool_categories(content),
+            features=self._extract_features(content)
+        )
+
+        return interface.model_dump()
+
+    async def parse_claude_md_agents(self, claude_md_path: str) -> dict:
+        """
+        Parse CLAUDE.md to extract agent definitions and tool sequences.
+
+        Args:
+            claude_md_path: Path to CLAUDE.md file
+
+        Returns:
+            List of agents with their tool sequences
+        """
+        path = Path(claude_md_path)
+
+        if not path.exists():
+            return {
+                "error": f"CLAUDE.md not found at {path}",
+                "claude_md_path": claude_md_path
+            }
+
+        content = path.read_text()
+        agents = self._extract_agents_from_claude_md(content)
+
+        return {
+            "file": str(path),
+            "agents": [a.model_dump() for a in agents],
+            "agent_count": len(agents)
+        }
+
+    def _extract_plugin_name(self, content: str, path: Path) -> str:
+        """Extract plugin name from content or path"""
+        # Try to get from H1 header
+        match = re.search(r'^#\s+(.+?)(?:\s+Plugin|\s*$)', content, re.MULTILINE)
+        if match:
+            name = match.group(1).strip()
+            # Handle cases like "# data-platform Plugin"
+            name = re.sub(r'\s*Plugin\s*$', '', name, flags=re.IGNORECASE)
+            return name
+
+        # Fall back to directory name
+        if path.is_dir():
+            return path.name
+        return path.parent.name
+
+    def _extract_description(self, content: str) -> Optional[str]:
+        """Extract plugin description from first paragraph after title"""
+        # Get content after H1, before first H2
+        match = re.search(r'^#\s+.+?\n\n(.+?)(?=\n##|\n\n##|\Z)', content, re.MULTILINE | re.DOTALL)
+        if match:
+            desc = match.group(1).strip()
+            # Take first paragraph only
+            desc = desc.split('\n\n')[0].strip()
+            return desc
+        return None
+
+    def _extract_commands(self, content: str) -> list[CommandInfo]:
+        """Extract commands from Commands section"""
+        commands = []
+
+        # Find Commands section
+        commands_section = self._extract_section(content, "Commands")
+        if not commands_section:
+            return commands
+
+        # Parse table format: | Command | Description |
+        # Only match actual command names (start with / or alphanumeric)
+        table_pattern = r'\|\s*`?(/[a-z][-a-z0-9]*)`?\s*\|\s*([^|]+)\s*\|'
+        for match in re.finditer(table_pattern, commands_section):
+            cmd_name = match.group(1).strip()
+            desc = match.group(2).strip()
+
+            # Skip header row and separators
+            if cmd_name.lower() in ('command', 'commands') or cmd_name.startswith('-'):
+                continue
+
+            commands.append(CommandInfo(
+                name=cmd_name,
+                description=desc
+            ))
+
+        # Also look for ### `/command-name` format (with backticks)
+        cmd_header_pattern = r'^###\s+`(/[a-z][-a-z0-9]*)`\s*\n(.+?)(?=\n###|\n##|\Z)'
+        for match in re.finditer(cmd_header_pattern, commands_section, re.MULTILINE | re.DOTALL):
+            cmd_name = match.group(1).strip()
+            desc_block = match.group(2).strip()
+            # Get first line or paragraph as description
+            desc = desc_block.split('\n')[0].strip()
+
+            # Don't duplicate if already found in table
+            if not any(c.name == cmd_name for c in commands):
+                commands.append(CommandInfo(name=cmd_name, description=desc))
+
+        # Also look for ### /command-name format (without backticks)
+        cmd_header_pattern2 = r'^###\s+(/[a-z][-a-z0-9]*)\s*\n(.+?)(?=\n###|\n##|\Z)'
+        for match in re.finditer(cmd_header_pattern2, commands_section, re.MULTILINE | re.DOTALL):
+            cmd_name = match.group(1).strip()
+            desc_block = match.group(2).strip()
+            # Get first line or paragraph as description
+            desc = desc_block.split('\n')[0].strip()
+
+            # Don't duplicate if already found in table
+            if not any(c.name == cmd_name for c in commands):
+                commands.append(CommandInfo(name=cmd_name, description=desc))
+
+        return commands
+
+    def _extract_agents_from_readme(self, content: str) -> list[AgentInfo]:
+        """Extract agents from Agents section in README"""
+        agents = []
+
+        # Find Agents section
+        agents_section = self._extract_section(content, "Agents")
+        if not agents_section:
+            return agents
+
+        # Parse table format: | Agent | Description |
+        # Only match actual agent names (alphanumeric with dashes/underscores)
+        table_pattern = r'\|\s*`?([a-z][-a-z0-9_]*)`?\s*\|\s*([^|]+)\s*\|'
+        for match in re.finditer(table_pattern, agents_section):
+            agent_name = match.group(1).strip()
+            desc = match.group(2).strip()
+
+            # Skip header row and separators
+            if agent_name.lower() in ('agent', 'agents') or agent_name.startswith('-'):
+                continue
+
+            agents.append(AgentInfo(name=agent_name, description=desc))
+
+        return agents
+
+    def _extract_tools(self, content: str) -> list[ToolInfo]:
+        """Extract tool list from Tools Summary or similar section"""
+        tools = []
+
+        # Find Tools Summary section
+        tools_section = self._extract_section(content, "Tools Summary")
+        if not tools_section:
+            tools_section = self._extract_section(content, "Tools")
+        if not tools_section:
+            tools_section = self._extract_section(content, "MCP Server Tools")
+
+        if not tools_section:
+            return tools
+
+        # Parse category headers: ### category (N tools)
+        category_pattern = r'###\s*(.+?)\s*(?:\((\d+)\s*tools?\))?\s*\n([^#]+)'
+        for match in re.finditer(category_pattern, tools_section):
+            category = match.group(1).strip()
+            tool_list_text = match.group(3).strip()
+
+            # Extract tool names from backtick lists
+            tool_names = re.findall(r'`([a-z_]+)`', tool_list_text)
+            for name in tool_names:
+                tools.append(ToolInfo(name=name, category=category))
+
+        # Also look for inline tool lists without categories
+        inline_pattern = r'`([a-z_]+)`'
+        all_tool_names = set(t.name for t in tools)
+        for match in re.finditer(inline_pattern, tools_section):
+            name = match.group(1)
+            if name not in all_tool_names:
+                tools.append(ToolInfo(name=name))
+                all_tool_names.add(name)
+
+        return tools
+
+    def _extract_tool_categories(self, content: str) -> dict[str, list[str]]:
+        """Extract tool categories with their tool lists"""
+        categories = {}
+
+        tools_section = self._extract_section(content, "Tools Summary")
+        if not tools_section:
+            tools_section = self._extract_section(content, "Tools")
+        if not tools_section:
+            return categories
+
+        # Parse category headers: ### category (N tools)
+        category_pattern = r'###\s*(.+?)\s*(?:\((\d+)\s*tools?\))?\s*\n([^#]+)'
+        for match in re.finditer(category_pattern, tools_section):
+            category = match.group(1).strip()
+            tool_list_text = match.group(3).strip()
+
+            # Extract tool names from backtick lists
+            tool_names = re.findall(r'`([a-z_]+)`', tool_list_text)
+            if tool_names:
+                categories[category] = tool_names
+
+        return categories
+
+    def _extract_features(self, content: str) -> list[str]:
+        """Extract features from Features section"""
+        features = []
+
+        features_section = self._extract_section(content, "Features")
+        if not features_section:
+            return features
+
+        # Parse bullet points
+        bullet_pattern = r'^[-*]\s+\*\*(.+?)\*\*'
+        for match in re.finditer(bullet_pattern, features_section, re.MULTILINE):
+            features.append(match.group(1).strip())
+
+        return features
+
+    def _extract_section(self, content: str, section_name: str) -> Optional[str]:
+        """Extract content of a markdown section by header name"""
+        # Match ## Section Name - include all content until next ## (same level or higher)
+        pattern = rf'^##\s+{re.escape(section_name)}(?:\s*\([^)]*\))?\s*\n(.*?)(?=\n##[^#]|\Z)'
+        match = re.search(pattern, content, re.MULTILINE | re.DOTALL | re.IGNORECASE)
+        if match:
+            return match.group(1).strip()
+
+        # Try ### level - include content until next ## or ###
+        pattern = rf'^###\s+{re.escape(section_name)}(?:\s*\([^)]*\))?\s*\n(.*?)(?=\n##|\n###[^#]|\Z)'
+        match = re.search(pattern, content, re.MULTILINE | re.DOTALL | re.IGNORECASE)
+        if match:
+            return match.group(1).strip()
+
+        return None
+
+    def _extract_agents_from_claude_md(self, content: str) -> list[ClaudeMdAgent]:
+        """Extract agent definitions from CLAUDE.md"""
+        agents = []
+
+        # Look for Four-Agent Model section specifically
+        # Match section headers like "### Four-Agent Model (projman)" or "## Four-Agent Model"
+        agent_model_match = re.search(
+            r'^##[#]?\s+Four-Agent Model.*?\n(.*?)(?=\n##[^#]|\Z)',
+            content, re.MULTILINE | re.DOTALL
+        )
+        agent_model_section = agent_model_match.group(1) if agent_model_match else None
+
+        if agent_model_section:
+            # Parse agent table within this section
+            # | **Planner** | Thoughtful, methodical | Sprint planning, ... |
+            # Match rows where first cell starts with ** (bold) and contains a capitalized word
+            agent_table_pattern = r'\|\s*\*\*([A-Z][a-zA-Z\s]+?)\*\*\s*\|\s*([^|]+)\s*\|\s*([^|]+)\s*\|'
+
+            for match in re.finditer(agent_table_pattern, agent_model_section):
+                agent_name = match.group(1).strip()
+                personality = match.group(2).strip()
+                responsibilities = match.group(3).strip()
+
+                # Skip header rows and separator rows
+                if agent_name.lower() in ('agent', 'agents', '---', '-', ''):
+                    continue
+                if 'personality' in personality.lower() or '---' in personality:
+                    continue
+
+                # Skip if personality looks like tool names (contains backticks)
+                if '`' in personality:
+                    continue
+
+                # Extract tool references from responsibilities
+                tool_refs = re.findall(r'`([a-z_]+)`', responsibilities)
+
+                # Split responsibilities by comma
+                resp_list = [r.strip() for r in responsibilities.split(',')]
+
+                agents.append(ClaudeMdAgent(
+                    name=agent_name,
+                    personality=personality,
+                    responsibilities=resp_list,
+                    tool_refs=tool_refs
+                ))
+
+        # Also look for agents table in ## Agents section
+        agents_section = self._extract_section(content, "Agents")
+        if agents_section:
+            # Parse table: | Agent | Description |
+            table_pattern = r'\|\s*`?([a-z][-a-z0-9_]+)`?\s*\|\s*([^|]+)\s*\|'
+            for match in re.finditer(table_pattern, agents_section):
+                agent_name = match.group(1).strip()
+                desc = match.group(2).strip()
+
+                # Skip header rows
+                if agent_name.lower() in ('agent', 'agents', '---', '-'):
+                    continue
+
+                # Check if agent already exists
+                if not any(a.name.lower() == agent_name.lower() for a in agents):
+                    agents.append(ClaudeMdAgent(
+                        name=agent_name,
+                        responsibilities=[desc] if desc else []
+                    ))
+
+        # Look for workflow sections to enrich agent data
+        workflow_section = self._extract_section(content, "Workflow")
+        if workflow_section:
+            # Parse numbered steps
+            step_pattern = r'^\d+\.\s+(.+?)$'
+            workflow_steps = re.findall(step_pattern, workflow_section, re.MULTILINE)
+
+            # Associate workflow steps with agents mentioned
+            for agent in agents:
+                for step in workflow_steps:
+                    if agent.name.lower() in step.lower():
+                        agent.workflow_steps.append(step)
+                        # Extract any tool references in the step
+                        step_tools = re.findall(r'`([a-z_]+)`', step)
+                        agent.tool_refs.extend(t for t in step_tools if t not in agent.tool_refs)
+
+        # Look for agent-specific sections (### Planner Agent)
+        agent_section_pattern = r'^###?\s+([A-Z][a-z]+(?:\s+[A-Z][a-z]+)?)\s+Agent\s*\n(.*?)(?=\n##|\n###|\Z)'
+        for match in re.finditer(agent_section_pattern, content, re.MULTILINE | re.DOTALL):
+            agent_name = match.group(1).strip()
+            section_content = match.group(2).strip()
+
+            # Check if agent already exists
+            existing = next((a for a in agents if a.name.lower() == agent_name.lower()), None)
+            if existing:
+                # Add tool refs from this section
+                tool_refs = re.findall(r'`([a-z_]+)`', section_content)
+                existing.tool_refs.extend(t for t in tool_refs if t not in existing.tool_refs)
+            else:
+                tool_refs = re.findall(r'`([a-z_]+)`', section_content)
+                agents.append(ClaudeMdAgent(
+                    name=agent_name,
+                    tool_refs=tool_refs
+                ))
+
+        return agents

mcp-servers/contract-validator/mcp_server/report_tools.py

@@ -0,0 +1,337 @@
+"""
+Report tools for generating compatibility reports and listing issues.
+
+Provides:
+- generate_compatibility_report: Full marketplace validation report
+- list_issues: Filtered issue listing
+"""
+import os
+from pathlib import Path
+from datetime import datetime
+from typing import Optional
+from pydantic import BaseModel
+
+from .parse_tools import ParseTools
+from .validation_tools import ValidationTools, IssueSeverity, IssueType, ValidationIssue
+
+
+class ReportSummary(BaseModel):
+    """Summary statistics for a report"""
+    total_plugins: int = 0
+    total_commands: int = 0
+    total_agents: int = 0
+    total_tools: int = 0
+    total_issues: int = 0
+    errors: int = 0
+    warnings: int = 0
+    info: int = 0
+
+
+class ReportTools:
+    """Tools for generating reports and listing issues"""
+
+    def __init__(self):
+        self.parse_tools = ParseTools()
+        self.validation_tools = ValidationTools()
+
+    async def generate_compatibility_report(
+        self,
+        marketplace_path: str,
+        format: str = "markdown"
+    ) -> dict:
+        """
+        Generate a comprehensive compatibility report for all plugins.
+
+        Args:
+            marketplace_path: Path to marketplace root directory
+            format: Output format ("markdown" or "json")
+
+        Returns:
+            Full compatibility report with all findings
+        """
+        marketplace = Path(marketplace_path)
+        plugins_dir = marketplace / "plugins"
+
+        if not plugins_dir.exists():
+            return {
+                "error": f"Plugins directory not found at {plugins_dir}",
+                "marketplace_path": marketplace_path
+            }
+
+        # Discover all plugins
+        plugins = []
+        for item in plugins_dir.iterdir():
+            if item.is_dir() and (item / ".claude-plugin").exists():
+                plugins.append(item)
+
+        if not plugins:
+            return {
+                "error": "No plugins found in marketplace",
+                "marketplace_path": marketplace_path
+            }
+
+        # Parse all plugin interfaces
+        interfaces = {}
+        all_issues = []
+        summary = ReportSummary(total_plugins=len(plugins))
+
+        for plugin_path in plugins:
+            interface = await self.parse_tools.parse_plugin_interface(str(plugin_path))
+            if "error" not in interface:
+                interfaces[interface["plugin_name"]] = interface
+                summary.total_commands += len(interface.get("commands", []))
+                summary.total_agents += len(interface.get("agents", []))
+                summary.total_tools += len(interface.get("tools", []))
+
+        # Run pairwise compatibility checks
+        plugin_names = list(interfaces.keys())
+        compatibility_results = []
+
+        for i, name_a in enumerate(plugin_names):
+            for name_b in plugin_names[i+1:]:
+                path_a = plugins_dir / self._find_plugin_dir(plugins_dir, name_a)
+                path_b = plugins_dir / self._find_plugin_dir(plugins_dir, name_b)
+
+                result = await self.validation_tools.validate_compatibility(
+                    str(path_a), str(path_b)
+                )
+
+                if "error" not in result:
+                    compatibility_results.append(result)
+                    all_issues.extend(result.get("issues", []))
+
+        # Parse CLAUDE.md if exists
+        claude_md = marketplace / "CLAUDE.md"
+        agents_from_claude = []
+        if claude_md.exists():
+            agents_result = await self.parse_tools.parse_claude_md_agents(str(claude_md))
+            if "error" not in agents_result:
+                agents_from_claude = agents_result.get("agents", [])
+
+                # Validate each agent
+                for agent in agents_from_claude:
+                    agent_result = await self.validation_tools.validate_agent_refs(
+                        agent["name"],
+                        str(claude_md),
+                        [str(p) for p in plugins]
+                    )
+                    if "error" not in agent_result:
+                        all_issues.extend(agent_result.get("issues", []))
+
+        # Count issues by severity
+        for issue in all_issues:
+            severity = issue.get("severity", "info")
+            if isinstance(severity, str):
+                severity_str = severity.lower()
+            else:
+                severity_str = severity.value if hasattr(severity, 'value') else str(severity).lower()
+
+            if "error" in severity_str:
+                summary.errors += 1
+            elif "warning" in severity_str:
+                summary.warnings += 1
+            else:
+                summary.info += 1
+
+        summary.total_issues = len(all_issues)
+
+        # Generate report
+        if format == "json":
+            return {
+                "generated_at": datetime.now().isoformat(),
+                "marketplace_path": marketplace_path,
+                "summary": summary.model_dump(),
+                "plugins": interfaces,
+                "compatibility_checks": compatibility_results,
+                "claude_md_agents": agents_from_claude,
+                "all_issues": all_issues
+            }
+        else:
+            # Generate markdown report
+            report = self._generate_markdown_report(
+                marketplace_path,
+                summary,
+                interfaces,
+                compatibility_results,
+                agents_from_claude,
+                all_issues
+            )
+            return {
+                "generated_at": datetime.now().isoformat(),
+                "marketplace_path": marketplace_path,
+                "summary": summary.model_dump(),
+                "report": report
+            }
+
+    def _find_plugin_dir(self, plugins_dir: Path, plugin_name: str) -> str:
+        """Find plugin directory by name (handles naming variations)"""
+        # Try exact match first
+        for item in plugins_dir.iterdir():
+            if item.is_dir():
+                if item.name.lower() == plugin_name.lower():
+                    return item.name
+                # Check plugin.json for name
+                plugin_json = item / ".claude-plugin" / "plugin.json"
+                if plugin_json.exists():
+                    import json
+                    try:
+                        data = json.loads(plugin_json.read_text())
+                        if data.get("name", "").lower() == plugin_name.lower():
+                            return item.name
+                    except:
+                        pass
+        return plugin_name
+
+    def _generate_markdown_report(
+        self,
+        marketplace_path: str,
+        summary: ReportSummary,
+        interfaces: dict,
+        compatibility_results: list,
+        agents: list,
+        issues: list
+    ) -> str:
+        """Generate markdown formatted report"""
+        lines = [
+            "# Contract Validation Report",
+            "",
+            f"**Generated:** {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}",
+            f"**Marketplace:** `{marketplace_path}`",
+            "",
+            "## Summary",
+            "",
+            f"| Metric | Count |",
+            f"|--------|-------|",
+            f"| Plugins | {summary.total_plugins} |",
+            f"| Commands | {summary.total_commands} |",
+            f"| Agents | {summary.total_agents} |",
+            f"| Tools | {summary.total_tools} |",
+            f"| **Issues** | **{summary.total_issues}** |",
+            f"| - Errors | {summary.errors} |",
+            f"| - Warnings | {summary.warnings} |",
+            f"| - Info | {summary.info} |",
+            "",
+        ]
+
+        # Plugin details
+        lines.extend([
+            "## Plugins",
+            "",
+        ])
+
+        for name, interface in interfaces.items():
+            cmds = len(interface.get("commands", []))
+            agents_count = len(interface.get("agents", []))
+            tools = len(interface.get("tools", []))
+            lines.append(f"### {name}")
+            lines.append("")
+            lines.append(f"- Commands: {cmds}")
+            lines.append(f"- Agents: {agents_count}")
+            lines.append(f"- Tools: {tools}")
+            lines.append("")
+
+        # Compatibility results
+        if compatibility_results:
+            lines.extend([
+                "## Compatibility Checks",
+                "",
+            ])
+
+            for result in compatibility_results:
+                status = "✓" if result.get("compatible", True) else "✗"
+                lines.append(f"### {result['plugin_a']} ↔ {result['plugin_b']} {status}")
+                lines.append("")
+
+                if result.get("shared_tools"):
+                    lines.append(f"- Shared tools: `{', '.join(result['shared_tools'])}`")
+                if result.get("issues"):
+                    for issue in result["issues"]:
+                        sev = issue.get("severity", "info")
+                        if hasattr(sev, 'value'):
+                            sev = sev.value
+                        lines.append(f"- [{sev.upper()}] {issue['message']}")
+                lines.append("")
+
+        # Issues section
+        if issues:
+            lines.extend([
+                "## All Issues",
+                "",
+                "| Severity | Type | Message |",
+                "|----------|------|---------|",
+            ])
+
+            for issue in issues:
+                sev = issue.get("severity", "info")
+                itype = issue.get("issue_type", "unknown")
+                msg = issue.get("message", "")
+
+                if hasattr(sev, 'value'):
+                    sev = sev.value
+                if hasattr(itype, 'value'):
+                    itype = itype.value
+
+                # Truncate message for table
+                msg_short = msg[:60] + "..." if len(msg) > 60 else msg
+                lines.append(f"| {sev} | {itype} | {msg_short} |")
+
+            lines.append("")
+
+        return "\n".join(lines)
+
+    async def list_issues(
+        self,
+        marketplace_path: str,
+        severity: str = "all",
+        issue_type: str = "all"
+    ) -> dict:
+        """
+        List validation issues with optional filtering.
+
+        Args:
+            marketplace_path: Path to marketplace root directory
+            severity: Filter by severity ("error", "warning", "info", "all")
+            issue_type: Filter by type ("missing_tool", "interface_mismatch", etc., "all")
+
+        Returns:
+            Filtered list of issues
+        """
+        # Generate full report first
+        report = await self.generate_compatibility_report(marketplace_path, format="json")
+
+        if "error" in report:
+            return report
+
+        all_issues = report.get("all_issues", [])
+
+        # Filter by severity
+        if severity != "all":
+            filtered = []
+            for issue in all_issues:
+                issue_sev = issue.get("severity", "info")
+                if hasattr(issue_sev, 'value'):
+                    issue_sev = issue_sev.value
+                if isinstance(issue_sev, str) and severity.lower() in issue_sev.lower():
+                    filtered.append(issue)
+            all_issues = filtered
+
+        # Filter by type
+        if issue_type != "all":
+            filtered = []
+            for issue in all_issues:
+                itype = issue.get("issue_type", "unknown")
+                if hasattr(itype, 'value'):
+                    itype = itype.value
+                if isinstance(itype, str) and issue_type.lower() in itype.lower():
+                    filtered.append(issue)
+            all_issues = filtered
+
+        return {
+            "marketplace_path": marketplace_path,
+            "filters": {
+                "severity": severity,
+                "issue_type": issue_type
+            },
+            "total_issues": len(all_issues),
+            "issues": all_issues
+        }

mcp-servers/contract-validator/mcp_server/server.py

@@ -0,0 +1,309 @@
+"""
+MCP Server entry point for Contract Validator.
+
+Provides cross-plugin compatibility validation and Claude.md agent verification
+tools to Claude Code via JSON-RPC 2.0 over stdio.
+"""
+import asyncio
+import logging
+import json
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import Tool, TextContent
+
+from .parse_tools import ParseTools
+from .validation_tools import ValidationTools
+from .report_tools import ReportTools
+
+# Suppress noisy MCP validation warnings on stderr
+logging.basicConfig(level=logging.INFO)
+logging.getLogger("root").setLevel(logging.ERROR)
+logging.getLogger("mcp").setLevel(logging.ERROR)
+logger = logging.getLogger(__name__)
+
+
+class ContractValidatorMCPServer:
+    """MCP Server for cross-plugin compatibility validation"""
+
+    def __init__(self):
+        self.server = Server("contract-validator-mcp")
+        self.parse_tools = ParseTools()
+        self.validation_tools = ValidationTools()
+        self.report_tools = ReportTools()
+
+    async def initialize(self):
+        """Initialize server."""
+        logger.info("Contract Validator MCP Server initialized")
+
+    def setup_tools(self):
+        """Register all available tools with the MCP server"""
+
+        @self.server.list_tools()
+        async def list_tools() -> list[Tool]:
+            """Return list of available tools"""
+            tools = [
+                # Parse tools (to be implemented in #186)
+                Tool(
+                    name="parse_plugin_interface",
+                    description="Parse plugin README.md to extract interface declarations (inputs, outputs, tools)",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "plugin_path": {
+                                "type": "string",
+                                "description": "Path to plugin directory or README.md"
+                            }
+                        },
+                        "required": ["plugin_path"]
+                    }
+                ),
+                Tool(
+                    name="parse_claude_md_agents",
+                    description="Parse Claude.md to extract agent definitions and their tool sequences",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "claude_md_path": {
+                                "type": "string",
+                                "description": "Path to CLAUDE.md file"
+                            }
+                        },
+                        "required": ["claude_md_path"]
+                    }
+                ),
+                # Validation tools (to be implemented in #187)
+                Tool(
+                    name="validate_compatibility",
+                    description="Validate compatibility between two plugin interfaces",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "plugin_a": {
+                                "type": "string",
+                                "description": "Path to first plugin"
+                            },
+                            "plugin_b": {
+                                "type": "string",
+                                "description": "Path to second plugin"
+                            }
+                        },
+                        "required": ["plugin_a", "plugin_b"]
+                    }
+                ),
+                Tool(
+                    name="validate_agent_refs",
+                    description="Validate that all tool references in an agent definition exist",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "agent_name": {
+                                "type": "string",
+                                "description": "Name of agent to validate"
+                            },
+                            "claude_md_path": {
+                                "type": "string",
+                                "description": "Path to CLAUDE.md containing agent"
+                            },
+                            "plugin_paths": {
+                                "type": "array",
+                                "items": {"type": "string"},
+                                "description": "Paths to available plugins"
+                            }
+                        },
+                        "required": ["agent_name", "claude_md_path"]
+                    }
+                ),
+                Tool(
+                    name="validate_data_flow",
+                    description="Validate data flow through an agent's tool sequence",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "agent_name": {
+                                "type": "string",
+                                "description": "Name of agent to validate"
+                            },
+                            "claude_md_path": {
+                                "type": "string",
+                                "description": "Path to CLAUDE.md containing agent"
+                            }
+                        },
+                        "required": ["agent_name", "claude_md_path"]
+                    }
+                ),
+                Tool(
+                    name="validate_workflow_integration",
+                    description="Validate that a domain plugin exposes the required advisory interfaces (gate command, review command, advisory agent) expected by projman's domain-consultation skill. Also checks gate contract version compatibility.",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "plugin_path": {
+                                "type": "string",
+                                "description": "Path to the domain plugin directory"
+                            },
+                            "domain_label": {
+                                "type": "string",
+                                "description": "The Domain/* label it claims to handle, e.g. Domain/Viz"
+                            },
+                            "expected_contract": {
+                                "type": "string",
+                                "description": "Expected contract version (e.g., 'v1'). If provided, validates the gate command's contract matches."
+                            }
+                        },
+                        "required": ["plugin_path", "domain_label"]
+                    }
+                ),
+                # Report tools (to be implemented in #188)
+                Tool(
+                    name="generate_compatibility_report",
+                    description="Generate a comprehensive compatibility report for all plugins",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "marketplace_path": {
+                                "type": "string",
+                                "description": "Path to marketplace root directory"
+                            },
+                            "format": {
+                                "type": "string",
+                                "enum": ["markdown", "json"],
+                                "default": "markdown",
+                                "description": "Output format"
+                            }
+                        },
+                        "required": ["marketplace_path"]
+                    }
+                ),
+                Tool(
+                    name="list_issues",
+                    description="List validation issues with optional filtering",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "marketplace_path": {
+                                "type": "string",
+                                "description": "Path to marketplace root directory"
+                            },
+                            "severity": {
+                                "type": "string",
+                                "enum": ["error", "warning", "info", "all"],
+                                "default": "all",
+                                "description": "Filter by severity"
+                            },
+                            "issue_type": {
+                                "type": "string",
+                                "enum": ["missing_tool", "interface_mismatch", "optional_dependency", "undeclared_output", "all"],
+                                "default": "all",
+                                "description": "Filter by issue type"
+                            }
+                        },
+                        "required": ["marketplace_path"]
+                    }
+                )
+            ]
+            return tools
+
+        @self.server.call_tool()
+        async def call_tool(name: str, arguments: dict) -> list[TextContent]:
+            """Handle tool invocation."""
+            try:
+                # All tools return placeholder responses for now
+                # Actual implementation will be added in issues #186, #187, #188
+
+                if name == "parse_plugin_interface":
+                    result = await self._parse_plugin_interface(**arguments)
+                elif name == "parse_claude_md_agents":
+                    result = await self._parse_claude_md_agents(**arguments)
+                elif name == "validate_compatibility":
+                    result = await self._validate_compatibility(**arguments)
+                elif name == "validate_agent_refs":
+                    result = await self._validate_agent_refs(**arguments)
+                elif name == "validate_data_flow":
+                    result = await self._validate_data_flow(**arguments)
+                elif name == "validate_workflow_integration":
+                    result = await self._validate_workflow_integration(**arguments)
+                elif name == "generate_compatibility_report":
+                    result = await self._generate_compatibility_report(**arguments)
+                elif name == "list_issues":
+                    result = await self._list_issues(**arguments)
+                else:
+                    raise ValueError(f"Unknown tool: {name}")
+
+                return [TextContent(
+                    type="text",
+                    text=json.dumps(result, indent=2, default=str)
+                )]
+
+            except Exception as e:
+                logger.error(f"Tool {name} failed: {e}")
+                return [TextContent(
+                    type="text",
+                    text=json.dumps({"error": str(e)}, indent=2)
+                )]
+
+    # Parse tool implementations (Issue #186)
+
+    async def _parse_plugin_interface(self, plugin_path: str) -> dict:
+        """Parse plugin interface from README.md"""
+        return await self.parse_tools.parse_plugin_interface(plugin_path)
+
+    async def _parse_claude_md_agents(self, claude_md_path: str) -> dict:
+        """Parse agents from CLAUDE.md"""
+        return await self.parse_tools.parse_claude_md_agents(claude_md_path)
+
+    # Validation tool implementations (Issue #187)
+
+    async def _validate_compatibility(self, plugin_a: str, plugin_b: str) -> dict:
+        """Validate compatibility between plugins"""
+        return await self.validation_tools.validate_compatibility(plugin_a, plugin_b)
+
+    async def _validate_agent_refs(self, agent_name: str, claude_md_path: str, plugin_paths: list = None) -> dict:
+        """Validate agent tool references"""
+        return await self.validation_tools.validate_agent_refs(agent_name, claude_md_path, plugin_paths)
+
+    async def _validate_data_flow(self, agent_name: str, claude_md_path: str) -> dict:
+        """Validate agent data flow"""
+        return await self.validation_tools.validate_data_flow(agent_name, claude_md_path)
+
+    async def _validate_workflow_integration(
+        self,
+        plugin_path: str,
+        domain_label: str,
+        expected_contract: str = None
+    ) -> dict:
+        """Validate domain plugin exposes required advisory interfaces"""
+        return await self.validation_tools.validate_workflow_integration(
+            plugin_path, domain_label, expected_contract
+        )
+
+    # Report tool implementations (Issue #188)
+
+    async def _generate_compatibility_report(self, marketplace_path: str, format: str = "markdown") -> dict:
+        """Generate comprehensive compatibility report"""
+        return await self.report_tools.generate_compatibility_report(marketplace_path, format)
+
+    async def _list_issues(self, marketplace_path: str, severity: str = "all", issue_type: str = "all") -> dict:
+        """List validation issues with filtering"""
+        return await self.report_tools.list_issues(marketplace_path, severity, issue_type)
+
+    async def run(self):
+        """Run the MCP server"""
+        await self.initialize()
+        self.setup_tools()
+
+        async with stdio_server() as (read_stream, write_stream):
+            await self.server.run(
+                read_stream,
+                write_stream,
+                self.server.create_initialization_options()
+            )
+
+
+async def main():
+    """Main entry point"""
+    server = ContractValidatorMCPServer()
+    await server.run()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

mcp-servers/contract-validator/mcp_server/validation_tools.py

@@ -0,0 +1,493 @@
+"""
+Validation tools for checking cross-plugin compatibility and agent references.
+
+Provides:
+- validate_compatibility: Compare two plugin interfaces
+- validate_agent_refs: Check agent tool references exist
+- validate_data_flow: Verify data flow through agent sequences
+"""
+from pathlib import Path
+from typing import Optional
+from pydantic import BaseModel
+from enum import Enum
+
+from .parse_tools import ParseTools, PluginInterface, ClaudeMdAgent
+
+
+class IssueSeverity(str, Enum):
+    ERROR = "error"
+    WARNING = "warning"
+    INFO = "info"
+
+
+class IssueType(str, Enum):
+    MISSING_TOOL = "missing_tool"
+    INTERFACE_MISMATCH = "interface_mismatch"
+    OPTIONAL_DEPENDENCY = "optional_dependency"
+    UNDECLARED_OUTPUT = "undeclared_output"
+    INVALID_SEQUENCE = "invalid_sequence"
+    MISSING_INTEGRATION = "missing_integration"
+
+
+class ValidationIssue(BaseModel):
+    """A single validation issue"""
+    severity: IssueSeverity
+    issue_type: IssueType
+    message: str
+    location: Optional[str] = None
+    suggestion: Optional[str] = None
+
+
+class CompatibilityResult(BaseModel):
+    """Result of compatibility check between two plugins"""
+    plugin_a: str
+    plugin_b: str
+    compatible: bool
+    shared_tools: list[str] = []
+    a_only_tools: list[str] = []
+    b_only_tools: list[str] = []
+    issues: list[ValidationIssue] = []
+
+
+class AgentValidationResult(BaseModel):
+    """Result of agent reference validation"""
+    agent_name: str
+    valid: bool
+    tool_refs_found: list[str] = []
+    tool_refs_missing: list[str] = []
+    issues: list[ValidationIssue] = []
+
+
+class DataFlowResult(BaseModel):
+    """Result of data flow validation"""
+    agent_name: str
+    valid: bool
+    flow_steps: list[str] = []
+    issues: list[ValidationIssue] = []
+
+
+class WorkflowIntegrationResult(BaseModel):
+    """Result of workflow integration validation for domain plugins"""
+    plugin_name: str
+    domain_label: str
+    valid: bool
+    gate_command_found: bool
+    gate_contract: Optional[str] = None  # Contract version declared by gate command
+    review_command_found: bool
+    advisory_agent_found: bool
+    issues: list[ValidationIssue] = []
+
+
+class ValidationTools:
+    """Tools for validating plugin compatibility and agent references"""
+
+    def __init__(self):
+        self.parse_tools = ParseTools()
+
+    async def validate_compatibility(self, plugin_a: str, plugin_b: str) -> dict:
+        """
+        Validate compatibility between two plugin interfaces.
+
+        Compares tools, commands, and agents to identify overlaps and gaps.
+
+        Args:
+            plugin_a: Path to first plugin directory
+            plugin_b: Path to second plugin directory
+
+        Returns:
+            Compatibility report with shared tools, unique tools, and issues
+        """
+        # Parse both plugins
+        interface_a = await self.parse_tools.parse_plugin_interface(plugin_a)
+        interface_b = await self.parse_tools.parse_plugin_interface(plugin_b)
+
+        # Check for parse errors
+        if "error" in interface_a:
+            return {
+                "error": f"Failed to parse plugin A: {interface_a['error']}",
+                "plugin_a": plugin_a,
+                "plugin_b": plugin_b
+            }
+        if "error" in interface_b:
+            return {
+                "error": f"Failed to parse plugin B: {interface_b['error']}",
+                "plugin_a": plugin_a,
+                "plugin_b": plugin_b
+            }
+
+        # Extract tool names
+        tools_a = set(t["name"] for t in interface_a.get("tools", []))
+        tools_b = set(t["name"] for t in interface_b.get("tools", []))
+
+        # Find overlaps and differences
+        shared = tools_a & tools_b
+        a_only = tools_a - tools_b
+        b_only = tools_b - tools_a
+
+        issues = []
+
+        # Check for potential naming conflicts
+        if shared:
+            issues.append(ValidationIssue(
+                severity=IssueSeverity.WARNING,
+                issue_type=IssueType.INTERFACE_MISMATCH,
+                message=f"Both plugins define tools with same names: {list(shared)}",
+                location=f"{interface_a['plugin_name']} and {interface_b['plugin_name']}",
+                suggestion="Ensure tools with same names have compatible interfaces"
+            ))
+
+        # Check command overlaps
+        cmds_a = set(c["name"] for c in interface_a.get("commands", []))
+        cmds_b = set(c["name"] for c in interface_b.get("commands", []))
+        shared_cmds = cmds_a & cmds_b
+
+        if shared_cmds:
+            issues.append(ValidationIssue(
+                severity=IssueSeverity.ERROR,
+                issue_type=IssueType.INTERFACE_MISMATCH,
+                message=f"Command name conflict: {list(shared_cmds)}",
+                location=f"{interface_a['plugin_name']} and {interface_b['plugin_name']}",
+                suggestion="Rename conflicting commands to avoid ambiguity"
+            ))
+
+        result = CompatibilityResult(
+            plugin_a=interface_a["plugin_name"],
+            plugin_b=interface_b["plugin_name"],
+            compatible=len([i for i in issues if i.severity == IssueSeverity.ERROR]) == 0,
+            shared_tools=list(shared),
+            a_only_tools=list(a_only),
+            b_only_tools=list(b_only),
+            issues=issues
+        )
+
+        return result.model_dump()
+
+    async def validate_agent_refs(
+        self,
+        agent_name: str,
+        claude_md_path: str,
+        plugin_paths: list[str] = None
+    ) -> dict:
+        """
+        Validate that all tool references in an agent definition exist.
+
+        Args:
+            agent_name: Name of the agent to validate
+            claude_md_path: Path to CLAUDE.md containing the agent
+            plugin_paths: Optional list of plugin paths to check for tools
+
+        Returns:
+            Validation result with found/missing tools and issues
+        """
+        # Parse CLAUDE.md for agents
+        agents_result = await self.parse_tools.parse_claude_md_agents(claude_md_path)
+
+        if "error" in agents_result:
+            return {
+                "error": agents_result["error"],
+                "agent_name": agent_name
+            }
+
+        # Find the specific agent
+        agent = None
+        for a in agents_result.get("agents", []):
+            if a["name"].lower() == agent_name.lower():
+                agent = a
+                break
+
+        if not agent:
+            return {
+                "error": f"Agent '{agent_name}' not found in {claude_md_path}",
+                "agent_name": agent_name,
+                "available_agents": [a["name"] for a in agents_result.get("agents", [])]
+            }
+
+        # Collect all available tools from plugins
+        available_tools = set()
+        if plugin_paths:
+            for plugin_path in plugin_paths:
+                interface = await self.parse_tools.parse_plugin_interface(plugin_path)
+                if "error" not in interface:
+                    for tool in interface.get("tools", []):
+                        available_tools.add(tool["name"])
+
+        # Check agent tool references
+        tool_refs = set(agent.get("tool_refs", []))
+        found = tool_refs & available_tools if available_tools else tool_refs
+        missing = tool_refs - available_tools if available_tools else set()
+
+        issues = []
+
+        # Report missing tools
+        for tool in missing:
+            issues.append(ValidationIssue(
+                severity=IssueSeverity.ERROR,
+                issue_type=IssueType.MISSING_TOOL,
+                message=f"Agent '{agent_name}' references tool '{tool}' which is not found",
+                location=claude_md_path,
+                suggestion=f"Check if tool '{tool}' exists or fix the reference"
+            ))
+
+        # Check if agent has no tool refs (might be incomplete)
+        if not tool_refs:
+            issues.append(ValidationIssue(
+                severity=IssueSeverity.INFO,
+                issue_type=IssueType.UNDECLARED_OUTPUT,
+                message=f"Agent '{agent_name}' has no documented tool references",
+                location=claude_md_path,
+                suggestion="Consider documenting which tools this agent uses"
+            ))
+
+        result = AgentValidationResult(
+            agent_name=agent_name,
+            valid=len([i for i in issues if i.severity == IssueSeverity.ERROR]) == 0,
+            tool_refs_found=list(found),
+            tool_refs_missing=list(missing),
+            issues=issues
+        )
+
+        return result.model_dump()
+
+    async def validate_data_flow(self, agent_name: str, claude_md_path: str) -> dict:
+        """
+        Validate data flow through an agent's tool sequence.
+
+        Checks that each step's expected output can be used by the next step.
+
+        Args:
+            agent_name: Name of the agent to validate
+            claude_md_path: Path to CLAUDE.md containing the agent
+
+        Returns:
+            Data flow validation result with steps and issues
+        """
+        # Parse CLAUDE.md for agents
+        agents_result = await self.parse_tools.parse_claude_md_agents(claude_md_path)
+
+        if "error" in agents_result:
+            return {
+                "error": agents_result["error"],
+                "agent_name": agent_name
+            }
+
+        # Find the specific agent
+        agent = None
+        for a in agents_result.get("agents", []):
+            if a["name"].lower() == agent_name.lower():
+                agent = a
+                break
+
+        if not agent:
+            return {
+                "error": f"Agent '{agent_name}' not found in {claude_md_path}",
+                "agent_name": agent_name,
+                "available_agents": [a["name"] for a in agents_result.get("agents", [])]
+            }
+
+        issues = []
+        flow_steps = []
+
+        # Extract workflow steps
+        workflow_steps = agent.get("workflow_steps", [])
+        responsibilities = agent.get("responsibilities", [])
+
+        # Build flow from workflow steps or responsibilities
+        steps = workflow_steps if workflow_steps else responsibilities
+
+        for i, step in enumerate(steps):
+            flow_steps.append(f"Step {i+1}: {step}")
+
+        # Check for data flow patterns
+        tool_refs = agent.get("tool_refs", [])
+
+        # Known data flow patterns
+        # e.g., data-platform produces data_ref, viz-platform consumes it
+        known_producers = {
+            "read_csv": "data_ref",
+            "read_parquet": "data_ref",
+            "pg_query": "data_ref",
+            "filter": "data_ref",
+            "groupby": "data_ref",
+        }
+
+        known_consumers = {
+            "describe": "data_ref",
+            "head": "data_ref",
+            "tail": "data_ref",
+            "to_csv": "data_ref",
+            "to_parquet": "data_ref",
+        }
+
+        # Check if agent uses tools that require data_ref
+        has_producer = any(t in known_producers for t in tool_refs)
+        has_consumer = any(t in known_consumers for t in tool_refs)
+
+        if has_consumer and not has_producer:
+            issues.append(ValidationIssue(
+                severity=IssueSeverity.WARNING,
+                issue_type=IssueType.INTERFACE_MISMATCH,
+                message=f"Agent '{agent_name}' uses tools that consume data_ref but no producer found",
+                location=claude_md_path,
+                suggestion="Ensure a data loading tool (read_csv, pg_query, etc.) is used before data consumers"
+            ))
+
+        # Check for empty workflow
+        if not steps and not tool_refs:
+            issues.append(ValidationIssue(
+                severity=IssueSeverity.INFO,
+                issue_type=IssueType.UNDECLARED_OUTPUT,
+                message=f"Agent '{agent_name}' has no documented workflow or tool sequence",
+                location=claude_md_path,
+                suggestion="Consider documenting the agent's workflow steps"
+            ))
+
+        result = DataFlowResult(
+            agent_name=agent_name,
+            valid=len([i for i in issues if i.severity == IssueSeverity.ERROR]) == 0,
+            flow_steps=flow_steps,
+            issues=issues
+        )
+
+        return result.model_dump()
+
+    async def validate_workflow_integration(
+        self,
+        plugin_path: str,
+        domain_label: str,
+        expected_contract: Optional[str] = None
+    ) -> dict:
+        """
+        Validate that a domain plugin exposes required advisory interfaces.
+
+        Checks for:
+        - Gate command (e.g., /design-gate, /data-gate) - REQUIRED
+        - Gate contract version (gate_contract in frontmatter) - INFO if missing
+        - Review command (e.g., /design-review, /data-review) - recommended
+        - Advisory agent referencing the domain label - recommended
+
+        Args:
+            plugin_path: Path to the domain plugin directory
+            domain_label: The Domain/* label it claims to handle (e.g., Domain/Viz)
+            expected_contract: Expected contract version (e.g., 'v1'). If provided,
+                              validates the gate command's contract matches.
+
+        Returns:
+            Validation result with found interfaces and issues
+        """
+        import re
+
+        plugin_path_obj = Path(plugin_path)
+        issues = []
+
+        # Extract plugin name from path
+        plugin_name = plugin_path_obj.name
+        if not plugin_path_obj.exists():
+            return {
+                "error": f"Plugin directory not found: {plugin_path}",
+                "plugin_path": plugin_path,
+                "domain_label": domain_label
+            }
+
+        # Extract domain short name from label (e.g., "Domain/Viz" -> "viz", "Domain/Data" -> "data")
+        domain_short = domain_label.split("/")[-1].lower() if "/" in domain_label else domain_label.lower()
+
+        # Check for gate command
+        commands_dir = plugin_path_obj / "commands"
+        gate_command_found = False
+        gate_contract = None
+        gate_patterns = ["pass", "fail", "PASS", "FAIL", "Binary pass/fail", "gate"]
+
+        if commands_dir.exists():
+            for cmd_file in commands_dir.glob("*.md"):
+                if "gate" in cmd_file.name.lower():
+                    # Verify it's actually a gate command by checking content
+                    content = cmd_file.read_text()
+                    if any(pattern in content for pattern in gate_patterns):
+                        gate_command_found = True
+                        # Parse frontmatter for gate_contract
+                        frontmatter_match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
+                        if frontmatter_match:
+                            frontmatter = frontmatter_match.group(1)
+                            contract_match = re.search(r'gate_contract:\s*(\S+)', frontmatter)
+                            if contract_match:
+                                gate_contract = contract_match.group(1)
+                        break
+
+        if not gate_command_found:
+            issues.append(ValidationIssue(
+                severity=IssueSeverity.ERROR,
+                issue_type=IssueType.MISSING_INTEGRATION,
+                message=f"Plugin '{plugin_name}' lacks a gate command for domain '{domain_label}'",
+                location=str(commands_dir),
+                suggestion=f"Create commands/{domain_short}-gate.md with binary PASS/FAIL output"
+            ))
+
+        # Check for review command
+        review_command_found = False
+        if commands_dir.exists():
+            for cmd_file in commands_dir.glob("*.md"):
+                if "review" in cmd_file.name.lower() and "gate" not in cmd_file.name.lower():
+                    review_command_found = True
+                    break
+
+        if not review_command_found:
+            issues.append(ValidationIssue(
+                severity=IssueSeverity.WARNING,
+                issue_type=IssueType.MISSING_INTEGRATION,
+                message=f"Plugin '{plugin_name}' lacks a review command for domain '{domain_label}'",
+                location=str(commands_dir),
+                suggestion=f"Create commands/{domain_short}-review.md for detailed audits"
+            ))
+
+        # Check for advisory agent
+        agents_dir = plugin_path_obj / "agents"
+        advisory_agent_found = False
+
+        if agents_dir.exists():
+            for agent_file in agents_dir.glob("*.md"):
+                content = agent_file.read_text()
+                # Check if agent references the domain label or gate command
+                if domain_label in content or f"{domain_short}-gate" in content.lower() or "advisor" in agent_file.name.lower() or "reviewer" in agent_file.name.lower():
+                    advisory_agent_found = True
+                    break
+
+        if not advisory_agent_found:
+            issues.append(ValidationIssue(
+                severity=IssueSeverity.WARNING,
+                issue_type=IssueType.MISSING_INTEGRATION,
+                message=f"Plugin '{plugin_name}' lacks an advisory agent for domain '{domain_label}'",
+                location=str(agents_dir) if agents_dir.exists() else str(plugin_path_obj),
+                suggestion=f"Create agents/{domain_short}-advisor.md referencing '{domain_label}'"
+            ))
+
+        # Check gate contract version
+        if gate_command_found:
+            if not gate_contract:
+                issues.append(ValidationIssue(
+                    severity=IssueSeverity.INFO,
+                    issue_type=IssueType.MISSING_INTEGRATION,
+                    message=f"Gate command does not declare a contract version",
+                    location=str(commands_dir),
+                    suggestion="Consider adding `gate_contract: v1` to frontmatter for version tracking"
+                ))
+            elif expected_contract and gate_contract != expected_contract:
+                issues.append(ValidationIssue(
+                    severity=IssueSeverity.WARNING,
+                    issue_type=IssueType.INTERFACE_MISMATCH,
+                    message=f"Contract version mismatch: gate declares {gate_contract}, projman expects {expected_contract}",
+                    location=str(commands_dir),
+                    suggestion=f"Update domain-consultation.md Gate Command Reference table to {gate_contract}, or update gate command to {expected_contract}"
+                ))
+
+        result = WorkflowIntegrationResult(
+            plugin_name=plugin_name,
+            domain_label=domain_label,
+            valid=gate_command_found,  # Only gate is required for validity
+            gate_command_found=gate_command_found,
+            gate_contract=gate_contract,
+            review_command_found=review_command_found,
+            advisory_agent_found=advisory_agent_found,
+            issues=issues
+        )
+
+        return result.model_dump()

mcp-servers/contract-validator/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "contract-validator-mcp"
+version = "1.0.0"
+description = "MCP Server for cross-plugin compatibility validation and agent verification"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [
+    {name = "Leo Miranda"}
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "mcp>=0.9.0",
+    "pydantic>=2.5.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.3",
+    "pytest-asyncio>=0.23.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["mcp_server*"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

mcp-servers/contract-validator/requirements.txt

@@ -0,0 +1,9 @@
+# MCP SDK
+mcp>=0.9.0
+
+# Utilities
+pydantic>=2.5.0
+
+# Testing
+pytest>=7.4.3
+pytest-asyncio>=0.23.0

mcp-servers/contract-validator/run.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+# Capture original working directory before any cd operations
+# This should be the user's project directory when launched by Claude Code
+export CLAUDE_PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CACHE_VENV="$HOME/.cache/claude-mcp-venvs/leo-claude-mktplace/contract-validator/.venv"
+LOCAL_VENV="$SCRIPT_DIR/.venv"
+
+if [[ -f "$CACHE_VENV/bin/python" ]]; then
+    PYTHON="$CACHE_VENV/bin/python"
+elif [[ -f "$LOCAL_VENV/bin/python" ]]; then
+    PYTHON="$LOCAL_VENV/bin/python"
+else
+    echo "ERROR: No venv found. Run: ./scripts/setup-venvs.sh" >&2
+    exit 1
+fi
+
+cd "$SCRIPT_DIR"
+export PYTHONPATH="$SCRIPT_DIR"
+exec "$PYTHON" -m mcp_server.server "$@"

mcp-servers/contract-validator/tests/__init__.py

@@ -0,0 +1 @@
+# Tests for contract-validator MCP server

mcp-servers/contract-validator/tests/test_parse_tools.py

@@ -0,0 +1,193 @@
+"""
+Unit tests for parse tools.
+"""
+import pytest
+from pathlib import Path
+
+
+@pytest.fixture
+def parse_tools():
+    """Create ParseTools instance"""
+    from mcp_server.parse_tools import ParseTools
+    return ParseTools()
+
+
+@pytest.fixture
+def sample_readme(tmp_path):
+    """Create a sample README.md for testing"""
+    readme = tmp_path / "README.md"
+    readme.write_text("""# Test Plugin
+
+A test plugin for validation.
+
+## Features
+
+- **Feature One**: Does something
+- **Feature Two**: Does something else
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/test-cmd` | Test command |
+| `/another-cmd` | Another test command |
+
+## Agents
+
+| Agent | Description |
+|-------|-------------|
+| `test-agent` | A test agent |
+
+## Tools Summary
+
+### Category A (3 tools)
+`tool_a`, `tool_b`, `tool_c`
+
+### Category B (2 tools)
+`tool_d`, `tool_e`
+""")
+    return str(tmp_path)
+
+
+@pytest.fixture
+def sample_claude_md(tmp_path):
+    """Create a sample CLAUDE.md for testing"""
+    claude_md = tmp_path / "CLAUDE.md"
+    claude_md.write_text("""# CLAUDE.md
+
+## Project Overview
+
+### Four-Agent Model (test)
+
+| Agent | Personality | Responsibilities |
+|-------|-------------|------------------|
+| **Planner** | Thoughtful | Planning via `create_issue`, `search_lessons` |
+| **Executor** | Focused | Implementation via `write`, `edit` |
+
+## Workflow
+
+1. Planner creates issues
+2. Executor implements code
+""")
+    return str(claude_md)
+
+
+@pytest.mark.asyncio
+async def test_parse_plugin_interface_basic(parse_tools, sample_readme):
+    """Test basic plugin interface parsing"""
+    result = await parse_tools.parse_plugin_interface(sample_readme)
+
+    assert "error" not in result
+    # Plugin name extraction strips "Plugin" suffix
+    assert result["plugin_name"] == "Test"
+    assert "A test plugin" in result["description"]
+
+
+@pytest.mark.asyncio
+async def test_parse_plugin_interface_commands(parse_tools, sample_readme):
+    """Test command extraction from README"""
+    result = await parse_tools.parse_plugin_interface(sample_readme)
+
+    commands = result["commands"]
+    assert len(commands) == 2
+    assert commands[0]["name"] == "/test-cmd"
+    assert commands[1]["name"] == "/another-cmd"
+
+
+@pytest.mark.asyncio
+async def test_parse_plugin_interface_agents(parse_tools, sample_readme):
+    """Test agent extraction from README"""
+    result = await parse_tools.parse_plugin_interface(sample_readme)
+
+    agents = result["agents"]
+    assert len(agents) == 1
+    assert agents[0]["name"] == "test-agent"
+
+
+@pytest.mark.asyncio
+async def test_parse_plugin_interface_tools(parse_tools, sample_readme):
+    """Test tool extraction from README"""
+    result = await parse_tools.parse_plugin_interface(sample_readme)
+
+    tools = result["tools"]
+    tool_names = [t["name"] for t in tools]
+    assert "tool_a" in tool_names
+    assert "tool_b" in tool_names
+    assert "tool_e" in tool_names
+    assert len(tools) >= 5
+
+
+@pytest.mark.asyncio
+async def test_parse_plugin_interface_categories(parse_tools, sample_readme):
+    """Test tool category extraction"""
+    result = await parse_tools.parse_plugin_interface(sample_readme)
+
+    categories = result["tool_categories"]
+    assert "Category A" in categories
+    assert "Category B" in categories
+    assert "tool_a" in categories["Category A"]
+
+
+@pytest.mark.asyncio
+async def test_parse_plugin_interface_features(parse_tools, sample_readme):
+    """Test feature extraction"""
+    result = await parse_tools.parse_plugin_interface(sample_readme)
+
+    features = result["features"]
+    assert "Feature One" in features
+    assert "Feature Two" in features
+
+
+@pytest.mark.asyncio
+async def test_parse_plugin_interface_not_found(parse_tools, tmp_path):
+    """Test error when README not found"""
+    result = await parse_tools.parse_plugin_interface(str(tmp_path / "nonexistent"))
+
+    assert "error" in result
+    assert "not found" in result["error"].lower()
+
+
+@pytest.mark.asyncio
+async def test_parse_claude_md_agents(parse_tools, sample_claude_md):
+    """Test agent extraction from CLAUDE.md"""
+    result = await parse_tools.parse_claude_md_agents(sample_claude_md)
+
+    assert "error" not in result
+    assert result["agent_count"] == 2
+
+    agents = result["agents"]
+    agent_names = [a["name"] for a in agents]
+    assert "Planner" in agent_names
+    assert "Executor" in agent_names
+
+
+@pytest.mark.asyncio
+async def test_parse_claude_md_tool_refs(parse_tools, sample_claude_md):
+    """Test tool reference extraction from agents"""
+    result = await parse_tools.parse_claude_md_agents(sample_claude_md)
+
+    agents = {a["name"]: a for a in result["agents"]}
+    planner = agents["Planner"]
+
+    assert "create_issue" in planner["tool_refs"]
+    assert "search_lessons" in planner["tool_refs"]
+
+
+@pytest.mark.asyncio
+async def test_parse_claude_md_not_found(parse_tools, tmp_path):
+    """Test error when CLAUDE.md not found"""
+    result = await parse_tools.parse_claude_md_agents(str(tmp_path / "CLAUDE.md"))
+
+    assert "error" in result
+    assert "not found" in result["error"].lower()
+
+
+@pytest.mark.asyncio
+async def test_parse_plugin_with_direct_file(parse_tools, sample_readme):
+    """Test parsing with direct file path instead of directory"""
+    readme_path = Path(sample_readme) / "README.md"
+    result = await parse_tools.parse_plugin_interface(str(readme_path))
+
+    assert "error" not in result
+    # Plugin name extraction strips "Plugin" suffix
+    assert result["plugin_name"] == "Test"

mcp-servers/contract-validator/tests/test_report_tools.py

@@ -0,0 +1,261 @@
+"""
+Unit tests for report tools.
+"""
+import pytest
+from pathlib import Path
+
+
+@pytest.fixture
+def report_tools():
+    """Create ReportTools instance"""
+    from mcp_server.report_tools import ReportTools
+    return ReportTools()
+
+
+@pytest.fixture
+def sample_marketplace(tmp_path):
+    """Create a sample marketplace structure"""
+    import json
+
+    plugins_dir = tmp_path / "plugins"
+    plugins_dir.mkdir()
+
+    # Plugin 1
+    plugin1 = plugins_dir / "plugin-one"
+    plugin1.mkdir()
+    plugin1_meta = plugin1 / ".claude-plugin"
+    plugin1_meta.mkdir()
+    (plugin1_meta / "plugin.json").write_text(json.dumps({"name": "plugin-one"}))
+    (plugin1 / "README.md").write_text("""# plugin-one
+
+First test plugin.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/cmd-one` | Command one |
+
+## Tools Summary
+
+### Tools (2 tools)
+`tool_a`, `tool_b`
+""")
+
+    # Plugin 2
+    plugin2 = plugins_dir / "plugin-two"
+    plugin2.mkdir()
+    plugin2_meta = plugin2 / ".claude-plugin"
+    plugin2_meta.mkdir()
+    (plugin2_meta / "plugin.json").write_text(json.dumps({"name": "plugin-two"}))
+    (plugin2 / "README.md").write_text("""# plugin-two
+
+Second test plugin.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/cmd-two` | Command two |
+
+## Tools Summary
+
+### Tools (2 tools)
+`tool_c`, `tool_d`
+""")
+
+    # Plugin 3 (with conflict)
+    plugin3 = plugins_dir / "plugin-three"
+    plugin3.mkdir()
+    plugin3_meta = plugin3 / ".claude-plugin"
+    plugin3_meta.mkdir()
+    (plugin3_meta / "plugin.json").write_text(json.dumps({"name": "plugin-three"}))
+    (plugin3 / "README.md").write_text("""# plugin-three
+
+Third test plugin with conflict.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/cmd-one` | Conflicting command |
+
+## Tools Summary
+
+### Tools (1 tool)
+`tool_e`
+""")
+
+    return str(tmp_path)
+
+
+@pytest.fixture
+def marketplace_no_plugins(tmp_path):
+    """Create marketplace with no plugins"""
+    plugins_dir = tmp_path / "plugins"
+    plugins_dir.mkdir()
+    return str(tmp_path)
+
+
+@pytest.fixture
+def marketplace_no_dir(tmp_path):
+    """Create path without plugins directory"""
+    return str(tmp_path)
+
+
+@pytest.mark.asyncio
+async def test_generate_report_json_format(report_tools, sample_marketplace):
+    """Test JSON format report generation"""
+    result = await report_tools.generate_compatibility_report(
+        sample_marketplace, "json"
+    )
+
+    assert "error" not in result
+    assert "generated_at" in result
+    assert "summary" in result
+    assert "plugins" in result
+    assert result["summary"]["total_plugins"] == 3
+
+
+@pytest.mark.asyncio
+async def test_generate_report_markdown_format(report_tools, sample_marketplace):
+    """Test markdown format report generation"""
+    result = await report_tools.generate_compatibility_report(
+        sample_marketplace, "markdown"
+    )
+
+    assert "error" not in result
+    assert "report" in result
+    assert "# Contract Validation Report" in result["report"]
+    assert "## Summary" in result["report"]
+
+
+@pytest.mark.asyncio
+async def test_generate_report_finds_conflicts(report_tools, sample_marketplace):
+    """Test that report finds command conflicts"""
+    result = await report_tools.generate_compatibility_report(
+        sample_marketplace, "json"
+    )
+
+    assert "error" not in result
+    assert result["summary"]["errors"] > 0
+    assert result["summary"]["total_issues"] > 0
+
+
+@pytest.mark.asyncio
+async def test_generate_report_counts_correctly(report_tools, sample_marketplace):
+    """Test summary counts are correct"""
+    result = await report_tools.generate_compatibility_report(
+        sample_marketplace, "json"
+    )
+
+    summary = result["summary"]
+    assert summary["total_plugins"] == 3
+    assert summary["total_commands"] == 3  # 3 commands total
+    assert summary["total_tools"] == 5  # a, b, c, d, e
+
+
+@pytest.mark.asyncio
+async def test_generate_report_no_plugins(report_tools, marketplace_no_plugins):
+    """Test error when no plugins found"""
+    result = await report_tools.generate_compatibility_report(
+        marketplace_no_plugins, "json"
+    )
+
+    assert "error" in result
+    assert "no plugins" in result["error"].lower()
+
+
+@pytest.mark.asyncio
+async def test_generate_report_no_plugins_dir(report_tools, marketplace_no_dir):
+    """Test error when plugins directory doesn't exist"""
+    result = await report_tools.generate_compatibility_report(
+        marketplace_no_dir, "json"
+    )
+
+    assert "error" in result
+    assert "not found" in result["error"].lower()
+
+
+@pytest.mark.asyncio
+async def test_list_issues_all(report_tools, sample_marketplace):
+    """Test listing all issues"""
+    result = await report_tools.list_issues(sample_marketplace, "all", "all")
+
+    assert "error" not in result
+    assert "issues" in result
+    assert result["total_issues"] > 0
+
+
+@pytest.mark.asyncio
+async def test_list_issues_filter_by_severity(report_tools, sample_marketplace):
+    """Test filtering issues by severity"""
+    all_result = await report_tools.list_issues(sample_marketplace, "all", "all")
+    error_result = await report_tools.list_issues(sample_marketplace, "error", "all")
+
+    # Error count should be less than or equal to all
+    assert error_result["total_issues"] <= all_result["total_issues"]
+
+    # All issues should have error severity
+    for issue in error_result["issues"]:
+        sev = issue.get("severity", "")
+        if hasattr(sev, 'value'):
+            sev = sev.value
+        assert "error" in str(sev).lower()
+
+
+@pytest.mark.asyncio
+async def test_list_issues_filter_by_type(report_tools, sample_marketplace):
+    """Test filtering issues by type"""
+    result = await report_tools.list_issues(
+        sample_marketplace, "all", "interface_mismatch"
+    )
+
+    # All issues should have matching type
+    for issue in result["issues"]:
+        itype = issue.get("issue_type", "")
+        if hasattr(itype, 'value'):
+            itype = itype.value
+        assert "interface_mismatch" in str(itype).lower()
+
+
+@pytest.mark.asyncio
+async def test_list_issues_combined_filters(report_tools, sample_marketplace):
+    """Test combined severity and type filters"""
+    result = await report_tools.list_issues(
+        sample_marketplace, "error", "interface_mismatch"
+    )
+
+    assert "error" not in result
+    # Should have command conflict errors
+    assert result["total_issues"] > 0
+
+
+@pytest.mark.asyncio
+async def test_report_markdown_has_all_sections(report_tools, sample_marketplace):
+    """Test markdown report contains all expected sections"""
+    result = await report_tools.generate_compatibility_report(
+        sample_marketplace, "markdown"
+    )
+
+    report = result["report"]
+    assert "## Summary" in report
+    assert "## Plugins" in report
+    # Compatibility section only if there are checks
+    assert "Plugin One" in report or "plugin-one" in report.lower()
+
+
+@pytest.mark.asyncio
+async def test_report_includes_suggestions(report_tools, sample_marketplace):
+    """Test that issues include suggestions"""
+    result = await report_tools.generate_compatibility_report(
+        sample_marketplace, "json"
+    )
+
+    issues = result.get("all_issues", [])
+    # Find an issue with a suggestion
+    issues_with_suggestions = [
+        i for i in issues
+        if i.get("suggestion")
+    ]
+    assert len(issues_with_suggestions) > 0

mcp-servers/contract-validator/tests/test_validation_tools.py

@@ -0,0 +1,514 @@
+"""
+Unit tests for validation tools.
+"""
+import pytest
+from pathlib import Path
+
+
+@pytest.fixture
+def validation_tools():
+    """Create ValidationTools instance"""
+    from mcp_server.validation_tools import ValidationTools
+    return ValidationTools()
+
+
+@pytest.fixture
+def plugin_a(tmp_path):
+    """Create first test plugin"""
+    plugin_dir = tmp_path / "plugin-a"
+    plugin_dir.mkdir()
+    (plugin_dir / ".claude-plugin").mkdir()
+
+    readme = plugin_dir / "README.md"
+    readme.write_text("""# Plugin A
+
+Test plugin A.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/setup-a` | Setup A |
+| `/shared-cmd` | Shared command |
+
+## Tools Summary
+
+### Core (2 tools)
+`tool_one`, `tool_two`
+""")
+    return str(plugin_dir)
+
+
+@pytest.fixture
+def plugin_b(tmp_path):
+    """Create second test plugin"""
+    plugin_dir = tmp_path / "plugin-b"
+    plugin_dir.mkdir()
+    (plugin_dir / ".claude-plugin").mkdir()
+
+    readme = plugin_dir / "README.md"
+    readme.write_text("""# Plugin B
+
+Test plugin B.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/setup-b` | Setup B |
+| `/shared-cmd` | Shared command (conflict!) |
+
+## Tools Summary
+
+### Core (2 tools)
+`tool_two`, `tool_three`
+""")
+    return str(plugin_dir)
+
+
+@pytest.fixture
+def plugin_no_conflict(tmp_path):
+    """Create plugin with no conflicts"""
+    plugin_dir = tmp_path / "plugin-c"
+    plugin_dir.mkdir()
+    (plugin_dir / ".claude-plugin").mkdir()
+
+    readme = plugin_dir / "README.md"
+    readme.write_text("""# Plugin C
+
+Test plugin C.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/unique-cmd` | Unique command |
+
+## Tools Summary
+
+### Core (1 tool)
+`unique_tool`
+""")
+    return str(plugin_dir)
+
+
+@pytest.fixture
+def claude_md_with_agents(tmp_path):
+    """Create CLAUDE.md with agent definitions"""
+    claude_md = tmp_path / "CLAUDE.md"
+    claude_md.write_text("""# CLAUDE.md
+
+### Four-Agent Model
+
+| Agent | Personality | Responsibilities |
+|-------|-------------|------------------|
+| **TestAgent** | Careful | Uses `tool_one`, `tool_two`, `missing_tool` |
+| **ValidAgent** | Thorough | Uses `tool_one` only |
+| **EmptyAgent** | Unknown | General tasks |
+""")
+    return str(claude_md)
+
+
+@pytest.mark.asyncio
+async def test_validate_compatibility_command_conflict(validation_tools, plugin_a, plugin_b):
+    """Test detection of command name conflicts"""
+    result = await validation_tools.validate_compatibility(plugin_a, plugin_b)
+
+    assert "error" not in result
+    assert result["compatible"] is False
+
+    # Find the command conflict issue
+    error_issues = [i for i in result["issues"] if i["severity"].value == "error"]
+    assert len(error_issues) > 0
+    assert any("/shared-cmd" in str(i["message"]) for i in error_issues)
+
+
+@pytest.mark.asyncio
+async def test_validate_compatibility_tool_overlap(validation_tools, plugin_a, plugin_b):
+    """Test detection of tool name overlaps"""
+    result = await validation_tools.validate_compatibility(plugin_a, plugin_b)
+
+    assert "tool_two" in result["shared_tools"]
+
+
+@pytest.mark.asyncio
+async def test_validate_compatibility_unique_tools(validation_tools, plugin_a, plugin_b):
+    """Test identification of unique tools per plugin"""
+    result = await validation_tools.validate_compatibility(plugin_a, plugin_b)
+
+    assert "tool_one" in result["a_only_tools"]
+    assert "tool_three" in result["b_only_tools"]
+
+
+@pytest.mark.asyncio
+async def test_validate_compatibility_no_conflict(validation_tools, plugin_a, plugin_no_conflict):
+    """Test compatible plugins"""
+    result = await validation_tools.validate_compatibility(plugin_a, plugin_no_conflict)
+
+    assert "error" not in result
+    assert result["compatible"] is True
+
+
+@pytest.mark.asyncio
+async def test_validate_compatibility_missing_plugin(validation_tools, plugin_a, tmp_path):
+    """Test error when plugin not found"""
+    result = await validation_tools.validate_compatibility(
+        plugin_a,
+        str(tmp_path / "nonexistent")
+    )
+
+    assert "error" in result
+
+
+@pytest.mark.asyncio
+async def test_validate_agent_refs_with_missing_tools(validation_tools, claude_md_with_agents, plugin_a):
+    """Test detection of missing tool references"""
+    result = await validation_tools.validate_agent_refs(
+        "TestAgent",
+        claude_md_with_agents,
+        [plugin_a]
+    )
+
+    assert "error" not in result
+    assert result["valid"] is False
+    assert "missing_tool" in result["tool_refs_missing"]
+
+
+@pytest.mark.asyncio
+async def test_validate_agent_refs_valid_agent(validation_tools, claude_md_with_agents, plugin_a):
+    """Test valid agent with all tools found"""
+    result = await validation_tools.validate_agent_refs(
+        "ValidAgent",
+        claude_md_with_agents,
+        [plugin_a]
+    )
+
+    assert "error" not in result
+    assert result["valid"] is True
+    assert "tool_one" in result["tool_refs_found"]
+
+
+@pytest.mark.asyncio
+async def test_validate_agent_refs_empty_agent(validation_tools, claude_md_with_agents, plugin_a):
+    """Test agent with no tool references"""
+    result = await validation_tools.validate_agent_refs(
+        "EmptyAgent",
+        claude_md_with_agents,
+        [plugin_a]
+    )
+
+    assert "error" not in result
+    # Should have info issue about undocumented references
+    info_issues = [i for i in result["issues"] if i["severity"].value == "info"]
+    assert len(info_issues) > 0
+
+
+@pytest.mark.asyncio
+async def test_validate_agent_refs_agent_not_found(validation_tools, claude_md_with_agents, plugin_a):
+    """Test error when agent not found"""
+    result = await validation_tools.validate_agent_refs(
+        "NonexistentAgent",
+        claude_md_with_agents,
+        [plugin_a]
+    )
+
+    assert "error" in result
+    assert "not found" in result["error"].lower()
+
+
+@pytest.mark.asyncio
+async def test_validate_data_flow_valid(validation_tools, tmp_path):
+    """Test data flow validation with valid flow"""
+    claude_md = tmp_path / "CLAUDE.md"
+    claude_md.write_text("""# CLAUDE.md
+
+### Four-Agent Model
+
+| Agent | Personality | Responsibilities |
+|-------|-------------|------------------|
+| **DataAgent** | Analytical | Load with `read_csv`, analyze with `describe`, export with `to_csv` |
+""")
+
+    result = await validation_tools.validate_data_flow("DataAgent", str(claude_md))
+
+    assert "error" not in result
+    assert result["valid"] is True
+
+
+@pytest.mark.asyncio
+async def test_validate_data_flow_missing_producer(validation_tools, tmp_path):
+    """Test data flow with consumer but no producer"""
+    claude_md = tmp_path / "CLAUDE.md"
+    claude_md.write_text("""# CLAUDE.md
+
+### Four-Agent Model
+
+| Agent | Personality | Responsibilities |
+|-------|-------------|------------------|
+| **BadAgent** | Careless | Just runs `describe`, `head`, `tail` without loading |
+""")
+
+    result = await validation_tools.validate_data_flow("BadAgent", str(claude_md))
+
+    assert "error" not in result
+    # Should have warning about missing producer
+    warning_issues = [i for i in result["issues"] if i["severity"].value == "warning"]
+    assert len(warning_issues) > 0
+
+
+# --- Workflow Integration Tests ---
+
+@pytest.fixture
+def domain_plugin_complete(tmp_path):
+    """Create a complete domain plugin with gate, review, and advisory agent"""
+    plugin_dir = tmp_path / "viz-platform"
+    plugin_dir.mkdir()
+    (plugin_dir / ".claude-plugin").mkdir()
+    (plugin_dir / "commands").mkdir()
+    (plugin_dir / "agents").mkdir()
+
+    # Gate command with PASS/FAIL pattern
+    gate_cmd = plugin_dir / "commands" / "design-gate.md"
+    gate_cmd.write_text("""# /design-gate
+
+Binary pass/fail validation gate for design system compliance.
+
+## Output
+
+- **PASS**: All design system checks passed
+- **FAIL**: Design system violations detected
+""")
+
+    # Review command
+    review_cmd = plugin_dir / "commands" / "design-review.md"
+    review_cmd.write_text("""# /design-review
+
+Comprehensive design system audit.
+""")
+
+    # Advisory agent
+    agent = plugin_dir / "agents" / "design-reviewer.md"
+    agent.write_text("""# design-reviewer
+
+Design system compliance auditor.
+
+Handles issues with `Domain/Viz` label.
+""")
+
+    return str(plugin_dir)
+
+
+@pytest.fixture
+def domain_plugin_missing_gate(tmp_path):
+    """Create domain plugin with review and agent but no gate command"""
+    plugin_dir = tmp_path / "data-platform"
+    plugin_dir.mkdir()
+    (plugin_dir / ".claude-plugin").mkdir()
+    (plugin_dir / "commands").mkdir()
+    (plugin_dir / "agents").mkdir()
+
+    # Review command (but no gate)
+    review_cmd = plugin_dir / "commands" / "data-review.md"
+    review_cmd.write_text("""# /data-review
+
+Data integrity audit.
+""")
+
+    # Advisory agent
+    agent = plugin_dir / "agents" / "data-advisor.md"
+    agent.write_text("""# data-advisor
+
+Data integrity advisor for Domain/Data issues.
+""")
+
+    return str(plugin_dir)
+
+
+@pytest.fixture
+def domain_plugin_minimal(tmp_path):
+    """Create minimal plugin with no commands or agents"""
+    plugin_dir = tmp_path / "minimal-plugin"
+    plugin_dir.mkdir()
+    (plugin_dir / ".claude-plugin").mkdir()
+
+    readme = plugin_dir / "README.md"
+    readme.write_text("# Minimal Plugin\n\nNo commands or agents.")
+
+    return str(plugin_dir)
+
+
+@pytest.mark.asyncio
+async def test_validate_workflow_integration_complete(validation_tools, domain_plugin_complete):
+    """Test complete domain plugin returns valid with all interfaces found"""
+    result = await validation_tools.validate_workflow_integration(
+        domain_plugin_complete,
+        "Domain/Viz"
+    )
+
+    assert "error" not in result
+    assert result["valid"] is True
+    assert result["gate_command_found"] is True
+    assert result["review_command_found"] is True
+    assert result["advisory_agent_found"] is True
+    # May have INFO issue about missing contract version (not an error/warning)
+    error_or_warning = [i for i in result["issues"]
+                        if i["severity"].value in ("error", "warning")]
+    assert len(error_or_warning) == 0
+
+
+@pytest.mark.asyncio
+async def test_validate_workflow_integration_missing_gate(validation_tools, domain_plugin_missing_gate):
+    """Test plugin missing gate command returns invalid with ERROR"""
+    result = await validation_tools.validate_workflow_integration(
+        domain_plugin_missing_gate,
+        "Domain/Data"
+    )
+
+    assert "error" not in result
+    assert result["valid"] is False
+    assert result["gate_command_found"] is False
+    assert result["review_command_found"] is True
+    assert result["advisory_agent_found"] is True
+
+    # Should have one ERROR for missing gate
+    error_issues = [i for i in result["issues"] if i["severity"].value == "error"]
+    assert len(error_issues) == 1
+    assert "gate" in error_issues[0]["message"].lower()
+
+
+@pytest.mark.asyncio
+async def test_validate_workflow_integration_minimal(validation_tools, domain_plugin_minimal):
+    """Test minimal plugin returns invalid with multiple issues"""
+    result = await validation_tools.validate_workflow_integration(
+        domain_plugin_minimal,
+        "Domain/Test"
+    )
+
+    assert "error" not in result
+    assert result["valid"] is False
+    assert result["gate_command_found"] is False
+    assert result["review_command_found"] is False
+    assert result["advisory_agent_found"] is False
+
+    # Should have one ERROR (gate) and two WARNINGs (review, agent)
+    error_issues = [i for i in result["issues"] if i["severity"].value == "error"]
+    warning_issues = [i for i in result["issues"] if i["severity"].value == "warning"]
+    assert len(error_issues) == 1
+    assert len(warning_issues) == 2
+
+
+@pytest.mark.asyncio
+async def test_validate_workflow_integration_nonexistent_plugin(validation_tools, tmp_path):
+    """Test error when plugin directory doesn't exist"""
+    result = await validation_tools.validate_workflow_integration(
+        str(tmp_path / "nonexistent"),
+        "Domain/Test"
+    )
+
+    assert "error" in result
+    assert "not found" in result["error"].lower()
+
+
+# --- Gate Contract Version Tests ---
+
+@pytest.fixture
+def domain_plugin_with_contract(tmp_path):
+    """Create domain plugin with gate_contract: v1 in frontmatter"""
+    plugin_dir = tmp_path / "viz-platform-versioned"
+    plugin_dir.mkdir()
+    (plugin_dir / ".claude-plugin").mkdir()
+    (plugin_dir / "commands").mkdir()
+    (plugin_dir / "agents").mkdir()
+
+    # Gate command with gate_contract in frontmatter
+    gate_cmd = plugin_dir / "commands" / "design-gate.md"
+    gate_cmd.write_text("""---
+description: Design system compliance gate (pass/fail)
+gate_contract: v1
+---
+
+# /design-gate
+
+Binary pass/fail validation gate for design system compliance.
+
+## Output
+
+- **PASS**: All design system checks passed
+- **FAIL**: Design system violations detected
+""")
+
+    # Review command
+    review_cmd = plugin_dir / "commands" / "design-review.md"
+    review_cmd.write_text("""# /design-review
+
+Comprehensive design system audit.
+""")
+
+    # Advisory agent
+    agent = plugin_dir / "agents" / "design-reviewer.md"
+    agent.write_text("""# design-reviewer
+
+Design system compliance auditor for Domain/Viz issues.
+""")
+
+    return str(plugin_dir)
+
+
+@pytest.mark.asyncio
+async def test_validate_workflow_contract_match(validation_tools, domain_plugin_with_contract):
+    """Test that matching expected_contract produces no warning"""
+    result = await validation_tools.validate_workflow_integration(
+        domain_plugin_with_contract,
+        "Domain/Viz",
+        expected_contract="v1"
+    )
+
+    assert "error" not in result
+    assert result["valid"] is True
+    assert result["gate_contract"] == "v1"
+
+    # Should have no warnings about contract mismatch
+    warning_issues = [i for i in result["issues"] if i["severity"].value == "warning"]
+    contract_warnings = [i for i in warning_issues if "contract" in i["message"].lower()]
+    assert len(contract_warnings) == 0
+
+
+@pytest.mark.asyncio
+async def test_validate_workflow_contract_mismatch(validation_tools, domain_plugin_with_contract):
+    """Test that mismatched expected_contract produces WARNING"""
+    result = await validation_tools.validate_workflow_integration(
+        domain_plugin_with_contract,
+        "Domain/Viz",
+        expected_contract="v2"  # Gate has v1
+    )
+
+    assert "error" not in result
+    assert result["valid"] is True  # Contract mismatch doesn't affect validity
+    assert result["gate_contract"] == "v1"
+
+    # Should have warning about contract mismatch
+    warning_issues = [i for i in result["issues"] if i["severity"].value == "warning"]
+    contract_warnings = [i for i in warning_issues if "contract" in i["message"].lower()]
+    assert len(contract_warnings) == 1
+    assert "mismatch" in contract_warnings[0]["message"].lower()
+    assert "v1" in contract_warnings[0]["message"]
+    assert "v2" in contract_warnings[0]["message"]
+
+
+@pytest.mark.asyncio
+async def test_validate_workflow_no_contract(validation_tools, domain_plugin_complete):
+    """Test that missing gate_contract produces INFO suggestion"""
+    result = await validation_tools.validate_workflow_integration(
+        domain_plugin_complete,
+        "Domain/Viz"
+    )
+
+    assert "error" not in result
+    assert result["valid"] is True
+    assert result["gate_contract"] is None
+
+    # Should have info issue about missing contract
+    info_issues = [i for i in result["issues"] if i["severity"].value == "info"]
+    contract_info = [i for i in info_issues if "contract" in i["message"].lower()]
+    assert len(contract_info) == 1
+    assert "does not declare" in contract_info[0]["message"].lower()

mcp-servers/data-platform/README.md

@@ -0,0 +1,131 @@
+# Data Platform MCP Server
+
+MCP Server providing pandas, PostgreSQL/PostGIS, and dbt tools for Claude Code.
+
+## Features
+
+- **pandas Tools**: DataFrame operations with Arrow IPC data_ref persistence
+- **PostgreSQL Tools**: Database queries with asyncpg connection pooling
+- **PostGIS Tools**: Spatial data operations
+- **dbt Tools**: Build tool wrapper with pre-execution validation
+
+## Installation
+
+```bash
+cd mcp-servers/data-platform
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+pip install -r requirements.txt
+```
+
+## Configuration
+
+### System-Level (PostgreSQL credentials)
+
+Create `~/.config/claude/postgres.env`:
+
+```env
+POSTGRES_URL=postgresql://user:password@host:5432/database
+```
+
+### Project-Level (dbt paths)
+
+Create `.env` in your project root:
+
+```env
+DBT_PROJECT_DIR=/path/to/dbt/project
+DBT_PROFILES_DIR=/path/to/.dbt
+DATA_PLATFORM_MAX_ROWS=100000
+```
+
+## Tools
+
+### pandas Tools (14 tools)
+
+| Tool | Description |
+|------|-------------|
+| `read_csv` | Load CSV file into DataFrame |
+| `read_parquet` | Load Parquet file into DataFrame |
+| `read_json` | Load JSON/JSONL file into DataFrame |
+| `to_csv` | Export DataFrame to CSV file |
+| `to_parquet` | Export DataFrame to Parquet file |
+| `describe` | Get statistical summary of DataFrame |
+| `head` | Get first N rows of DataFrame |
+| `tail` | Get last N rows of DataFrame |
+| `filter` | Filter DataFrame rows by condition |
+| `select` | Select specific columns from DataFrame |
+| `groupby` | Group DataFrame and aggregate |
+| `join` | Join two DataFrames |
+| `list_data` | List all stored DataFrames |
+| `drop_data` | Remove a DataFrame from storage |
+
+### PostgreSQL Tools (6 tools)
+
+| Tool | Description |
+|------|-------------|
+| `pg_connect` | Test connection and return status |
+| `pg_query` | Execute SELECT, return as data_ref |
+| `pg_execute` | Execute INSERT/UPDATE/DELETE |
+| `pg_tables` | List all tables in schema |
+| `pg_columns` | Get column info for table |
+| `pg_schemas` | List all schemas |
+
+### PostGIS Tools (4 tools)
+
+| Tool | Description |
+|------|-------------|
+| `st_tables` | List PostGIS-enabled tables |
+| `st_geometry_type` | Get geometry type of column |
+| `st_srid` | Get SRID of geometry column |
+| `st_extent` | Get bounding box of geometries |
+
+### dbt Tools (8 tools)
+
+| Tool | Description |
+|------|-------------|
+| `dbt_parse` | Validate project (pre-execution) |
+| `dbt_run` | Run models with selection |
+| `dbt_test` | Run tests |
+| `dbt_build` | Run + test |
+| `dbt_compile` | Compile SQL without executing |
+| `dbt_ls` | List resources |
+| `dbt_docs_generate` | Generate documentation |
+| `dbt_lineage` | Get model dependencies |
+
+## data_ref System
+
+All DataFrame operations use a `data_ref` system to persist data across tool calls:
+
+1. **Load data**: Returns a `data_ref` string (e.g., `"df_a1b2c3d4"`)
+2. **Use data_ref**: Pass to other tools (filter, join, export)
+3. **List data**: Use `list_data` to see all stored DataFrames
+4. **Clean up**: Use `drop_data` when done
+
+### Example Flow
+
+```
+read_csv("data.csv") → {"data_ref": "sales_data", "rows": 1000}
+filter("sales_data", "amount > 100") → {"data_ref": "sales_data_filtered"}
+describe("sales_data_filtered") → {statistics}
+to_parquet("sales_data_filtered", "output.parquet") → {success}
+```
+
+## Memory Management
+
+- Default row limit: 100,000 rows per DataFrame
+- Configure via `DATA_PLATFORM_MAX_ROWS` environment variable
+- Use chunked processing for large files (`chunk_size` parameter)
+- Monitor with `list_data` tool (shows memory usage)
+
+## Running
+
+```bash
+python -m mcp_server.server
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```

mcp-servers/data-platform/mcp_server/__init__.py

@@ -0,0 +1,7 @@
+"""
+Data Platform MCP Server.
+
+Provides pandas, PostgreSQL/PostGIS, and dbt tools to Claude Code via MCP.
+"""
+
+__version__ = "1.0.0"

mcp-servers/data-platform/mcp_server/config.py

@@ -0,0 +1,195 @@
+"""
+Configuration loader for Data Platform MCP Server.
+
+Implements hybrid configuration system:
+- System-level: ~/.config/claude/postgres.env (credentials)
+- Project-level: .env (dbt project paths, overrides)
+- Auto-detection: dbt_project.yml discovery
+"""
+from pathlib import Path
+from dotenv import load_dotenv
+import os
+import logging
+from typing import Dict, Optional
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+class DataPlatformConfig:
+    """Hybrid configuration loader for data platform tools"""
+
+    def __init__(self):
+        self.postgres_url: Optional[str] = None
+        self.dbt_project_dir: Optional[str] = None
+        self.dbt_profiles_dir: Optional[str] = None
+        self.max_rows: int = 100_000
+
+    def load(self) -> Dict[str, Optional[str]]:
+        """
+        Load configuration from system and project levels.
+
+        Returns:
+            Dict containing postgres_url, dbt_project_dir, dbt_profiles_dir, max_rows
+
+        Note:
+            PostgreSQL credentials are optional - server can run in pandas-only mode.
+        """
+        # Load system config (PostgreSQL credentials)
+        system_config = Path.home() / '.config' / 'claude' / 'postgres.env'
+        if system_config.exists():
+            load_dotenv(system_config)
+            logger.info(f"Loaded system configuration from {system_config}")
+        else:
+            logger.info(
+                f"System config not found: {system_config} - "
+                "PostgreSQL tools will be unavailable"
+            )
+
+        # Find project directory
+        project_dir = self._find_project_directory()
+
+        # Load project config (overrides system)
+        if project_dir:
+            project_config = project_dir / '.env'
+            if project_config.exists():
+                load_dotenv(project_config, override=True)
+                logger.info(f"Loaded project configuration from {project_config}")
+
+        # Extract values
+        self.postgres_url = os.getenv('POSTGRES_URL')
+        self.dbt_project_dir = os.getenv('DBT_PROJECT_DIR')
+        self.dbt_profiles_dir = os.getenv('DBT_PROFILES_DIR')
+        self.max_rows = int(os.getenv('DATA_PLATFORM_MAX_ROWS', '100000'))
+
+        # Auto-detect dbt project if not specified
+        if not self.dbt_project_dir and project_dir:
+            self.dbt_project_dir = self._find_dbt_project(project_dir)
+            if self.dbt_project_dir:
+                logger.info(f"Auto-detected dbt project: {self.dbt_project_dir}")
+
+        # Default dbt profiles dir to ~/.dbt
+        if not self.dbt_profiles_dir:
+            default_profiles = Path.home() / '.dbt'
+            if default_profiles.exists():
+                self.dbt_profiles_dir = str(default_profiles)
+
+        return {
+            'postgres_url': self.postgres_url,
+            'dbt_project_dir': self.dbt_project_dir,
+            'dbt_profiles_dir': self.dbt_profiles_dir,
+            'max_rows': self.max_rows,
+            'postgres_available': self.postgres_url is not None,
+            'dbt_available': self.dbt_project_dir is not None
+        }
+
+    def _find_project_directory(self) -> Optional[Path]:
+        """
+        Find the user's project directory.
+
+        Returns:
+            Path to project directory, or None if not found
+        """
+        # Strategy 1: Check CLAUDE_PROJECT_DIR environment variable
+        project_dir = os.getenv('CLAUDE_PROJECT_DIR')
+        if project_dir:
+            path = Path(project_dir)
+            if path.exists():
+                logger.info(f"Found project directory from CLAUDE_PROJECT_DIR: {path}")
+                return path
+
+        # Strategy 2: Check PWD
+        pwd = os.getenv('PWD')
+        if pwd:
+            path = Path(pwd)
+            if path.exists() and (
+                (path / '.git').exists() or
+                (path / '.env').exists() or
+                (path / 'dbt_project.yml').exists()
+            ):
+                logger.info(f"Found project directory from PWD: {path}")
+                return path
+
+        # Strategy 3: Check current working directory
+        cwd = Path.cwd()
+        if (cwd / '.git').exists() or (cwd / '.env').exists() or (cwd / 'dbt_project.yml').exists():
+            logger.info(f"Found project directory from cwd: {cwd}")
+            return cwd
+
+        logger.debug("Could not determine project directory")
+        return None
+
+    def _find_dbt_project(self, start_dir: Path) -> Optional[str]:
+        """
+        Find dbt_project.yml in the project or its subdirectories.
+
+        Args:
+            start_dir: Directory to start searching from
+
+        Returns:
+            Path to dbt project directory, or None if not found
+        """
+        # Check root
+        if (start_dir / 'dbt_project.yml').exists():
+            return str(start_dir)
+
+        # Check common subdirectories
+        for subdir in ['dbt', 'transform', 'analytics', 'models']:
+            candidate = start_dir / subdir
+            if (candidate / 'dbt_project.yml').exists():
+                return str(candidate)
+
+        # Search one level deep
+        for item in start_dir.iterdir():
+            if item.is_dir() and not item.name.startswith('.'):
+                if (item / 'dbt_project.yml').exists():
+                    return str(item)
+
+        return None
+
+
+def load_config() -> Dict[str, Optional[str]]:
+    """
+    Convenience function to load configuration.
+
+    Returns:
+        Configuration dictionary
+    """
+    config = DataPlatformConfig()
+    return config.load()
+
+
+def check_postgres_connection() -> Dict[str, any]:
+    """
+    Check PostgreSQL connection status for SessionStart hook.
+
+    Returns:
+        Dict with connection status and message
+    """
+    import asyncio
+
+    config = load_config()
+    if not config.get('postgres_url'):
+        return {
+            'connected': False,
+            'message': 'PostgreSQL not configured (POSTGRES_URL not set)'
+        }
+
+    async def test_connection():
+        try:
+            import asyncpg
+            conn = await asyncpg.connect(config['postgres_url'], timeout=5)
+            version = await conn.fetchval('SELECT version()')
+            await conn.close()
+            return {
+                'connected': True,
+                'message': f'Connected to PostgreSQL',
+                'version': version.split(',')[0] if version else 'Unknown'
+            }
+        except Exception as e:
+            return {
+                'connected': False,
+                'message': f'PostgreSQL connection failed: {str(e)}'
+            }
+
+    return asyncio.run(test_connection())

mcp-servers/data-platform/mcp_server/data_store.py

@@ -0,0 +1,219 @@
+"""
+Arrow IPC DataFrame Registry.
+
+Provides persistent storage for DataFrames across tool calls using Apache Arrow
+for efficient memory management and serialization.
+"""
+import pyarrow as pa
+import pandas as pd
+import uuid
+import logging
+from typing import Dict, Optional, List, Union
+from dataclasses import dataclass
+from datetime import datetime
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class DataFrameInfo:
+    """Metadata about a stored DataFrame"""
+    ref: str
+    rows: int
+    columns: int
+    column_names: List[str]
+    dtypes: Dict[str, str]
+    memory_bytes: int
+    created_at: datetime
+    source: Optional[str] = None
+
+
+class DataStore:
+    """
+    Singleton registry for Arrow Tables (DataFrames).
+
+    Uses Arrow IPC format for efficient memory usage and supports
+    data_ref based retrieval across multiple tool calls.
+    """
+    _instance = None
+    _dataframes: Dict[str, pa.Table] = {}
+    _metadata: Dict[str, DataFrameInfo] = {}
+    _max_rows: int = 100_000
+
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._dataframes = {}
+            cls._metadata = {}
+        return cls._instance
+
+    @classmethod
+    def get_instance(cls) -> 'DataStore':
+        """Get the singleton instance"""
+        if cls._instance is None:
+            cls._instance = cls()
+        return cls._instance
+
+    @classmethod
+    def set_max_rows(cls, max_rows: int):
+        """Set the maximum rows limit"""
+        cls._max_rows = max_rows
+
+    def store(
+        self,
+        data: Union[pa.Table, pd.DataFrame],
+        name: Optional[str] = None,
+        source: Optional[str] = None
+    ) -> str:
+        """
+        Store a DataFrame and return its reference.
+
+        Args:
+            data: Arrow Table or pandas DataFrame
+            name: Optional name for the reference (auto-generated if not provided)
+            source: Optional source description (e.g., file path, query)
+
+        Returns:
+            data_ref string to retrieve the DataFrame later
+        """
+        # Convert pandas to Arrow if needed
+        if isinstance(data, pd.DataFrame):
+            table = pa.Table.from_pandas(data)
+        else:
+            table = data
+
+        # Generate reference
+        data_ref = name or f"df_{uuid.uuid4().hex[:8]}"
+
+        # Ensure unique reference
+        if data_ref in self._dataframes and name is None:
+            data_ref = f"{data_ref}_{uuid.uuid4().hex[:4]}"
+
+        # Store table
+        self._dataframes[data_ref] = table
+
+        # Store metadata
+        schema = table.schema
+        self._metadata[data_ref] = DataFrameInfo(
+            ref=data_ref,
+            rows=table.num_rows,
+            columns=table.num_columns,
+            column_names=[f.name for f in schema],
+            dtypes={f.name: str(f.type) for f in schema},
+            memory_bytes=table.nbytes,
+            created_at=datetime.now(),
+            source=source
+        )
+
+        logger.info(f"Stored DataFrame '{data_ref}': {table.num_rows} rows, {table.num_columns} cols")
+        return data_ref
+
+    def get(self, data_ref: str) -> Optional[pa.Table]:
+        """
+        Retrieve an Arrow Table by reference.
+
+        Args:
+            data_ref: Reference string from store()
+
+        Returns:
+            Arrow Table or None if not found
+        """
+        return self._dataframes.get(data_ref)
+
+    def get_pandas(self, data_ref: str) -> Optional[pd.DataFrame]:
+        """
+        Retrieve a DataFrame as pandas.
+
+        Args:
+            data_ref: Reference string from store()
+
+        Returns:
+            pandas DataFrame or None if not found
+        """
+        table = self.get(data_ref)
+        if table is not None:
+            return table.to_pandas()
+        return None
+
+    def get_info(self, data_ref: str) -> Optional[DataFrameInfo]:
+        """
+        Get metadata about a stored DataFrame.
+
+        Args:
+            data_ref: Reference string
+
+        Returns:
+            DataFrameInfo or None if not found
+        """
+        return self._metadata.get(data_ref)
+
+    def list_refs(self) -> List[Dict]:
+        """
+        List all stored DataFrame references with metadata.
+
+        Returns:
+            List of dicts with ref, rows, columns, memory info
+        """
+        result = []
+        for ref, info in self._metadata.items():
+            result.append({
+                'ref': ref,
+                'rows': info.rows,
+                'columns': info.columns,
+                'column_names': info.column_names,
+                'memory_mb': round(info.memory_bytes / (1024 * 1024), 2),
+                'source': info.source,
+                'created_at': info.created_at.isoformat()
+            })
+        return result
+
+    def drop(self, data_ref: str) -> bool:
+        """
+        Remove a DataFrame from the store.
+
+        Args:
+            data_ref: Reference string
+
+        Returns:
+            True if removed, False if not found
+        """
+        if data_ref in self._dataframes:
+            del self._dataframes[data_ref]
+            del self._metadata[data_ref]
+            logger.info(f"Dropped DataFrame '{data_ref}'")
+            return True
+        return False
+
+    def clear(self):
+        """Remove all stored DataFrames"""
+        count = len(self._dataframes)
+        self._dataframes.clear()
+        self._metadata.clear()
+        logger.info(f"Cleared {count} DataFrames from store")
+
+    def total_memory_bytes(self) -> int:
+        """Get total memory used by all stored DataFrames"""
+        return sum(info.memory_bytes for info in self._metadata.values())
+
+    def total_memory_mb(self) -> float:
+        """Get total memory in MB"""
+        return round(self.total_memory_bytes() / (1024 * 1024), 2)
+
+    def check_row_limit(self, row_count: int) -> Dict:
+        """
+        Check if row count exceeds limit.
+
+        Args:
+            row_count: Number of rows
+
+        Returns:
+            Dict with 'exceeded' bool and 'message' if exceeded
+        """
+        if row_count > self._max_rows:
+            return {
+                'exceeded': True,
+                'message': f"Row count ({row_count:,}) exceeds limit ({self._max_rows:,})",
+                'suggestion': f"Use chunked processing or filter data first",
+                'limit': self._max_rows
+            }
+        return {'exceeded': False}

mcp-servers/data-platform/mcp_server/dbt_tools.py

@@ -0,0 +1,387 @@
+"""
+dbt MCP Tools.
+
+Provides dbt CLI wrapper with pre-execution validation.
+"""
+import subprocess
+import json
+import logging
+import os
+from pathlib import Path
+from typing import Dict, List, Optional, Any
+
+from .config import load_config
+
+logger = logging.getLogger(__name__)
+
+
+class DbtTools:
+    """dbt CLI wrapper tools with pre-validation"""
+
+    def __init__(self):
+        self.config = load_config()
+        self.project_dir = self.config.get('dbt_project_dir')
+        self.profiles_dir = self.config.get('dbt_profiles_dir')
+
+    def _get_dbt_command(self, cmd: List[str]) -> List[str]:
+        """Build dbt command with project and profiles directories"""
+        base = ['dbt']
+        if self.project_dir:
+            base.extend(['--project-dir', self.project_dir])
+        if self.profiles_dir:
+            base.extend(['--profiles-dir', self.profiles_dir])
+        base.extend(cmd)
+        return base
+
+    def _run_dbt(
+        self,
+        cmd: List[str],
+        timeout: int = 300,
+        capture_json: bool = False
+    ) -> Dict:
+        """
+        Run dbt command and return result.
+
+        Args:
+            cmd: dbt subcommand and arguments
+            timeout: Command timeout in seconds
+            capture_json: If True, parse JSON output
+
+        Returns:
+            Dict with command result
+        """
+        if not self.project_dir:
+            return {
+                'error': 'dbt project not found',
+                'suggestion': 'Set DBT_PROJECT_DIR in project .env or ensure dbt_project.yml exists'
+            }
+
+        full_cmd = self._get_dbt_command(cmd)
+        logger.info(f"Running: {' '.join(full_cmd)}")
+
+        try:
+            env = os.environ.copy()
+            # Disable dbt analytics/tracking
+            env['DBT_SEND_ANONYMOUS_USAGE_STATS'] = 'false'
+
+            result = subprocess.run(
+                full_cmd,
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+                cwd=self.project_dir,
+                env=env
+            )
+
+            output = {
+                'success': result.returncode == 0,
+                'command': ' '.join(cmd),
+                'stdout': result.stdout,
+                'stderr': result.stderr if result.returncode != 0 else None
+            }
+
+            if capture_json and result.returncode == 0:
+                try:
+                    output['data'] = json.loads(result.stdout)
+                except json.JSONDecodeError:
+                    pass
+
+            return output
+
+        except subprocess.TimeoutExpired:
+            return {
+                'error': f'Command timed out after {timeout}s',
+                'command': ' '.join(cmd)
+            }
+        except FileNotFoundError:
+            return {
+                'error': 'dbt not found in PATH',
+                'suggestion': 'Install dbt: pip install dbt-core dbt-postgres'
+            }
+        except Exception as e:
+            logger.error(f"dbt command failed: {e}")
+            return {'error': str(e)}
+
+    async def dbt_parse(self) -> Dict:
+        """
+        Validate dbt project without executing (pre-flight check).
+
+        Returns:
+            Dict with validation result and any errors
+        """
+        result = self._run_dbt(['parse'])
+
+        # Check if _run_dbt returned an error (e.g., project not found, timeout, dbt not installed)
+        if 'error' in result:
+            return result
+
+        if not result.get('success'):
+            # Extract useful error info from stderr
+            stderr = result.get('stderr', '') or result.get('stdout', '')
+            errors = []
+
+            # Look for common dbt 1.9+ deprecation warnings
+            if 'deprecated' in stderr.lower():
+                errors.append({
+                    'type': 'deprecation',
+                    'message': 'Deprecated syntax found - check dbt 1.9+ migration guide'
+                })
+
+            # Look for compilation errors
+            if 'compilation error' in stderr.lower():
+                errors.append({
+                    'type': 'compilation',
+                    'message': 'SQL compilation error - check model syntax'
+                })
+
+            return {
+                'valid': False,
+                'errors': errors,
+                'details': stderr[:2000] if stderr else None,
+                'suggestion': 'Fix issues before running dbt models'
+            }
+
+        return {
+            'valid': True,
+            'message': 'dbt project validation passed'
+        }
+
+    async def dbt_run(
+        self,
+        select: Optional[str] = None,
+        exclude: Optional[str] = None,
+        full_refresh: bool = False
+    ) -> Dict:
+        """
+        Run dbt models with pre-validation.
+
+        Args:
+            select: Model selection (e.g., "model_name", "+model_name", "tag:daily")
+            exclude: Models to exclude
+            full_refresh: If True, rebuild incremental models
+
+        Returns:
+            Dict with run result
+        """
+        # ALWAYS validate first
+        parse_result = await self.dbt_parse()
+        if not parse_result.get('valid'):
+            return {
+                'error': 'Pre-validation failed',
+                **parse_result
+            }
+
+        cmd = ['run']
+        if select:
+            cmd.extend(['--select', select])
+        if exclude:
+            cmd.extend(['--exclude', exclude])
+        if full_refresh:
+            cmd.append('--full-refresh')
+
+        return self._run_dbt(cmd)
+
+    async def dbt_test(
+        self,
+        select: Optional[str] = None,
+        exclude: Optional[str] = None
+    ) -> Dict:
+        """
+        Run dbt tests.
+
+        Args:
+            select: Test selection
+            exclude: Tests to exclude
+
+        Returns:
+            Dict with test results
+        """
+        cmd = ['test']
+        if select:
+            cmd.extend(['--select', select])
+        if exclude:
+            cmd.extend(['--exclude', exclude])
+
+        return self._run_dbt(cmd)
+
+    async def dbt_build(
+        self,
+        select: Optional[str] = None,
+        exclude: Optional[str] = None,
+        full_refresh: bool = False
+    ) -> Dict:
+        """
+        Run dbt build (run + test) with pre-validation.
+
+        Args:
+            select: Model/test selection
+            exclude: Resources to exclude
+            full_refresh: If True, rebuild incremental models
+
+        Returns:
+            Dict with build result
+        """
+        # ALWAYS validate first
+        parse_result = await self.dbt_parse()
+        if not parse_result.get('valid'):
+            return {
+                'error': 'Pre-validation failed',
+                **parse_result
+            }
+
+        cmd = ['build']
+        if select:
+            cmd.extend(['--select', select])
+        if exclude:
+            cmd.extend(['--exclude', exclude])
+        if full_refresh:
+            cmd.append('--full-refresh')
+
+        return self._run_dbt(cmd)
+
+    async def dbt_compile(
+        self,
+        select: Optional[str] = None
+    ) -> Dict:
+        """
+        Compile dbt models to SQL without executing.
+
+        Args:
+            select: Model selection
+
+        Returns:
+            Dict with compiled SQL info
+        """
+        cmd = ['compile']
+        if select:
+            cmd.extend(['--select', select])
+
+        return self._run_dbt(cmd)
+
+    async def dbt_ls(
+        self,
+        select: Optional[str] = None,
+        resource_type: Optional[str] = None,
+        output: str = 'name'
+    ) -> Dict:
+        """
+        List dbt resources.
+
+        Args:
+            select: Resource selection
+            resource_type: Filter by type (model, test, seed, snapshot, source)
+            output: Output format ('name', 'path', 'json')
+
+        Returns:
+            Dict with list of resources
+        """
+        cmd = ['ls', '--output', output]
+        if select:
+            cmd.extend(['--select', select])
+        if resource_type:
+            cmd.extend(['--resource-type', resource_type])
+
+        result = self._run_dbt(cmd)
+
+        if result.get('success') and result.get('stdout'):
+            lines = [l.strip() for l in result['stdout'].split('\n') if l.strip()]
+            result['resources'] = lines
+            result['count'] = len(lines)
+
+        return result
+
+    async def dbt_docs_generate(self) -> Dict:
+        """
+        Generate dbt documentation.
+
+        Returns:
+            Dict with generation result
+        """
+        result = self._run_dbt(['docs', 'generate'])
+
+        if result.get('success') and self.project_dir:
+            # Check for generated catalog
+            catalog_path = Path(self.project_dir) / 'target' / 'catalog.json'
+            manifest_path = Path(self.project_dir) / 'target' / 'manifest.json'
+            result['catalog_generated'] = catalog_path.exists()
+            result['manifest_generated'] = manifest_path.exists()
+
+        return result
+
+    async def dbt_lineage(self, model: str) -> Dict:
+        """
+        Get model dependencies and lineage.
+
+        Args:
+            model: Model name to analyze
+
+        Returns:
+            Dict with upstream and downstream dependencies
+        """
+        if not self.project_dir:
+            return {'error': 'dbt project not found'}
+
+        manifest_path = Path(self.project_dir) / 'target' / 'manifest.json'
+
+        # Generate manifest if not exists
+        if not manifest_path.exists():
+            compile_result = await self.dbt_compile(select=model)
+            if not compile_result.get('success'):
+                return {
+                    'error': 'Failed to compile manifest',
+                    'details': compile_result
+                }
+
+        if not manifest_path.exists():
+            return {
+                'error': 'Manifest not found',
+                'suggestion': 'Run dbt compile first'
+            }
+
+        try:
+            with open(manifest_path) as f:
+                manifest = json.load(f)
+
+            # Find the model node
+            model_key = None
+            for key in manifest.get('nodes', {}):
+                if key.endswith(f'.{model}') or manifest['nodes'][key].get('name') == model:
+                    model_key = key
+                    break
+
+            if not model_key:
+                return {
+                    'error': f'Model not found: {model}',
+                    'available_models': [
+                        n.get('name') for n in manifest.get('nodes', {}).values()
+                        if n.get('resource_type') == 'model'
+                    ][:20]
+                }
+
+            node = manifest['nodes'][model_key]
+
+            # Get upstream (depends_on)
+            upstream = node.get('depends_on', {}).get('nodes', [])
+
+            # Get downstream (find nodes that depend on this one)
+            downstream = []
+            for key, other_node in manifest.get('nodes', {}).items():
+                deps = other_node.get('depends_on', {}).get('nodes', [])
+                if model_key in deps:
+                    downstream.append(key)
+
+            return {
+                'model': model,
+                'unique_id': model_key,
+                'materialization': node.get('config', {}).get('materialized'),
+                'schema': node.get('schema'),
+                'database': node.get('database'),
+                'upstream': upstream,
+                'downstream': downstream,
+                'description': node.get('description'),
+                'tags': node.get('tags', [])
+            }
+
+        except Exception as e:
+            logger.error(f"dbt_lineage failed: {e}")
+            return {'error': str(e)}

mcp-servers/data-platform/mcp_server/pandas_tools.py

@@ -0,0 +1,500 @@
+"""
+pandas MCP Tools.
+
+Provides DataFrame operations with Arrow IPC data_ref persistence.
+"""
+import pandas as pd
+import pyarrow as pa
+import pyarrow.parquet as pq
+import json
+import logging
+from pathlib import Path
+from typing import Dict, List, Optional, Any, Union
+
+from .data_store import DataStore
+from .config import load_config
+
+logger = logging.getLogger(__name__)
+
+
+class PandasTools:
+    """pandas data manipulation tools with data_ref persistence"""
+
+    def __init__(self):
+        self.store = DataStore.get_instance()
+        config = load_config()
+        self.max_rows = config.get('max_rows', 100_000)
+        self.store.set_max_rows(self.max_rows)
+
+    def _check_and_store(
+        self,
+        df: pd.DataFrame,
+        name: Optional[str] = None,
+        source: Optional[str] = None
+    ) -> Dict:
+        """Check row limit and store DataFrame if within limits"""
+        check = self.store.check_row_limit(len(df))
+        if check['exceeded']:
+            return {
+                'error': 'row_limit_exceeded',
+                **check,
+                'preview': df.head(100).to_dict(orient='records')
+            }
+
+        data_ref = self.store.store(df, name=name, source=source)
+        return {
+            'data_ref': data_ref,
+            'rows': len(df),
+            'columns': list(df.columns),
+            'dtypes': {col: str(dtype) for col, dtype in df.dtypes.items()}
+        }
+
+    async def read_csv(
+        self,
+        file_path: str,
+        name: Optional[str] = None,
+        chunk_size: Optional[int] = None,
+        **kwargs
+    ) -> Dict:
+        """
+        Load CSV file into DataFrame.
+
+        Args:
+            file_path: Path to CSV file
+            name: Optional name for data_ref
+            chunk_size: If provided, process in chunks
+            **kwargs: Additional pandas read_csv arguments
+
+        Returns:
+            Dict with data_ref or error info
+        """
+        path = Path(file_path)
+        if not path.exists():
+            return {'error': f'File not found: {file_path}'}
+
+        try:
+            if chunk_size:
+                # Chunked processing - return iterator info
+                chunks = []
+                for i, chunk in enumerate(pd.read_csv(path, chunksize=chunk_size, **kwargs)):
+                    chunk_ref = self.store.store(chunk, name=f"{name or 'chunk'}_{i}", source=file_path)
+                    chunks.append({'ref': chunk_ref, 'rows': len(chunk)})
+                return {
+                    'chunked': True,
+                    'chunks': chunks,
+                    'total_chunks': len(chunks)
+                }
+
+            df = pd.read_csv(path, **kwargs)
+            return self._check_and_store(df, name=name, source=file_path)
+
+        except Exception as e:
+            logger.error(f"read_csv failed: {e}")
+            return {'error': str(e)}
+
+    async def read_parquet(
+        self,
+        file_path: str,
+        name: Optional[str] = None,
+        columns: Optional[List[str]] = None
+    ) -> Dict:
+        """
+        Load Parquet file into DataFrame.
+
+        Args:
+            file_path: Path to Parquet file
+            name: Optional name for data_ref
+            columns: Optional list of columns to load
+
+        Returns:
+            Dict with data_ref or error info
+        """
+        path = Path(file_path)
+        if not path.exists():
+            return {'error': f'File not found: {file_path}'}
+
+        try:
+            table = pq.read_table(path, columns=columns)
+            df = table.to_pandas()
+            return self._check_and_store(df, name=name, source=file_path)
+
+        except Exception as e:
+            logger.error(f"read_parquet failed: {e}")
+            return {'error': str(e)}
+
+    async def read_json(
+        self,
+        file_path: str,
+        name: Optional[str] = None,
+        lines: bool = False,
+        **kwargs
+    ) -> Dict:
+        """
+        Load JSON/JSONL file into DataFrame.
+
+        Args:
+            file_path: Path to JSON file
+            name: Optional name for data_ref
+            lines: If True, read as JSON Lines format
+            **kwargs: Additional pandas read_json arguments
+
+        Returns:
+            Dict with data_ref or error info
+        """
+        path = Path(file_path)
+        if not path.exists():
+            return {'error': f'File not found: {file_path}'}
+
+        try:
+            df = pd.read_json(path, lines=lines, **kwargs)
+            return self._check_and_store(df, name=name, source=file_path)
+
+        except Exception as e:
+            logger.error(f"read_json failed: {e}")
+            return {'error': str(e)}
+
+    async def to_csv(
+        self,
+        data_ref: str,
+        file_path: str,
+        index: bool = False,
+        **kwargs
+    ) -> Dict:
+        """
+        Export DataFrame to CSV file.
+
+        Args:
+            data_ref: Reference to stored DataFrame
+            file_path: Output file path
+            index: Whether to include index
+            **kwargs: Additional pandas to_csv arguments
+
+        Returns:
+            Dict with success status
+        """
+        df = self.store.get_pandas(data_ref)
+        if df is None:
+            return {'error': f'DataFrame not found: {data_ref}'}
+
+        try:
+            df.to_csv(file_path, index=index, **kwargs)
+            return {
+                'success': True,
+                'file_path': file_path,
+                'rows': len(df),
+                'size_bytes': Path(file_path).stat().st_size
+            }
+        except Exception as e:
+            logger.error(f"to_csv failed: {e}")
+            return {'error': str(e)}
+
+    async def to_parquet(
+        self,
+        data_ref: str,
+        file_path: str,
+        compression: str = 'snappy'
+    ) -> Dict:
+        """
+        Export DataFrame to Parquet file.
+
+        Args:
+            data_ref: Reference to stored DataFrame
+            file_path: Output file path
+            compression: Compression codec
+
+        Returns:
+            Dict with success status
+        """
+        table = self.store.get(data_ref)
+        if table is None:
+            return {'error': f'DataFrame not found: {data_ref}'}
+
+        try:
+            pq.write_table(table, file_path, compression=compression)
+            return {
+                'success': True,
+                'file_path': file_path,
+                'rows': table.num_rows,
+                'size_bytes': Path(file_path).stat().st_size
+            }
+        except Exception as e:
+            logger.error(f"to_parquet failed: {e}")
+            return {'error': str(e)}
+
+    async def describe(self, data_ref: str) -> Dict:
+        """
+        Get statistical summary of DataFrame.
+
+        Args:
+            data_ref: Reference to stored DataFrame
+
+        Returns:
+            Dict with statistical summary
+        """
+        df = self.store.get_pandas(data_ref)
+        if df is None:
+            return {'error': f'DataFrame not found: {data_ref}'}
+
+        try:
+            desc = df.describe(include='all')
+            info = self.store.get_info(data_ref)
+
+            return {
+                'data_ref': data_ref,
+                'shape': {'rows': len(df), 'columns': len(df.columns)},
+                'columns': list(df.columns),
+                'dtypes': {col: str(dtype) for col, dtype in df.dtypes.items()},
+                'memory_mb': info.memory_bytes / (1024 * 1024) if info else None,
+                'null_counts': df.isnull().sum().to_dict(),
+                'statistics': desc.to_dict()
+            }
+        except Exception as e:
+            logger.error(f"describe failed: {e}")
+            return {'error': str(e)}
+
+    async def head(self, data_ref: str, n: int = 10) -> Dict:
+        """
+        Get first N rows of DataFrame.
+
+        Args:
+            data_ref: Reference to stored DataFrame
+            n: Number of rows
+
+        Returns:
+            Dict with rows as records
+        """
+        df = self.store.get_pandas(data_ref)
+        if df is None:
+            return {'error': f'DataFrame not found: {data_ref}'}
+
+        try:
+            head_df = df.head(n)
+            return {
+                'data_ref': data_ref,
+                'total_rows': len(df),
+                'returned_rows': len(head_df),
+                'columns': list(df.columns),
+                'data': head_df.to_dict(orient='records')
+            }
+        except Exception as e:
+            logger.error(f"head failed: {e}")
+            return {'error': str(e)}
+
+    async def tail(self, data_ref: str, n: int = 10) -> Dict:
+        """
+        Get last N rows of DataFrame.
+
+        Args:
+            data_ref: Reference to stored DataFrame
+            n: Number of rows
+
+        Returns:
+            Dict with rows as records
+        """
+        df = self.store.get_pandas(data_ref)
+        if df is None:
+            return {'error': f'DataFrame not found: {data_ref}'}
+
+        try:
+            tail_df = df.tail(n)
+            return {
+                'data_ref': data_ref,
+                'total_rows': len(df),
+                'returned_rows': len(tail_df),
+                'columns': list(df.columns),
+                'data': tail_df.to_dict(orient='records')
+            }
+        except Exception as e:
+            logger.error(f"tail failed: {e}")
+            return {'error': str(e)}
+
+    async def filter(
+        self,
+        data_ref: str,
+        condition: str,
+        name: Optional[str] = None
+    ) -> Dict:
+        """
+        Filter DataFrame rows by condition.
+
+        Args:
+            data_ref: Reference to stored DataFrame
+            condition: pandas query string (e.g., "age > 30 and city == 'NYC'")
+            name: Optional name for result data_ref
+
+        Returns:
+            Dict with new data_ref for filtered result
+        """
+        df = self.store.get_pandas(data_ref)
+        if df is None:
+            return {'error': f'DataFrame not found: {data_ref}'}
+
+        try:
+            filtered = df.query(condition).reset_index(drop=True)
+            result_name = name or f"{data_ref}_filtered"
+            return self._check_and_store(
+                filtered,
+                name=result_name,
+                source=f"filter({data_ref}, '{condition}')"
+            )
+        except Exception as e:
+            logger.error(f"filter failed: {e}")
+            return {'error': str(e)}
+
+    async def select(
+        self,
+        data_ref: str,
+        columns: List[str],
+        name: Optional[str] = None
+    ) -> Dict:
+        """
+        Select specific columns from DataFrame.
+
+        Args:
+            data_ref: Reference to stored DataFrame
+            columns: List of column names to select
+            name: Optional name for result data_ref
+
+        Returns:
+            Dict with new data_ref for selected columns
+        """
+        df = self.store.get_pandas(data_ref)
+        if df is None:
+            return {'error': f'DataFrame not found: {data_ref}'}
+
+        try:
+            # Validate columns exist
+            missing = [c for c in columns if c not in df.columns]
+            if missing:
+                return {
+                    'error': f'Columns not found: {missing}',
+                    'available_columns': list(df.columns)
+                }
+
+            selected = df[columns]
+            result_name = name or f"{data_ref}_select"
+            return self._check_and_store(
+                selected,
+                name=result_name,
+                source=f"select({data_ref}, {columns})"
+            )
+        except Exception as e:
+            logger.error(f"select failed: {e}")
+            return {'error': str(e)}
+
+    async def groupby(
+        self,
+        data_ref: str,
+        by: Union[str, List[str]],
+        agg: Dict[str, Union[str, List[str]]],
+        name: Optional[str] = None
+    ) -> Dict:
+        """
+        Group DataFrame and aggregate.
+
+        Args:
+            data_ref: Reference to stored DataFrame
+            by: Column(s) to group by
+            agg: Aggregation dict (e.g., {"sales": "sum", "count": "mean"})
+            name: Optional name for result data_ref
+
+        Returns:
+            Dict with new data_ref for aggregated result
+        """
+        df = self.store.get_pandas(data_ref)
+        if df is None:
+            return {'error': f'DataFrame not found: {data_ref}'}
+
+        try:
+            grouped = df.groupby(by).agg(agg).reset_index()
+            # Flatten column names if multi-level
+            if isinstance(grouped.columns, pd.MultiIndex):
+                grouped.columns = ['_'.join(col).strip('_') for col in grouped.columns]
+
+            result_name = name or f"{data_ref}_grouped"
+            return self._check_and_store(
+                grouped,
+                name=result_name,
+                source=f"groupby({data_ref}, by={by})"
+            )
+        except Exception as e:
+            logger.error(f"groupby failed: {e}")
+            return {'error': str(e)}
+
+    async def join(
+        self,
+        left_ref: str,
+        right_ref: str,
+        on: Optional[Union[str, List[str]]] = None,
+        left_on: Optional[Union[str, List[str]]] = None,
+        right_on: Optional[Union[str, List[str]]] = None,
+        how: str = 'inner',
+        name: Optional[str] = None
+    ) -> Dict:
+        """
+        Join two DataFrames.
+
+        Args:
+            left_ref: Reference to left DataFrame
+            right_ref: Reference to right DataFrame
+            on: Column(s) to join on (if same name in both)
+            left_on: Left join column(s)
+            right_on: Right join column(s)
+            how: Join type ('inner', 'left', 'right', 'outer')
+            name: Optional name for result data_ref
+
+        Returns:
+            Dict with new data_ref for joined result
+        """
+        left_df = self.store.get_pandas(left_ref)
+        right_df = self.store.get_pandas(right_ref)
+
+        if left_df is None:
+            return {'error': f'DataFrame not found: {left_ref}'}
+        if right_df is None:
+            return {'error': f'DataFrame not found: {right_ref}'}
+
+        try:
+            joined = pd.merge(
+                left_df, right_df,
+                on=on, left_on=left_on, right_on=right_on,
+                how=how
+            )
+            result_name = name or f"{left_ref}_{right_ref}_joined"
+            return self._check_and_store(
+                joined,
+                name=result_name,
+                source=f"join({left_ref}, {right_ref}, how={how})"
+            )
+        except Exception as e:
+            logger.error(f"join failed: {e}")
+            return {'error': str(e)}
+
+    async def list_data(self) -> Dict:
+        """
+        List all stored DataFrames.
+
+        Returns:
+            Dict with list of stored DataFrames and their info
+        """
+        refs = self.store.list_refs()
+        return {
+            'count': len(refs),
+            'total_memory_mb': self.store.total_memory_mb(),
+            'max_rows_limit': self.max_rows,
+            'dataframes': refs
+        }
+
+    async def drop_data(self, data_ref: str) -> Dict:
+        """
+        Remove a DataFrame from storage.
+
+        Args:
+            data_ref: Reference to drop
+
+        Returns:
+            Dict with success status
+        """
+        if self.store.drop(data_ref):
+            return {'success': True, 'dropped': data_ref}
+        return {'error': f'DataFrame not found: {data_ref}'}

mcp-servers/data-platform/mcp_server/postgres_tools.py

@@ -0,0 +1,538 @@
+"""
+PostgreSQL/PostGIS MCP Tools.
+
+Provides database operations with connection pooling and PostGIS support.
+"""
+import asyncio
+import logging
+from typing import Dict, List, Optional, Any
+import json
+
+from .data_store import DataStore
+from .config import load_config
+
+logger = logging.getLogger(__name__)
+
+# Optional imports - gracefully handle missing dependencies
+try:
+    import asyncpg
+    ASYNCPG_AVAILABLE = True
+except ImportError:
+    ASYNCPG_AVAILABLE = False
+    logger.warning("asyncpg not available - PostgreSQL tools will be disabled")
+
+try:
+    import pandas as pd
+    PANDAS_AVAILABLE = True
+except ImportError:
+    PANDAS_AVAILABLE = False
+
+
+class PostgresTools:
+    """PostgreSQL/PostGIS database tools"""
+
+    def __init__(self):
+        self.store = DataStore.get_instance()
+        self.config = load_config()
+        self.pool: Optional[Any] = None
+        self.max_rows = self.config.get('max_rows', 100_000)
+
+    async def _get_pool(self):
+        """Get or create connection pool"""
+        if not ASYNCPG_AVAILABLE:
+            raise RuntimeError("asyncpg not installed - run: pip install asyncpg")
+
+        if self.pool is None:
+            postgres_url = self.config.get('postgres_url')
+            if not postgres_url:
+                raise RuntimeError(
+                    "PostgreSQL not configured. Set POSTGRES_URL in "
+                    "~/.config/claude/postgres.env"
+                )
+            self.pool = await asyncpg.create_pool(postgres_url, min_size=1, max_size=5)
+        return self.pool
+
+    async def pg_connect(self) -> Dict:
+        """
+        Test PostgreSQL connection and return status.
+
+        Returns:
+            Dict with connection status, version, and database info
+        """
+        if not ASYNCPG_AVAILABLE:
+            return {
+                'connected': False,
+                'error': 'asyncpg not installed',
+                'suggestion': 'pip install asyncpg'
+            }
+
+        postgres_url = self.config.get('postgres_url')
+        if not postgres_url:
+            return {
+                'connected': False,
+                'error': 'POSTGRES_URL not configured',
+                'suggestion': 'Create ~/.config/claude/postgres.env with POSTGRES_URL=postgresql://...'
+            }
+
+        try:
+            pool = await self._get_pool()
+            async with pool.acquire() as conn:
+                version = await conn.fetchval('SELECT version()')
+                db_name = await conn.fetchval('SELECT current_database()')
+                user = await conn.fetchval('SELECT current_user')
+
+                # Check for PostGIS
+                postgis_version = None
+                try:
+                    postgis_version = await conn.fetchval('SELECT PostGIS_Version()')
+                except Exception:
+                    pass
+
+                return {
+                    'connected': True,
+                    'database': db_name,
+                    'user': user,
+                    'version': version.split(',')[0] if version else 'Unknown',
+                    'postgis_version': postgis_version,
+                    'postgis_available': postgis_version is not None
+                }
+
+        except Exception as e:
+            logger.error(f"pg_connect failed: {e}")
+            return {
+                'connected': False,
+                'error': str(e)
+            }
+
+    async def pg_query(
+        self,
+        query: str,
+        params: Optional[List] = None,
+        name: Optional[str] = None
+    ) -> Dict:
+        """
+        Execute SELECT query and return results as data_ref.
+
+        Args:
+            query: SQL SELECT query
+            params: Query parameters (positional, use $1, $2, etc.)
+            name: Optional name for result data_ref
+
+        Returns:
+            Dict with data_ref for results or error
+        """
+        if not PANDAS_AVAILABLE:
+            return {'error': 'pandas not available'}
+
+        try:
+            pool = await self._get_pool()
+            async with pool.acquire() as conn:
+                if params:
+                    rows = await conn.fetch(query, *params)
+                else:
+                    rows = await conn.fetch(query)
+
+                if not rows:
+                    return {
+                        'data_ref': None,
+                        'rows': 0,
+                        'message': 'Query returned no results'
+                    }
+
+                # Convert to DataFrame
+                df = pd.DataFrame([dict(r) for r in rows])
+
+                # Check row limit
+                check = self.store.check_row_limit(len(df))
+                if check['exceeded']:
+                    return {
+                        'error': 'row_limit_exceeded',
+                        **check,
+                        'preview': df.head(100).to_dict(orient='records')
+                    }
+
+                # Store result
+                data_ref = self.store.store(df, name=name, source=f"pg_query: {query[:100]}...")
+                return {
+                    'data_ref': data_ref,
+                    'rows': len(df),
+                    'columns': list(df.columns)
+                }
+
+        except Exception as e:
+            logger.error(f"pg_query failed: {e}")
+            return {'error': str(e)}
+
+    async def pg_execute(
+        self,
+        query: str,
+        params: Optional[List] = None
+    ) -> Dict:
+        """
+        Execute INSERT/UPDATE/DELETE query.
+
+        Args:
+            query: SQL DML query
+            params: Query parameters
+
+        Returns:
+            Dict with affected rows count
+        """
+        try:
+            pool = await self._get_pool()
+            async with pool.acquire() as conn:
+                if params:
+                    result = await conn.execute(query, *params)
+                else:
+                    result = await conn.execute(query)
+
+                # Parse result (e.g., "INSERT 0 1" or "UPDATE 5")
+                parts = result.split()
+                affected = int(parts[-1]) if parts else 0
+
+                return {
+                    'success': True,
+                    'command': parts[0] if parts else 'UNKNOWN',
+                    'affected_rows': affected
+                }
+
+        except Exception as e:
+            logger.error(f"pg_execute failed: {e}")
+            return {'error': str(e)}
+
+    async def pg_tables(self, schema: str = 'public') -> Dict:
+        """
+        List all tables in schema.
+
+        Args:
+            schema: Schema name (default: public)
+
+        Returns:
+            Dict with list of tables
+        """
+        query = """
+            SELECT
+                table_name,
+                table_type,
+                (SELECT count(*) FROM information_schema.columns c
+                 WHERE c.table_schema = t.table_schema
+                 AND c.table_name = t.table_name) as column_count
+            FROM information_schema.tables t
+            WHERE table_schema = $1
+            ORDER BY table_name
+        """
+        try:
+            pool = await self._get_pool()
+            async with pool.acquire() as conn:
+                rows = await conn.fetch(query, schema)
+                tables = [
+                    {
+                        'name': r['table_name'],
+                        'type': r['table_type'],
+                        'columns': r['column_count']
+                    }
+                    for r in rows
+                ]
+                return {
+                    'schema': schema,
+                    'count': len(tables),
+                    'tables': tables
+                }
+        except Exception as e:
+            logger.error(f"pg_tables failed: {e}")
+            return {'error': str(e)}
+
+    async def pg_columns(self, table: str, schema: str = 'public') -> Dict:
+        """
+        Get column information for a table.
+
+        Args:
+            table: Table name
+            schema: Schema name (default: public)
+
+        Returns:
+            Dict with column details
+        """
+        query = """
+            SELECT
+                column_name,
+                data_type,
+                udt_name,
+                is_nullable,
+                column_default,
+                character_maximum_length,
+                numeric_precision
+            FROM information_schema.columns
+            WHERE table_schema = $1 AND table_name = $2
+            ORDER BY ordinal_position
+        """
+        try:
+            pool = await self._get_pool()
+            async with pool.acquire() as conn:
+                rows = await conn.fetch(query, schema, table)
+                columns = [
+                    {
+                        'name': r['column_name'],
+                        'type': r['data_type'],
+                        'udt': r['udt_name'],
+                        'nullable': r['is_nullable'] == 'YES',
+                        'default': r['column_default'],
+                        'max_length': r['character_maximum_length'],
+                        'precision': r['numeric_precision']
+                    }
+                    for r in rows
+                ]
+                return {
+                    'table': f'{schema}.{table}',
+                    'column_count': len(columns),
+                    'columns': columns
+                }
+        except Exception as e:
+            logger.error(f"pg_columns failed: {e}")
+            return {'error': str(e)}
+
+    async def pg_schemas(self) -> Dict:
+        """
+        List all schemas in database.
+
+        Returns:
+            Dict with list of schemas
+        """
+        query = """
+            SELECT schema_name
+            FROM information_schema.schemata
+            WHERE schema_name NOT IN ('pg_catalog', 'information_schema', 'pg_toast')
+            ORDER BY schema_name
+        """
+        try:
+            pool = await self._get_pool()
+            async with pool.acquire() as conn:
+                rows = await conn.fetch(query)
+                schemas = [r['schema_name'] for r in rows]
+                return {
+                    'count': len(schemas),
+                    'schemas': schemas
+                }
+        except Exception as e:
+            logger.error(f"pg_schemas failed: {e}")
+            return {'error': str(e)}
+
+    async def st_tables(self, schema: str = 'public') -> Dict:
+        """
+        List PostGIS-enabled tables.
+
+        Args:
+            schema: Schema name (default: public)
+
+        Returns:
+            Dict with list of tables with geometry columns
+        """
+        query = """
+            SELECT
+                f_table_name as table_name,
+                f_geometry_column as geometry_column,
+                type as geometry_type,
+                srid,
+                coord_dimension
+            FROM geometry_columns
+            WHERE f_table_schema = $1
+            ORDER BY f_table_name
+        """
+        try:
+            pool = await self._get_pool()
+            async with pool.acquire() as conn:
+                rows = await conn.fetch(query, schema)
+                tables = [
+                    {
+                        'table': r['table_name'],
+                        'geometry_column': r['geometry_column'],
+                        'geometry_type': r['geometry_type'],
+                        'srid': r['srid'],
+                        'dimensions': r['coord_dimension']
+                    }
+                    for r in rows
+                ]
+                return {
+                    'schema': schema,
+                    'count': len(tables),
+                    'postgis_tables': tables
+                }
+        except Exception as e:
+            if 'geometry_columns' in str(e):
+                return {
+                    'error': 'PostGIS not installed or extension not enabled',
+                    'suggestion': 'Run: CREATE EXTENSION IF NOT EXISTS postgis;'
+                }
+            logger.error(f"st_tables failed: {e}")
+            return {'error': str(e)}
+
+    async def st_geometry_type(self, table: str, column: str, schema: str = 'public') -> Dict:
+        """
+        Get geometry type of a column.
+
+        Args:
+            table: Table name
+            column: Geometry column name
+            schema: Schema name
+
+        Returns:
+            Dict with geometry type information
+        """
+        query = f"""
+            SELECT DISTINCT ST_GeometryType({column}) as geom_type
+            FROM {schema}.{table}
+            WHERE {column} IS NOT NULL
+            LIMIT 10
+        """
+        try:
+            pool = await self._get_pool()
+            async with pool.acquire() as conn:
+                rows = await conn.fetch(query)
+                types = [r['geom_type'] for r in rows]
+                return {
+                    'table': f'{schema}.{table}',
+                    'column': column,
+                    'geometry_types': types
+                }
+        except Exception as e:
+            logger.error(f"st_geometry_type failed: {e}")
+            return {'error': str(e)}
+
+    async def st_srid(self, table: str, column: str, schema: str = 'public') -> Dict:
+        """
+        Get SRID of geometry column.
+
+        Args:
+            table: Table name
+            column: Geometry column name
+            schema: Schema name
+
+        Returns:
+            Dict with SRID information
+        """
+        query = f"""
+            SELECT DISTINCT ST_SRID({column}) as srid
+            FROM {schema}.{table}
+            WHERE {column} IS NOT NULL
+            LIMIT 1
+        """
+        try:
+            pool = await self._get_pool()
+            async with pool.acquire() as conn:
+                row = await conn.fetchrow(query)
+                srid = row['srid'] if row else None
+
+                # Get SRID description
+                srid_info = None
+                if srid:
+                    srid_query = """
+                        SELECT srtext, proj4text
+                        FROM spatial_ref_sys
+                        WHERE srid = $1
+                    """
+                    srid_row = await conn.fetchrow(srid_query, srid)
+                    if srid_row:
+                        srid_info = {
+                            'description': srid_row['srtext'][:200] if srid_row['srtext'] else None,
+                            'proj4': srid_row['proj4text']
+                        }
+
+                return {
+                    'table': f'{schema}.{table}',
+                    'column': column,
+                    'srid': srid,
+                    'info': srid_info
+                }
+        except Exception as e:
+            logger.error(f"st_srid failed: {e}")
+            return {'error': str(e)}
+
+    async def st_extent(self, table: str, column: str, schema: str = 'public') -> Dict:
+        """
+        Get bounding box of all geometries.
+
+        Args:
+            table: Table name
+            column: Geometry column name
+            schema: Schema name
+
+        Returns:
+            Dict with bounding box coordinates
+        """
+        query = f"""
+            SELECT
+                ST_XMin(extent) as xmin,
+                ST_YMin(extent) as ymin,
+                ST_XMax(extent) as xmax,
+                ST_YMax(extent) as ymax
+            FROM (
+                SELECT ST_Extent({column}) as extent
+                FROM {schema}.{table}
+            ) sub
+        """
+        try:
+            pool = await self._get_pool()
+            async with pool.acquire() as conn:
+                row = await conn.fetchrow(query)
+                if row and row['xmin'] is not None:
+                    return {
+                        'table': f'{schema}.{table}',
+                        'column': column,
+                        'bbox': {
+                            'xmin': float(row['xmin']),
+                            'ymin': float(row['ymin']),
+                            'xmax': float(row['xmax']),
+                            'ymax': float(row['ymax'])
+                        }
+                    }
+                return {
+                    'table': f'{schema}.{table}',
+                    'column': column,
+                    'bbox': None,
+                    'message': 'No geometries found or all NULL'
+                }
+        except Exception as e:
+            logger.error(f"st_extent failed: {e}")
+            return {'error': str(e)}
+
+    async def close(self):
+        """Close connection pool"""
+        if self.pool:
+            await self.pool.close()
+            self.pool = None
+
+
+def check_connection() -> None:
+    """
+    Check PostgreSQL connection for SessionStart hook.
+    Prints warning to stderr if connection fails.
+    """
+    import sys
+
+    config = load_config()
+    if not config.get('postgres_url'):
+        print(
+            "[data-platform] PostgreSQL not configured (POSTGRES_URL not set)",
+            file=sys.stderr
+        )
+        return
+
+    async def test():
+        try:
+            if not ASYNCPG_AVAILABLE:
+                print(
+                    "[data-platform] asyncpg not installed - PostgreSQL tools unavailable",
+                    file=sys.stderr
+                )
+                return
+
+            conn = await asyncpg.connect(config['postgres_url'], timeout=5)
+            await conn.close()
+            print("[data-platform] PostgreSQL connection OK", file=sys.stderr)
+        except Exception as e:
+            print(
+                f"[data-platform] PostgreSQL connection failed: {e}",
+                file=sys.stderr
+            )
+
+    asyncio.run(test())

mcp-servers/data-platform/mcp_server/server.py

@@ -0,0 +1,795 @@
+"""
+MCP Server entry point for Data Platform integration.
+
+Provides pandas, PostgreSQL/PostGIS, and dbt tools to Claude Code via JSON-RPC 2.0 over stdio.
+"""
+import asyncio
+import logging
+import json
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import Tool, TextContent
+
+from .config import DataPlatformConfig
+from .data_store import DataStore
+from .pandas_tools import PandasTools
+from .postgres_tools import PostgresTools
+from .dbt_tools import DbtTools
+
+# Suppress noisy MCP validation warnings on stderr
+logging.basicConfig(level=logging.INFO)
+logging.getLogger("root").setLevel(logging.ERROR)
+logging.getLogger("mcp").setLevel(logging.ERROR)
+logger = logging.getLogger(__name__)
+
+
+class DataPlatformMCPServer:
+    """MCP Server for data platform integration"""
+
+    def __init__(self):
+        self.server = Server("data-platform-mcp")
+        self.config = None
+        self.pandas_tools = None
+        self.postgres_tools = None
+        self.dbt_tools = None
+
+    async def initialize(self):
+        """Initialize server and load configuration."""
+        try:
+            config_loader = DataPlatformConfig()
+            self.config = config_loader.load()
+
+            self.pandas_tools = PandasTools()
+            self.postgres_tools = PostgresTools()
+            self.dbt_tools = DbtTools()
+
+            # Log available capabilities
+            caps = []
+            caps.append("pandas")
+            if self.config.get('postgres_available'):
+                caps.append("PostgreSQL")
+            if self.config.get('dbt_available'):
+                caps.append("dbt")
+
+            logger.info(f"Data Platform MCP Server initialized with: {', '.join(caps)}")
+
+        except Exception as e:
+            logger.error(f"Failed to initialize: {e}")
+            raise
+
+    def setup_tools(self):
+        """Register all available tools with the MCP server"""
+
+        @self.server.list_tools()
+        async def list_tools() -> list[Tool]:
+            """Return list of available tools"""
+            tools = [
+                # pandas tools - always available
+                Tool(
+                    name="read_csv",
+                    description="Load CSV file into DataFrame",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "file_path": {
+                                "type": "string",
+                                "description": "Path to CSV file"
+                            },
+                            "name": {
+                                "type": "string",
+                                "description": "Optional name for data_ref"
+                            },
+                            "chunk_size": {
+                                "type": "integer",
+                                "description": "Process in chunks of this size"
+                            }
+                        },
+                        "required": ["file_path"]
+                    }
+                ),
+                Tool(
+                    name="read_parquet",
+                    description="Load Parquet file into DataFrame",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "file_path": {
+                                "type": "string",
+                                "description": "Path to Parquet file"
+                            },
+                            "name": {
+                                "type": "string",
+                                "description": "Optional name for data_ref"
+                            },
+                            "columns": {
+                                "type": "array",
+                                "items": {"type": "string"},
+                                "description": "Optional list of columns to load"
+                            }
+                        },
+                        "required": ["file_path"]
+                    }
+                ),
+                Tool(
+                    name="read_json",
+                    description="Load JSON/JSONL file into DataFrame",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "file_path": {
+                                "type": "string",
+                                "description": "Path to JSON file"
+                            },
+                            "name": {
+                                "type": "string",
+                                "description": "Optional name for data_ref"
+                            },
+                            "lines": {
+                                "type": "boolean",
+                                "default": False,
+                                "description": "Read as JSON Lines format"
+                            }
+                        },
+                        "required": ["file_path"]
+                    }
+                ),
+                Tool(
+                    name="to_csv",
+                    description="Export DataFrame to CSV file",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "data_ref": {
+                                "type": "string",
+                                "description": "Reference to stored DataFrame"
+                            },
+                            "file_path": {
+                                "type": "string",
+                                "description": "Output file path"
+                            },
+                            "index": {
+                                "type": "boolean",
+                                "default": False,
+                                "description": "Include index column"
+                            }
+                        },
+                        "required": ["data_ref", "file_path"]
+                    }
+                ),
+                Tool(
+                    name="to_parquet",
+                    description="Export DataFrame to Parquet file",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "data_ref": {
+                                "type": "string",
+                                "description": "Reference to stored DataFrame"
+                            },
+                            "file_path": {
+                                "type": "string",
+                                "description": "Output file path"
+                            },
+                            "compression": {
+                                "type": "string",
+                                "default": "snappy",
+                                "description": "Compression codec"
+                            }
+                        },
+                        "required": ["data_ref", "file_path"]
+                    }
+                ),
+                Tool(
+                    name="describe",
+                    description="Get statistical summary of DataFrame",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "data_ref": {
+                                "type": "string",
+                                "description": "Reference to stored DataFrame"
+                            }
+                        },
+                        "required": ["data_ref"]
+                    }
+                ),
+                Tool(
+                    name="head",
+                    description="Get first N rows of DataFrame",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "data_ref": {
+                                "type": "string",
+                                "description": "Reference to stored DataFrame"
+                            },
+                            "n": {
+                                "type": "integer",
+                                "default": 10,
+                                "description": "Number of rows"
+                            }
+                        },
+                        "required": ["data_ref"]
+                    }
+                ),
+                Tool(
+                    name="tail",
+                    description="Get last N rows of DataFrame",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "data_ref": {
+                                "type": "string",
+                                "description": "Reference to stored DataFrame"
+                            },
+                            "n": {
+                                "type": "integer",
+                                "default": 10,
+                                "description": "Number of rows"
+                            }
+                        },
+                        "required": ["data_ref"]
+                    }
+                ),
+                Tool(
+                    name="filter",
+                    description="Filter DataFrame rows by condition",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "data_ref": {
+                                "type": "string",
+                                "description": "Reference to stored DataFrame"
+                            },
+                            "condition": {
+                                "type": "string",
+                                "description": "pandas query string (e.g., 'age > 30 and city == \"NYC\"')"
+                            },
+                            "name": {
+                                "type": "string",
+                                "description": "Optional name for result data_ref"
+                            }
+                        },
+                        "required": ["data_ref", "condition"]
+                    }
+                ),
+                Tool(
+                    name="select",
+                    description="Select specific columns from DataFrame",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "data_ref": {
+                                "type": "string",
+                                "description": "Reference to stored DataFrame"
+                            },
+                            "columns": {
+                                "type": "array",
+                                "items": {"type": "string"},
+                                "description": "List of column names to select"
+                            },
+                            "name": {
+                                "type": "string",
+                                "description": "Optional name for result data_ref"
+                            }
+                        },
+                        "required": ["data_ref", "columns"]
+                    }
+                ),
+                Tool(
+                    name="groupby",
+                    description="Group DataFrame and aggregate",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "data_ref": {
+                                "type": "string",
+                                "description": "Reference to stored DataFrame"
+                            },
+                            "by": {
+                                "oneOf": [
+                                    {"type": "string"},
+                                    {"type": "array", "items": {"type": "string"}}
+                                ],
+                                "description": "Column(s) to group by"
+                            },
+                            "agg": {
+                                "type": "object",
+                                "description": "Aggregation dict (e.g., {\"sales\": \"sum\", \"count\": \"mean\"})"
+                            },
+                            "name": {
+                                "type": "string",
+                                "description": "Optional name for result data_ref"
+                            }
+                        },
+                        "required": ["data_ref", "by", "agg"]
+                    }
+                ),
+                Tool(
+                    name="join",
+                    description="Join two DataFrames",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "left_ref": {
+                                "type": "string",
+                                "description": "Reference to left DataFrame"
+                            },
+                            "right_ref": {
+                                "type": "string",
+                                "description": "Reference to right DataFrame"
+                            },
+                            "on": {
+                                "oneOf": [
+                                    {"type": "string"},
+                                    {"type": "array", "items": {"type": "string"}}
+                                ],
+                                "description": "Column(s) to join on (if same name in both)"
+                            },
+                            "left_on": {
+                                "oneOf": [
+                                    {"type": "string"},
+                                    {"type": "array", "items": {"type": "string"}}
+                                ],
+                                "description": "Left join column(s)"
+                            },
+                            "right_on": {
+                                "oneOf": [
+                                    {"type": "string"},
+                                    {"type": "array", "items": {"type": "string"}}
+                                ],
+                                "description": "Right join column(s)"
+                            },
+                            "how": {
+                                "type": "string",
+                                "enum": ["inner", "left", "right", "outer"],
+                                "default": "inner",
+                                "description": "Join type"
+                            },
+                            "name": {
+                                "type": "string",
+                                "description": "Optional name for result data_ref"
+                            }
+                        },
+                        "required": ["left_ref", "right_ref"]
+                    }
+                ),
+                Tool(
+                    name="list_data",
+                    description="List all stored DataFrames",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {}
+                    }
+                ),
+                Tool(
+                    name="drop_data",
+                    description="Remove a DataFrame from storage",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "data_ref": {
+                                "type": "string",
+                                "description": "Reference to drop"
+                            }
+                        },
+                        "required": ["data_ref"]
+                    }
+                ),
+                # PostgreSQL tools
+                Tool(
+                    name="pg_connect",
+                    description="Test PostgreSQL connection and return status",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {}
+                    }
+                ),
+                Tool(
+                    name="pg_query",
+                    description="Execute SELECT query and return results as data_ref",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "query": {
+                                "type": "string",
+                                "description": "SQL SELECT query"
+                            },
+                            "params": {
+                                "type": "array",
+                                "items": {},
+                                "description": "Query parameters (use $1, $2, etc.)"
+                            },
+                            "name": {
+                                "type": "string",
+                                "description": "Optional name for result data_ref"
+                            }
+                        },
+                        "required": ["query"]
+                    }
+                ),
+                Tool(
+                    name="pg_execute",
+                    description="Execute INSERT/UPDATE/DELETE query",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "query": {
+                                "type": "string",
+                                "description": "SQL DML query"
+                            },
+                            "params": {
+                                "type": "array",
+                                "items": {},
+                                "description": "Query parameters"
+                            }
+                        },
+                        "required": ["query"]
+                    }
+                ),
+                Tool(
+                    name="pg_tables",
+                    description="List all tables in schema",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "schema": {
+                                "type": "string",
+                                "default": "public",
+                                "description": "Schema name"
+                            }
+                        }
+                    }
+                ),
+                Tool(
+                    name="pg_columns",
+                    description="Get column information for a table",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "table": {
+                                "type": "string",
+                                "description": "Table name"
+                            },
+                            "schema": {
+                                "type": "string",
+                                "default": "public",
+                                "description": "Schema name"
+                            }
+                        },
+                        "required": ["table"]
+                    }
+                ),
+                Tool(
+                    name="pg_schemas",
+                    description="List all schemas in database",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {}
+                    }
+                ),
+                # PostGIS tools
+                Tool(
+                    name="st_tables",
+                    description="List PostGIS-enabled tables",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "schema": {
+                                "type": "string",
+                                "default": "public",
+                                "description": "Schema name"
+                            }
+                        }
+                    }
+                ),
+                Tool(
+                    name="st_geometry_type",
+                    description="Get geometry type of a column",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "table": {
+                                "type": "string",
+                                "description": "Table name"
+                            },
+                            "column": {
+                                "type": "string",
+                                "description": "Geometry column name"
+                            },
+                            "schema": {
+                                "type": "string",
+                                "default": "public",
+                                "description": "Schema name"
+                            }
+                        },
+                        "required": ["table", "column"]
+                    }
+                ),
+                Tool(
+                    name="st_srid",
+                    description="Get SRID of geometry column",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "table": {
+                                "type": "string",
+                                "description": "Table name"
+                            },
+                            "column": {
+                                "type": "string",
+                                "description": "Geometry column name"
+                            },
+                            "schema": {
+                                "type": "string",
+                                "default": "public",
+                                "description": "Schema name"
+                            }
+                        },
+                        "required": ["table", "column"]
+                    }
+                ),
+                Tool(
+                    name="st_extent",
+                    description="Get bounding box of all geometries",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "table": {
+                                "type": "string",
+                                "description": "Table name"
+                            },
+                            "column": {
+                                "type": "string",
+                                "description": "Geometry column name"
+                            },
+                            "schema": {
+                                "type": "string",
+                                "default": "public",
+                                "description": "Schema name"
+                            }
+                        },
+                        "required": ["table", "column"]
+                    }
+                ),
+                # dbt tools
+                Tool(
+                    name="dbt_parse",
+                    description="Validate dbt project (pre-flight check)",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {}
+                    }
+                ),
+                Tool(
+                    name="dbt_run",
+                    description="Run dbt models with pre-validation",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "select": {
+                                "type": "string",
+                                "description": "Model selection (e.g., 'model_name', '+model_name', 'tag:daily')"
+                            },
+                            "exclude": {
+                                "type": "string",
+                                "description": "Models to exclude"
+                            },
+                            "full_refresh": {
+                                "type": "boolean",
+                                "default": False,
+                                "description": "Rebuild incremental models"
+                            }
+                        }
+                    }
+                ),
+                Tool(
+                    name="dbt_test",
+                    description="Run dbt tests",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "select": {
+                                "type": "string",
+                                "description": "Test selection"
+                            },
+                            "exclude": {
+                                "type": "string",
+                                "description": "Tests to exclude"
+                            }
+                        }
+                    }
+                ),
+                Tool(
+                    name="dbt_build",
+                    description="Run dbt build (run + test) with pre-validation",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "select": {
+                                "type": "string",
+                                "description": "Model/test selection"
+                            },
+                            "exclude": {
+                                "type": "string",
+                                "description": "Resources to exclude"
+                            },
+                            "full_refresh": {
+                                "type": "boolean",
+                                "default": False,
+                                "description": "Rebuild incremental models"
+                            }
+                        }
+                    }
+                ),
+                Tool(
+                    name="dbt_compile",
+                    description="Compile dbt models to SQL without executing",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "select": {
+                                "type": "string",
+                                "description": "Model selection"
+                            }
+                        }
+                    }
+                ),
+                Tool(
+                    name="dbt_ls",
+                    description="List dbt resources",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "select": {
+                                "type": "string",
+                                "description": "Resource selection"
+                            },
+                            "resource_type": {
+                                "type": "string",
+                                "enum": ["model", "test", "seed", "snapshot", "source"],
+                                "description": "Filter by type"
+                            },
+                            "output": {
+                                "type": "string",
+                                "enum": ["name", "path", "json"],
+                                "default": "name",
+                                "description": "Output format"
+                            }
+                        }
+                    }
+                ),
+                Tool(
+                    name="dbt_docs_generate",
+                    description="Generate dbt documentation",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {}
+                    }
+                ),
+                Tool(
+                    name="dbt_lineage",
+                    description="Get model dependencies and lineage",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "model": {
+                                "type": "string",
+                                "description": "Model name to analyze"
+                            }
+                        },
+                        "required": ["model"]
+                    }
+                )
+            ]
+            return tools
+
+        @self.server.call_tool()
+        async def call_tool(name: str, arguments: dict) -> list[TextContent]:
+            """Handle tool invocation."""
+            try:
+                # Route to appropriate tool handler
+                # pandas tools
+                if name == "read_csv":
+                    result = await self.pandas_tools.read_csv(**arguments)
+                elif name == "read_parquet":
+                    result = await self.pandas_tools.read_parquet(**arguments)
+                elif name == "read_json":
+                    result = await self.pandas_tools.read_json(**arguments)
+                elif name == "to_csv":
+                    result = await self.pandas_tools.to_csv(**arguments)
+                elif name == "to_parquet":
+                    result = await self.pandas_tools.to_parquet(**arguments)
+                elif name == "describe":
+                    result = await self.pandas_tools.describe(**arguments)
+                elif name == "head":
+                    result = await self.pandas_tools.head(**arguments)
+                elif name == "tail":
+                    result = await self.pandas_tools.tail(**arguments)
+                elif name == "filter":
+                    result = await self.pandas_tools.filter(**arguments)
+                elif name == "select":
+                    result = await self.pandas_tools.select(**arguments)
+                elif name == "groupby":
+                    result = await self.pandas_tools.groupby(**arguments)
+                elif name == "join":
+                    result = await self.pandas_tools.join(**arguments)
+                elif name == "list_data":
+                    result = await self.pandas_tools.list_data()
+                elif name == "drop_data":
+                    result = await self.pandas_tools.drop_data(**arguments)
+                # PostgreSQL tools
+                elif name == "pg_connect":
+                    result = await self.postgres_tools.pg_connect()
+                elif name == "pg_query":
+                    result = await self.postgres_tools.pg_query(**arguments)
+                elif name == "pg_execute":
+                    result = await self.postgres_tools.pg_execute(**arguments)
+                elif name == "pg_tables":
+                    result = await self.postgres_tools.pg_tables(**arguments)
+                elif name == "pg_columns":
+                    result = await self.postgres_tools.pg_columns(**arguments)
+                elif name == "pg_schemas":
+                    result = await self.postgres_tools.pg_schemas()
+                # PostGIS tools
+                elif name == "st_tables":
+                    result = await self.postgres_tools.st_tables(**arguments)
+                elif name == "st_geometry_type":
+                    result = await self.postgres_tools.st_geometry_type(**arguments)
+                elif name == "st_srid":
+                    result = await self.postgres_tools.st_srid(**arguments)
+                elif name == "st_extent":
+                    result = await self.postgres_tools.st_extent(**arguments)
+                # dbt tools
+                elif name == "dbt_parse":
+                    result = await self.dbt_tools.dbt_parse()
+                elif name == "dbt_run":
+                    result = await self.dbt_tools.dbt_run(**arguments)
+                elif name == "dbt_test":
+                    result = await self.dbt_tools.dbt_test(**arguments)
+                elif name == "dbt_build":
+                    result = await self.dbt_tools.dbt_build(**arguments)
+                elif name == "dbt_compile":
+                    result = await self.dbt_tools.dbt_compile(**arguments)
+                elif name == "dbt_ls":
+                    result = await self.dbt_tools.dbt_ls(**arguments)
+                elif name == "dbt_docs_generate":
+                    result = await self.dbt_tools.dbt_docs_generate()
+                elif name == "dbt_lineage":
+                    result = await self.dbt_tools.dbt_lineage(**arguments)
+                else:
+                    raise ValueError(f"Unknown tool: {name}")
+
+                return [TextContent(
+                    type="text",
+                    text=json.dumps(result, indent=2, default=str)
+                )]
+
+            except Exception as e:
+                logger.error(f"Tool {name} failed: {e}")
+                return [TextContent(
+                    type="text",
+                    text=json.dumps({"error": str(e)}, indent=2)
+                )]
+
+    async def run(self):
+        """Run the MCP server"""
+        await self.initialize()
+        self.setup_tools()
+
+        async with stdio_server() as (read_stream, write_stream):
+            await self.server.run(
+                read_stream,
+                write_stream,
+                self.server.create_initialization_options()
+            )
+
+
+async def main():
+    """Main entry point"""
+    server = DataPlatformMCPServer()
+    await server.run()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

mcp-servers/data-platform/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "data-platform-mcp"
+version = "1.0.0"
+description = "MCP Server for data engineering with pandas, PostgreSQL/PostGIS, and dbt"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [
+    {name = "Leo Miranda"}
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "mcp>=0.9.0",
+    "pandas>=2.0.0",
+    "pyarrow>=14.0.0",
+    "asyncpg>=0.29.0",
+    "geoalchemy2>=0.14.0",
+    "shapely>=2.0.0",
+    "dbt-core>=1.9.0",
+    "dbt-postgres>=1.9.0",
+    "python-dotenv>=1.0.0",
+    "pydantic>=2.5.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.3",
+    "pytest-asyncio>=0.23.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["mcp_server*"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

mcp-servers/data-platform/requirements.txt

@@ -0,0 +1,23 @@
+# MCP SDK
+mcp>=0.9.0
+
+# Data Processing
+pandas>=2.0.0
+pyarrow>=14.0.0
+
+# PostgreSQL/PostGIS
+asyncpg>=0.29.0
+geoalchemy2>=0.14.0
+shapely>=2.0.0
+
+# dbt
+dbt-core>=1.9.0
+dbt-postgres>=1.9.0
+
+# Utilities
+python-dotenv>=1.0.0
+pydantic>=2.5.0
+
+# Testing
+pytest>=7.4.3
+pytest-asyncio>=0.23.0

mcp-servers/data-platform/run.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+# Capture original working directory before any cd operations
+# This should be the user's project directory when launched by Claude Code
+export CLAUDE_PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CACHE_VENV="$HOME/.cache/claude-mcp-venvs/leo-claude-mktplace/data-platform/.venv"
+LOCAL_VENV="$SCRIPT_DIR/.venv"
+
+if [[ -f "$CACHE_VENV/bin/python" ]]; then
+    PYTHON="$CACHE_VENV/bin/python"
+elif [[ -f "$LOCAL_VENV/bin/python" ]]; then
+    PYTHON="$LOCAL_VENV/bin/python"
+else
+    echo "ERROR: No venv found. Run: ./scripts/setup-venvs.sh" >&2
+    exit 1
+fi
+
+cd "$SCRIPT_DIR"
+export PYTHONPATH="$SCRIPT_DIR"
+exec "$PYTHON" -m mcp_server.server "$@"

mcp-servers/data-platform/tests/__init__.py

@@ -0,0 +1,3 @@
+"""
+Tests for Data Platform MCP Server.
+"""

mcp-servers/data-platform/tests/test_config.py

@@ -0,0 +1,239 @@
+"""
+Unit tests for configuration loader.
+"""
+import pytest
+from pathlib import Path
+import os
+
+
+def test_load_system_config(tmp_path, monkeypatch):
+    """Test loading system-level PostgreSQL configuration"""
+    # Import here to avoid import errors before setup
+    from mcp_server.config import DataPlatformConfig
+
+    # Mock home directory
+    config_dir = tmp_path / '.config' / 'claude'
+    config_dir.mkdir(parents=True)
+
+    config_file = config_dir / 'postgres.env'
+    config_file.write_text(
+        "POSTGRES_URL=postgresql://user:pass@localhost:5432/testdb\n"
+    )
+
+    monkeypatch.setenv('HOME', str(tmp_path))
+    monkeypatch.chdir(tmp_path)
+
+    config = DataPlatformConfig()
+    result = config.load()
+
+    assert result['postgres_url'] == 'postgresql://user:pass@localhost:5432/testdb'
+    assert result['postgres_available'] is True
+
+
+def test_postgres_optional(tmp_path, monkeypatch):
+    """Test that PostgreSQL configuration is optional"""
+    from mcp_server.config import DataPlatformConfig
+
+    # No postgres.env file
+    monkeypatch.setenv('HOME', str(tmp_path))
+    monkeypatch.chdir(tmp_path)
+
+    # Clear any existing env vars
+    monkeypatch.delenv('POSTGRES_URL', raising=False)
+
+    config = DataPlatformConfig()
+    result = config.load()
+
+    assert result['postgres_url'] is None
+    assert result['postgres_available'] is False
+
+
+def test_project_config_override(tmp_path, monkeypatch):
+    """Test that project config overrides system config"""
+    from mcp_server.config import DataPlatformConfig
+
+    # Set up system config
+    system_config_dir = tmp_path / '.config' / 'claude'
+    system_config_dir.mkdir(parents=True)
+
+    system_config = system_config_dir / 'postgres.env'
+    system_config.write_text(
+        "POSTGRES_URL=postgresql://system:pass@localhost:5432/systemdb\n"
+    )
+
+    # Set up project config
+    project_dir = tmp_path / 'project'
+    project_dir.mkdir()
+
+    project_config = project_dir / '.env'
+    project_config.write_text(
+        "POSTGRES_URL=postgresql://project:pass@localhost:5432/projectdb\n"
+        "DBT_PROJECT_DIR=/path/to/dbt\n"
+    )
+
+    monkeypatch.setenv('HOME', str(tmp_path))
+    monkeypatch.chdir(project_dir)
+
+    config = DataPlatformConfig()
+    result = config.load()
+
+    # Project config should override
+    assert result['postgres_url'] == 'postgresql://project:pass@localhost:5432/projectdb'
+    assert result['dbt_project_dir'] == '/path/to/dbt'
+
+
+def test_max_rows_config(tmp_path, monkeypatch):
+    """Test max rows configuration"""
+    from mcp_server.config import DataPlatformConfig
+
+    project_dir = tmp_path / 'project'
+    project_dir.mkdir()
+
+    project_config = project_dir / '.env'
+    project_config.write_text("DATA_PLATFORM_MAX_ROWS=50000\n")
+
+    monkeypatch.setenv('HOME', str(tmp_path))
+    monkeypatch.chdir(project_dir)
+
+    config = DataPlatformConfig()
+    result = config.load()
+
+    assert result['max_rows'] == 50000
+
+
+def test_default_max_rows(tmp_path, monkeypatch):
+    """Test default max rows value"""
+    from mcp_server.config import DataPlatformConfig
+
+    monkeypatch.setenv('HOME', str(tmp_path))
+    monkeypatch.chdir(tmp_path)
+
+    # Clear any existing env vars
+    monkeypatch.delenv('DATA_PLATFORM_MAX_ROWS', raising=False)
+
+    config = DataPlatformConfig()
+    result = config.load()
+
+    assert result['max_rows'] == 100_000  # Default value
+
+
+def test_dbt_auto_detection(tmp_path, monkeypatch):
+    """Test automatic dbt project detection"""
+    from mcp_server.config import DataPlatformConfig
+
+    # Create project with dbt_project.yml
+    project_dir = tmp_path / 'project'
+    project_dir.mkdir()
+    (project_dir / 'dbt_project.yml').write_text("name: test_project\n")
+
+    monkeypatch.setenv('HOME', str(tmp_path))
+    monkeypatch.chdir(project_dir)
+    # Clear PWD and DBT_PROJECT_DIR to ensure auto-detection
+    monkeypatch.delenv('PWD', raising=False)
+    monkeypatch.delenv('DBT_PROJECT_DIR', raising=False)
+    monkeypatch.delenv('CLAUDE_PROJECT_DIR', raising=False)
+
+    config = DataPlatformConfig()
+    result = config.load()
+
+    assert result['dbt_project_dir'] == str(project_dir)
+    assert result['dbt_available'] is True
+
+
+def test_dbt_subdirectory_detection(tmp_path, monkeypatch):
+    """Test dbt project detection in subdirectory"""
+    from mcp_server.config import DataPlatformConfig
+
+    # Create project with dbt in subdirectory
+    project_dir = tmp_path / 'project'
+    project_dir.mkdir()
+    # Need a marker file for _find_project_directory to find the project
+    (project_dir / '.git').mkdir()
+    dbt_dir = project_dir / 'transform'
+    dbt_dir.mkdir()
+    (dbt_dir / 'dbt_project.yml').write_text("name: test_project\n")
+
+    monkeypatch.setenv('HOME', str(tmp_path))
+    monkeypatch.chdir(project_dir)
+    # Clear env vars to ensure auto-detection
+    monkeypatch.delenv('PWD', raising=False)
+    monkeypatch.delenv('DBT_PROJECT_DIR', raising=False)
+    monkeypatch.delenv('CLAUDE_PROJECT_DIR', raising=False)
+
+    config = DataPlatformConfig()
+    result = config.load()
+
+    assert result['dbt_project_dir'] == str(dbt_dir)
+    assert result['dbt_available'] is True
+
+
+def test_no_dbt_project(tmp_path, monkeypatch):
+    """Test when no dbt project exists"""
+    from mcp_server.config import DataPlatformConfig
+
+    project_dir = tmp_path / 'project'
+    project_dir.mkdir()
+
+    monkeypatch.setenv('HOME', str(tmp_path))
+    monkeypatch.chdir(project_dir)
+
+    # Clear any existing env vars
+    monkeypatch.delenv('DBT_PROJECT_DIR', raising=False)
+
+    config = DataPlatformConfig()
+    result = config.load()
+
+    assert result['dbt_project_dir'] is None
+    assert result['dbt_available'] is False
+
+
+def test_find_project_directory_from_env(tmp_path, monkeypatch):
+    """Test finding project directory from CLAUDE_PROJECT_DIR env var"""
+    from mcp_server.config import DataPlatformConfig
+
+    project_dir = tmp_path / 'my-project'
+    project_dir.mkdir()
+    (project_dir / '.git').mkdir()
+
+    monkeypatch.setenv('CLAUDE_PROJECT_DIR', str(project_dir))
+
+    config = DataPlatformConfig()
+    result = config._find_project_directory()
+
+    assert result == project_dir
+
+
+def test_find_project_directory_from_cwd(tmp_path, monkeypatch):
+    """Test finding project directory from cwd with .env file"""
+    from mcp_server.config import DataPlatformConfig
+
+    project_dir = tmp_path / 'project'
+    project_dir.mkdir()
+    (project_dir / '.env').write_text("TEST=value")
+
+    monkeypatch.chdir(project_dir)
+    monkeypatch.delenv('CLAUDE_PROJECT_DIR', raising=False)
+    monkeypatch.delenv('PWD', raising=False)
+
+    config = DataPlatformConfig()
+    result = config._find_project_directory()
+
+    assert result == project_dir
+
+
+def test_find_project_directory_none_when_no_markers(tmp_path, monkeypatch):
+    """Test returns None when no project markers found"""
+    from mcp_server.config import DataPlatformConfig
+
+    empty_dir = tmp_path / 'empty'
+    empty_dir.mkdir()
+
+    monkeypatch.chdir(empty_dir)
+    monkeypatch.delenv('CLAUDE_PROJECT_DIR', raising=False)
+    monkeypatch.delenv('PWD', raising=False)
+    monkeypatch.delenv('DBT_PROJECT_DIR', raising=False)
+
+    config = DataPlatformConfig()
+    result = config._find_project_directory()
+
+    assert result is None

mcp-servers/data-platform/tests/test_data_store.py

@@ -0,0 +1,240 @@
+"""
+Unit tests for Arrow IPC DataFrame registry.
+"""
+import pytest
+import pandas as pd
+import pyarrow as pa
+
+
+def test_store_pandas_dataframe():
+    """Test storing pandas DataFrame"""
+    from mcp_server.data_store import DataStore
+
+    # Create fresh instance for test
+    store = DataStore()
+    store._dataframes = {}
+    store._metadata = {}
+
+    df = pd.DataFrame({'a': [1, 2, 3], 'b': ['x', 'y', 'z']})
+    data_ref = store.store(df, name='test_df')
+
+    assert data_ref == 'test_df'
+    assert 'test_df' in store._dataframes
+    assert store._metadata['test_df'].rows == 3
+    assert store._metadata['test_df'].columns == 2
+
+
+def test_store_arrow_table():
+    """Test storing Arrow Table directly"""
+    from mcp_server.data_store import DataStore
+
+    store = DataStore()
+    store._dataframes = {}
+    store._metadata = {}
+
+    table = pa.table({'x': [1, 2, 3], 'y': [4, 5, 6]})
+    data_ref = store.store(table, name='arrow_test')
+
+    assert data_ref == 'arrow_test'
+    assert store._dataframes['arrow_test'].num_rows == 3
+
+
+def test_store_auto_name():
+    """Test auto-generated data_ref names"""
+    from mcp_server.data_store import DataStore
+
+    store = DataStore()
+    store._dataframes = {}
+    store._metadata = {}
+
+    df = pd.DataFrame({'a': [1, 2]})
+    data_ref = store.store(df)
+
+    assert data_ref.startswith('df_')
+    assert len(data_ref) == 11  # df_ + 8 hex chars
+
+
+def test_get_dataframe():
+    """Test retrieving stored DataFrame"""
+    from mcp_server.data_store import DataStore
+
+    store = DataStore()
+    store._dataframes = {}
+    store._metadata = {}
+
+    df = pd.DataFrame({'a': [1, 2, 3]})
+    store.store(df, name='get_test')
+
+    result = store.get('get_test')
+    assert result is not None
+    assert result.num_rows == 3
+
+
+def test_get_pandas():
+    """Test retrieving as pandas DataFrame"""
+    from mcp_server.data_store import DataStore
+
+    store = DataStore()
+    store._dataframes = {}
+    store._metadata = {}
+
+    df = pd.DataFrame({'a': [1, 2, 3], 'b': ['x', 'y', 'z']})
+    store.store(df, name='pandas_test')
+
+    result = store.get_pandas('pandas_test')
+    assert isinstance(result, pd.DataFrame)
+    assert list(result.columns) == ['a', 'b']
+    assert len(result) == 3
+
+
+def test_get_nonexistent():
+    """Test getting nonexistent data_ref returns None"""
+    from mcp_server.data_store import DataStore
+
+    store = DataStore()
+    store._dataframes = {}
+    store._metadata = {}
+
+    assert store.get('nonexistent') is None
+    assert store.get_pandas('nonexistent') is None
+
+
+def test_list_refs():
+    """Test listing all stored DataFrames"""
+    from mcp_server.data_store import DataStore
+
+    store = DataStore()
+    store._dataframes = {}
+    store._metadata = {}
+
+    store.store(pd.DataFrame({'a': [1, 2]}), name='df1')
+    store.store(pd.DataFrame({'b': [3, 4, 5]}), name='df2')
+
+    refs = store.list_refs()
+
+    assert len(refs) == 2
+    ref_names = [r['ref'] for r in refs]
+    assert 'df1' in ref_names
+    assert 'df2' in ref_names
+
+
+def test_drop_dataframe():
+    """Test dropping a DataFrame"""
+    from mcp_server.data_store import DataStore
+
+    store = DataStore()
+    store._dataframes = {}
+    store._metadata = {}
+
+    store.store(pd.DataFrame({'a': [1]}), name='drop_test')
+    assert store.get('drop_test') is not None
+
+    result = store.drop('drop_test')
+    assert result is True
+    assert store.get('drop_test') is None
+
+
+def test_drop_nonexistent():
+    """Test dropping nonexistent data_ref"""
+    from mcp_server.data_store import DataStore
+
+    store = DataStore()
+    store._dataframes = {}
+    store._metadata = {}
+
+    result = store.drop('nonexistent')
+    assert result is False
+
+
+def test_clear():
+    """Test clearing all DataFrames"""
+    from mcp_server.data_store import DataStore
+
+    store = DataStore()
+    store._dataframes = {}
+    store._metadata = {}
+
+    store.store(pd.DataFrame({'a': [1]}), name='df1')
+    store.store(pd.DataFrame({'b': [2]}), name='df2')
+
+    store.clear()
+
+    assert len(store.list_refs()) == 0
+
+
+def test_get_info():
+    """Test getting DataFrame metadata"""
+    from mcp_server.data_store import DataStore
+
+    store = DataStore()
+    store._dataframes = {}
+    store._metadata = {}
+
+    df = pd.DataFrame({'a': [1, 2, 3], 'b': ['x', 'y', 'z']})
+    store.store(df, name='info_test', source='test source')
+
+    info = store.get_info('info_test')
+
+    assert info.ref == 'info_test'
+    assert info.rows == 3
+    assert info.columns == 2
+    assert info.column_names == ['a', 'b']
+    assert info.source == 'test source'
+    assert info.memory_bytes > 0
+
+
+def test_total_memory():
+    """Test total memory calculation"""
+    from mcp_server.data_store import DataStore
+
+    store = DataStore()
+    store._dataframes = {}
+    store._metadata = {}
+
+    store.store(pd.DataFrame({'a': range(100)}), name='df1')
+    store.store(pd.DataFrame({'b': range(200)}), name='df2')
+
+    total = store.total_memory_bytes()
+    assert total > 0
+
+    total_mb = store.total_memory_mb()
+    assert total_mb >= 0
+
+
+def test_check_row_limit():
+    """Test row limit checking"""
+    from mcp_server.data_store import DataStore
+
+    store = DataStore()
+    store._max_rows = 100
+
+    # Under limit
+    result = store.check_row_limit(50)
+    assert result['exceeded'] is False
+
+    # Over limit
+    result = store.check_row_limit(150)
+    assert result['exceeded'] is True
+    assert 'suggestion' in result
+
+
+def test_metadata_dtypes():
+    """Test that dtypes are correctly recorded"""
+    from mcp_server.data_store import DataStore
+
+    store = DataStore()
+    store._dataframes = {}
+    store._metadata = {}
+
+    df = pd.DataFrame({
+        'int_col': [1, 2, 3],
+        'float_col': [1.1, 2.2, 3.3],
+        'str_col': ['a', 'b', 'c']
+    })
+    store.store(df, name='dtype_test')
+
+    info = store.get_info('dtype_test')
+
+    assert 'int_col' in info.dtypes
+    assert 'float_col' in info.dtypes
+    assert 'str_col' in info.dtypes

mcp-servers/data-platform/tests/test_dbt_tools.py

@@ -0,0 +1,318 @@
+"""
+Unit tests for dbt MCP tools.
+"""
+import pytest
+from unittest.mock import Mock, patch, MagicMock
+import subprocess
+import json
+import tempfile
+import os
+
+
+@pytest.fixture
+def mock_config(tmp_path):
+    """Mock configuration with dbt project"""
+    dbt_dir = tmp_path / 'dbt_project'
+    dbt_dir.mkdir()
+    (dbt_dir / 'dbt_project.yml').write_text('name: test_project\n')
+
+    return {
+        'dbt_project_dir': str(dbt_dir),
+        'dbt_profiles_dir': str(tmp_path / '.dbt')
+    }
+
+
+@pytest.fixture
+def dbt_tools(mock_config):
+    """Create DbtTools instance with mocked config"""
+    with patch('mcp_server.dbt_tools.load_config', return_value=mock_config):
+        from mcp_server.dbt_tools import DbtTools
+
+        tools = DbtTools()
+        tools.project_dir = mock_config['dbt_project_dir']
+        tools.profiles_dir = mock_config['dbt_profiles_dir']
+        return tools
+
+
+@pytest.mark.asyncio
+async def test_dbt_parse_success(dbt_tools):
+    """Test successful dbt parse"""
+    mock_result = MagicMock()
+    mock_result.returncode = 0
+    mock_result.stdout = 'Parsed successfully'
+    mock_result.stderr = ''
+
+    with patch('subprocess.run', return_value=mock_result):
+        result = await dbt_tools.dbt_parse()
+
+    assert result['valid'] is True
+
+
+@pytest.mark.asyncio
+async def test_dbt_parse_failure(dbt_tools):
+    """Test dbt parse with errors"""
+    mock_result = MagicMock()
+    mock_result.returncode = 1
+    mock_result.stdout = ''
+    mock_result.stderr = 'Compilation error: deprecated syntax'
+
+    with patch('subprocess.run', return_value=mock_result):
+        result = await dbt_tools.dbt_parse()
+
+    assert result['valid'] is False
+    assert 'deprecated' in str(result.get('details', '')).lower() or len(result.get('errors', [])) > 0
+
+
+@pytest.mark.asyncio
+async def test_dbt_run_with_prevalidation(dbt_tools):
+    """Test dbt run includes pre-validation"""
+    # First call is parse, second is run
+    mock_parse = MagicMock()
+    mock_parse.returncode = 0
+    mock_parse.stdout = 'OK'
+    mock_parse.stderr = ''
+
+    mock_run = MagicMock()
+    mock_run.returncode = 0
+    mock_run.stdout = 'Completed successfully'
+    mock_run.stderr = ''
+
+    with patch('subprocess.run', side_effect=[mock_parse, mock_run]):
+        result = await dbt_tools.dbt_run()
+
+    assert result['success'] is True
+
+
+@pytest.mark.asyncio
+async def test_dbt_run_fails_validation(dbt_tools):
+    """Test dbt run fails if validation fails"""
+    mock_parse = MagicMock()
+    mock_parse.returncode = 1
+    mock_parse.stdout = ''
+    mock_parse.stderr = 'Parse error'
+
+    with patch('subprocess.run', return_value=mock_parse):
+        result = await dbt_tools.dbt_run()
+
+    assert 'error' in result
+    assert 'Pre-validation failed' in result['error']
+
+
+@pytest.mark.asyncio
+async def test_dbt_run_with_selection(dbt_tools):
+    """Test dbt run with model selection"""
+    mock_parse = MagicMock()
+    mock_parse.returncode = 0
+    mock_parse.stdout = 'OK'
+    mock_parse.stderr = ''
+
+    mock_run = MagicMock()
+    mock_run.returncode = 0
+    mock_run.stdout = 'Completed'
+    mock_run.stderr = ''
+
+    calls = []
+
+    def track_calls(*args, **kwargs):
+        calls.append(args[0] if args else kwargs.get('args', []))
+        if len(calls) == 1:
+            return mock_parse
+        return mock_run
+
+    with patch('subprocess.run', side_effect=track_calls):
+        result = await dbt_tools.dbt_run(select='dim_customers')
+
+    # Verify --select was passed
+    assert any('--select' in str(call) for call in calls)
+
+
+@pytest.mark.asyncio
+async def test_dbt_test(dbt_tools):
+    """Test dbt test"""
+    mock_result = MagicMock()
+    mock_result.returncode = 0
+    mock_result.stdout = 'All tests passed'
+    mock_result.stderr = ''
+
+    with patch('subprocess.run', return_value=mock_result):
+        result = await dbt_tools.dbt_test()
+
+    assert result['success'] is True
+
+
+@pytest.mark.asyncio
+async def test_dbt_build(dbt_tools):
+    """Test dbt build with pre-validation"""
+    mock_parse = MagicMock()
+    mock_parse.returncode = 0
+    mock_parse.stdout = 'OK'
+    mock_parse.stderr = ''
+
+    mock_build = MagicMock()
+    mock_build.returncode = 0
+    mock_build.stdout = 'Build complete'
+    mock_build.stderr = ''
+
+    with patch('subprocess.run', side_effect=[mock_parse, mock_build]):
+        result = await dbt_tools.dbt_build()
+
+    assert result['success'] is True
+
+
+@pytest.mark.asyncio
+async def test_dbt_compile(dbt_tools):
+    """Test dbt compile"""
+    mock_result = MagicMock()
+    mock_result.returncode = 0
+    mock_result.stdout = 'Compiled'
+    mock_result.stderr = ''
+
+    with patch('subprocess.run', return_value=mock_result):
+        result = await dbt_tools.dbt_compile()
+
+    assert result['success'] is True
+
+
+@pytest.mark.asyncio
+async def test_dbt_ls(dbt_tools):
+    """Test dbt ls"""
+    mock_result = MagicMock()
+    mock_result.returncode = 0
+    mock_result.stdout = 'dim_customers\ndim_products\nfct_orders\n'
+    mock_result.stderr = ''
+
+    with patch('subprocess.run', return_value=mock_result):
+        result = await dbt_tools.dbt_ls()
+
+    assert result['success'] is True
+    assert result['count'] == 3
+    assert 'dim_customers' in result['resources']
+
+
+@pytest.mark.asyncio
+async def test_dbt_docs_generate(dbt_tools, tmp_path):
+    """Test dbt docs generate"""
+    mock_result = MagicMock()
+    mock_result.returncode = 0
+    mock_result.stdout = 'Done'
+    mock_result.stderr = ''
+
+    # Create fake target directory
+    target_dir = tmp_path / 'dbt_project' / 'target'
+    target_dir.mkdir(parents=True)
+    (target_dir / 'catalog.json').write_text('{}')
+    (target_dir / 'manifest.json').write_text('{}')
+
+    dbt_tools.project_dir = str(tmp_path / 'dbt_project')
+
+    with patch('subprocess.run', return_value=mock_result):
+        result = await dbt_tools.dbt_docs_generate()
+
+    assert result['success'] is True
+    assert result['catalog_generated'] is True
+    assert result['manifest_generated'] is True
+
+
+@pytest.mark.asyncio
+async def test_dbt_lineage(dbt_tools, tmp_path):
+    """Test dbt lineage"""
+    # Create manifest
+    target_dir = tmp_path / 'dbt_project' / 'target'
+    target_dir.mkdir(parents=True)
+
+    manifest = {
+        'nodes': {
+            'model.test.dim_customers': {
+                'name': 'dim_customers',
+                'resource_type': 'model',
+                'schema': 'public',
+                'database': 'testdb',
+                'description': 'Customer dimension',
+                'tags': ['daily'],
+                'config': {'materialized': 'table'},
+                'depends_on': {
+                    'nodes': ['model.test.stg_customers']
+                }
+            },
+            'model.test.stg_customers': {
+                'name': 'stg_customers',
+                'resource_type': 'model',
+                'depends_on': {'nodes': []}
+            },
+            'model.test.fct_orders': {
+                'name': 'fct_orders',
+                'resource_type': 'model',
+                'depends_on': {
+                    'nodes': ['model.test.dim_customers']
+                }
+            }
+        }
+    }
+    (target_dir / 'manifest.json').write_text(json.dumps(manifest))
+
+    dbt_tools.project_dir = str(tmp_path / 'dbt_project')
+
+    result = await dbt_tools.dbt_lineage('dim_customers')
+
+    assert result['model'] == 'dim_customers'
+    assert 'model.test.stg_customers' in result['upstream']
+    assert 'model.test.fct_orders' in result['downstream']
+
+
+@pytest.mark.asyncio
+async def test_dbt_lineage_model_not_found(dbt_tools, tmp_path):
+    """Test dbt lineage with nonexistent model"""
+    target_dir = tmp_path / 'dbt_project' / 'target'
+    target_dir.mkdir(parents=True)
+
+    manifest = {
+        'nodes': {
+            'model.test.dim_customers': {
+                'name': 'dim_customers',
+                'resource_type': 'model'
+            }
+        }
+    }
+    (target_dir / 'manifest.json').write_text(json.dumps(manifest))
+
+    dbt_tools.project_dir = str(tmp_path / 'dbt_project')
+
+    result = await dbt_tools.dbt_lineage('nonexistent_model')
+
+    assert 'error' in result
+    assert 'not found' in result['error'].lower()
+
+
+@pytest.mark.asyncio
+async def test_dbt_no_project():
+    """Test dbt tools when no project configured"""
+    with patch('mcp_server.dbt_tools.load_config', return_value={'dbt_project_dir': None}):
+        from mcp_server.dbt_tools import DbtTools
+
+        tools = DbtTools()
+        tools.project_dir = None
+
+        result = await tools.dbt_run()
+
+    assert 'error' in result
+    assert 'not found' in result['error'].lower()
+
+
+@pytest.mark.asyncio
+async def test_dbt_timeout(dbt_tools):
+    """Test dbt command timeout handling"""
+    with patch('subprocess.run', side_effect=subprocess.TimeoutExpired('dbt', 300)):
+        result = await dbt_tools.dbt_parse()
+
+    assert 'error' in result
+    assert 'timed out' in result['error'].lower()
+
+
+@pytest.mark.asyncio
+async def test_dbt_not_installed(dbt_tools):
+    """Test handling when dbt is not installed"""
+    with patch('subprocess.run', side_effect=FileNotFoundError()):
+        result = await dbt_tools.dbt_parse()
+
+    assert 'error' in result
+    assert 'not found' in result['error'].lower()

mcp-servers/data-platform/tests/test_pandas_tools.py

@@ -0,0 +1,301 @@
+"""
+Unit tests for pandas MCP tools.
+"""
+import pytest
+import pandas as pd
+import tempfile
+import os
+from pathlib import Path
+
+
+@pytest.fixture
+def temp_csv(tmp_path):
+    """Create a temporary CSV file for testing"""
+    csv_path = tmp_path / 'test.csv'
+    df = pd.DataFrame({
+        'id': [1, 2, 3, 4, 5],
+        'name': ['Alice', 'Bob', 'Charlie', 'Diana', 'Eve'],
+        'value': [10.5, 20.0, 30.5, 40.0, 50.5]
+    })
+    df.to_csv(csv_path, index=False)
+    return str(csv_path)
+
+
+@pytest.fixture
+def temp_parquet(tmp_path):
+    """Create a temporary Parquet file for testing"""
+    parquet_path = tmp_path / 'test.parquet'
+    df = pd.DataFrame({
+        'id': [1, 2, 3],
+        'data': ['a', 'b', 'c']
+    })
+    df.to_parquet(parquet_path)
+    return str(parquet_path)
+
+
+@pytest.fixture
+def temp_json(tmp_path):
+    """Create a temporary JSON file for testing"""
+    json_path = tmp_path / 'test.json'
+    df = pd.DataFrame({
+        'x': [1, 2],
+        'y': [3, 4]
+    })
+    df.to_json(json_path, orient='records')
+    return str(json_path)
+
+
+@pytest.fixture
+def pandas_tools():
+    """Create PandasTools instance with fresh store"""
+    from mcp_server.pandas_tools import PandasTools
+    from mcp_server.data_store import DataStore
+
+    # Reset store for test isolation
+    store = DataStore.get_instance()
+    store._dataframes = {}
+    store._metadata = {}
+
+    return PandasTools()
+
+
+@pytest.mark.asyncio
+async def test_read_csv(pandas_tools, temp_csv):
+    """Test reading CSV file"""
+    result = await pandas_tools.read_csv(temp_csv, name='csv_test')
+
+    assert 'data_ref' in result
+    assert result['data_ref'] == 'csv_test'
+    assert result['rows'] == 5
+    assert 'id' in result['columns']
+    assert 'name' in result['columns']
+
+
+@pytest.mark.asyncio
+async def test_read_csv_nonexistent(pandas_tools):
+    """Test reading nonexistent CSV file"""
+    result = await pandas_tools.read_csv('/nonexistent/path.csv')
+
+    assert 'error' in result
+    assert 'not found' in result['error'].lower()
+
+
+@pytest.mark.asyncio
+async def test_read_parquet(pandas_tools, temp_parquet):
+    """Test reading Parquet file"""
+    result = await pandas_tools.read_parquet(temp_parquet, name='parquet_test')
+
+    assert 'data_ref' in result
+    assert result['rows'] == 3
+
+
+@pytest.mark.asyncio
+async def test_read_json(pandas_tools, temp_json):
+    """Test reading JSON file"""
+    result = await pandas_tools.read_json(temp_json, name='json_test')
+
+    assert 'data_ref' in result
+    assert result['rows'] == 2
+
+
+@pytest.mark.asyncio
+async def test_to_csv(pandas_tools, temp_csv, tmp_path):
+    """Test exporting to CSV"""
+    # First load some data
+    await pandas_tools.read_csv(temp_csv, name='export_test')
+
+    # Export to new file
+    output_path = str(tmp_path / 'output.csv')
+    result = await pandas_tools.to_csv('export_test', output_path)
+
+    assert result['success'] is True
+    assert os.path.exists(output_path)
+
+
+@pytest.mark.asyncio
+async def test_to_parquet(pandas_tools, temp_csv, tmp_path):
+    """Test exporting to Parquet"""
+    await pandas_tools.read_csv(temp_csv, name='parquet_export')
+
+    output_path = str(tmp_path / 'output.parquet')
+    result = await pandas_tools.to_parquet('parquet_export', output_path)
+
+    assert result['success'] is True
+    assert os.path.exists(output_path)
+
+
+@pytest.mark.asyncio
+async def test_describe(pandas_tools, temp_csv):
+    """Test describe statistics"""
+    await pandas_tools.read_csv(temp_csv, name='describe_test')
+
+    result = await pandas_tools.describe('describe_test')
+
+    assert 'data_ref' in result
+    assert 'shape' in result
+    assert result['shape']['rows'] == 5
+    assert 'statistics' in result
+    assert 'null_counts' in result
+
+
+@pytest.mark.asyncio
+async def test_head(pandas_tools, temp_csv):
+    """Test getting first N rows"""
+    await pandas_tools.read_csv(temp_csv, name='head_test')
+
+    result = await pandas_tools.head('head_test', n=3)
+
+    assert result['returned_rows'] == 3
+    assert len(result['data']) == 3
+
+
+@pytest.mark.asyncio
+async def test_tail(pandas_tools, temp_csv):
+    """Test getting last N rows"""
+    await pandas_tools.read_csv(temp_csv, name='tail_test')
+
+    result = await pandas_tools.tail('tail_test', n=2)
+
+    assert result['returned_rows'] == 2
+
+
+@pytest.mark.asyncio
+async def test_filter(pandas_tools, temp_csv):
+    """Test filtering rows"""
+    await pandas_tools.read_csv(temp_csv, name='filter_test')
+
+    result = await pandas_tools.filter('filter_test', 'value > 25')
+
+    assert 'data_ref' in result
+    assert result['rows'] == 3  # 30.5, 40.0, 50.5
+
+
+@pytest.mark.asyncio
+async def test_filter_invalid_condition(pandas_tools, temp_csv):
+    """Test filter with invalid condition"""
+    await pandas_tools.read_csv(temp_csv, name='filter_error')
+
+    result = await pandas_tools.filter('filter_error', 'invalid_column > 0')
+
+    assert 'error' in result
+
+
+@pytest.mark.asyncio
+async def test_select(pandas_tools, temp_csv):
+    """Test selecting columns"""
+    await pandas_tools.read_csv(temp_csv, name='select_test')
+
+    result = await pandas_tools.select('select_test', ['id', 'name'])
+
+    assert 'data_ref' in result
+    assert result['columns'] == ['id', 'name']
+
+
+@pytest.mark.asyncio
+async def test_select_invalid_column(pandas_tools, temp_csv):
+    """Test select with invalid column"""
+    await pandas_tools.read_csv(temp_csv, name='select_error')
+
+    result = await pandas_tools.select('select_error', ['id', 'nonexistent'])
+
+    assert 'error' in result
+    assert 'available_columns' in result
+
+
+@pytest.mark.asyncio
+async def test_groupby(pandas_tools, tmp_path):
+    """Test groupby aggregation"""
+    # Create test data with groups
+    csv_path = tmp_path / 'groupby.csv'
+    df = pd.DataFrame({
+        'category': ['A', 'A', 'B', 'B'],
+        'value': [10, 20, 30, 40]
+    })
+    df.to_csv(csv_path, index=False)
+
+    await pandas_tools.read_csv(str(csv_path), name='groupby_test')
+
+    result = await pandas_tools.groupby(
+        'groupby_test',
+        by='category',
+        agg={'value': 'sum'}
+    )
+
+    assert 'data_ref' in result
+    assert result['rows'] == 2  # Two groups: A, B
+
+
+@pytest.mark.asyncio
+async def test_join(pandas_tools, tmp_path):
+    """Test joining DataFrames"""
+    # Create left table
+    left_path = tmp_path / 'left.csv'
+    pd.DataFrame({
+        'id': [1, 2, 3],
+        'name': ['A', 'B', 'C']
+    }).to_csv(left_path, index=False)
+
+    # Create right table
+    right_path = tmp_path / 'right.csv'
+    pd.DataFrame({
+        'id': [1, 2, 4],
+        'value': [100, 200, 400]
+    }).to_csv(right_path, index=False)
+
+    await pandas_tools.read_csv(str(left_path), name='left')
+    await pandas_tools.read_csv(str(right_path), name='right')
+
+    result = await pandas_tools.join('left', 'right', on='id', how='inner')
+
+    assert 'data_ref' in result
+    assert result['rows'] == 2  # Only id 1 and 2 match
+
+
+@pytest.mark.asyncio
+async def test_list_data(pandas_tools, temp_csv):
+    """Test listing all DataFrames"""
+    await pandas_tools.read_csv(temp_csv, name='list_test1')
+    await pandas_tools.read_csv(temp_csv, name='list_test2')
+
+    result = await pandas_tools.list_data()
+
+    assert result['count'] == 2
+    refs = [df['ref'] for df in result['dataframes']]
+    assert 'list_test1' in refs
+    assert 'list_test2' in refs
+
+
+@pytest.mark.asyncio
+async def test_drop_data(pandas_tools, temp_csv):
+    """Test dropping DataFrame"""
+    await pandas_tools.read_csv(temp_csv, name='drop_test')
+
+    result = await pandas_tools.drop_data('drop_test')
+
+    assert result['success'] is True
+
+    # Verify it's gone
+    list_result = await pandas_tools.list_data()
+    refs = [df['ref'] for df in list_result['dataframes']]
+    assert 'drop_test' not in refs
+
+
+@pytest.mark.asyncio
+async def test_drop_nonexistent(pandas_tools):
+    """Test dropping nonexistent DataFrame"""
+    result = await pandas_tools.drop_data('nonexistent')
+
+    assert 'error' in result
+
+
+@pytest.mark.asyncio
+async def test_operations_on_nonexistent(pandas_tools):
+    """Test operations on nonexistent data_ref"""
+    result = await pandas_tools.describe('nonexistent')
+    assert 'error' in result
+
+    result = await pandas_tools.head('nonexistent')
+    assert 'error' in result
+
+    result = await pandas_tools.filter('nonexistent', 'x > 0')
+    assert 'error' in result

mcp-servers/data-platform/tests/test_postgres_tools.py

@@ -0,0 +1,338 @@
+"""
+Unit tests for PostgreSQL MCP tools.
+"""
+import pytest
+from unittest.mock import Mock, AsyncMock, patch, MagicMock
+import pandas as pd
+
+
+@pytest.fixture
+def mock_config():
+    """Mock configuration"""
+    return {
+        'postgres_url': 'postgresql://test:test@localhost:5432/testdb',
+        'max_rows': 100000
+    }
+
+
+@pytest.fixture
+def postgres_tools(mock_config):
+    """Create PostgresTools instance with mocked config"""
+    with patch('mcp_server.postgres_tools.load_config', return_value=mock_config):
+        from mcp_server.postgres_tools import PostgresTools
+        from mcp_server.data_store import DataStore
+
+        # Reset store
+        store = DataStore.get_instance()
+        store._dataframes = {}
+        store._metadata = {}
+
+        tools = PostgresTools()
+        tools.config = mock_config
+        return tools
+
+
+@pytest.mark.asyncio
+async def test_pg_connect_no_config():
+    """Test pg_connect when no PostgreSQL configured"""
+    with patch('mcp_server.postgres_tools.load_config', return_value={'postgres_url': None}):
+        from mcp_server.postgres_tools import PostgresTools
+
+        tools = PostgresTools()
+        tools.config = {'postgres_url': None}
+
+        result = await tools.pg_connect()
+
+        assert result['connected'] is False
+        assert 'not configured' in result['error'].lower()
+
+
+@pytest.mark.asyncio
+async def test_pg_connect_success(postgres_tools):
+    """Test successful pg_connect"""
+    mock_conn = AsyncMock()
+    mock_conn.fetchval = AsyncMock(side_effect=[
+        'PostgreSQL 15.1',  # version
+        'testdb',           # database name
+        'testuser',         # user
+        None                # PostGIS check fails
+    ])
+    mock_conn.close = AsyncMock()
+
+    # Create proper async context manager
+    mock_cm = AsyncMock()
+    mock_cm.__aenter__ = AsyncMock(return_value=mock_conn)
+    mock_cm.__aexit__ = AsyncMock(return_value=None)
+
+    mock_pool = MagicMock()
+    mock_pool.acquire = MagicMock(return_value=mock_cm)
+
+    # Use AsyncMock for create_pool since it's awaited
+    with patch('asyncpg.create_pool', new=AsyncMock(return_value=mock_pool)):
+        postgres_tools.pool = None
+        result = await postgres_tools.pg_connect()
+
+    assert result['connected'] is True
+    assert result['database'] == 'testdb'
+
+
+@pytest.mark.asyncio
+async def test_pg_query_success(postgres_tools):
+    """Test successful pg_query"""
+    mock_rows = [
+        {'id': 1, 'name': 'Alice'},
+        {'id': 2, 'name': 'Bob'}
+    ]
+
+    mock_conn = AsyncMock()
+    mock_conn.fetch = AsyncMock(return_value=mock_rows)
+
+    mock_pool = AsyncMock()
+    mock_pool.acquire = MagicMock(return_value=AsyncMock(
+        __aenter__=AsyncMock(return_value=mock_conn),
+        __aexit__=AsyncMock()
+    ))
+
+    postgres_tools.pool = mock_pool
+
+    result = await postgres_tools.pg_query('SELECT * FROM users', name='users_data')
+
+    assert 'data_ref' in result
+    assert result['rows'] == 2
+
+
+@pytest.mark.asyncio
+async def test_pg_query_empty_result(postgres_tools):
+    """Test pg_query with no results"""
+    mock_conn = AsyncMock()
+    mock_conn.fetch = AsyncMock(return_value=[])
+
+    mock_pool = AsyncMock()
+    mock_pool.acquire = MagicMock(return_value=AsyncMock(
+        __aenter__=AsyncMock(return_value=mock_conn),
+        __aexit__=AsyncMock()
+    ))
+
+    postgres_tools.pool = mock_pool
+
+    result = await postgres_tools.pg_query('SELECT * FROM empty_table')
+
+    assert result['data_ref'] is None
+    assert result['rows'] == 0
+
+
+@pytest.mark.asyncio
+async def test_pg_execute_success(postgres_tools):
+    """Test successful pg_execute"""
+    mock_conn = AsyncMock()
+    mock_conn.execute = AsyncMock(return_value='INSERT 0 3')
+
+    mock_pool = AsyncMock()
+    mock_pool.acquire = MagicMock(return_value=AsyncMock(
+        __aenter__=AsyncMock(return_value=mock_conn),
+        __aexit__=AsyncMock()
+    ))
+
+    postgres_tools.pool = mock_pool
+
+    result = await postgres_tools.pg_execute('INSERT INTO users VALUES (1, 2, 3)')
+
+    assert result['success'] is True
+    assert result['affected_rows'] == 3
+    assert result['command'] == 'INSERT'
+
+
+@pytest.mark.asyncio
+async def test_pg_tables(postgres_tools):
+    """Test listing tables"""
+    mock_rows = [
+        {'table_name': 'users', 'table_type': 'BASE TABLE', 'column_count': 5},
+        {'table_name': 'orders', 'table_type': 'BASE TABLE', 'column_count': 8}
+    ]
+
+    mock_conn = AsyncMock()
+    mock_conn.fetch = AsyncMock(return_value=mock_rows)
+
+    mock_pool = AsyncMock()
+    mock_pool.acquire = MagicMock(return_value=AsyncMock(
+        __aenter__=AsyncMock(return_value=mock_conn),
+        __aexit__=AsyncMock()
+    ))
+
+    postgres_tools.pool = mock_pool
+
+    result = await postgres_tools.pg_tables(schema='public')
+
+    assert result['schema'] == 'public'
+    assert result['count'] == 2
+    assert len(result['tables']) == 2
+
+
+@pytest.mark.asyncio
+async def test_pg_columns(postgres_tools):
+    """Test getting column info"""
+    mock_rows = [
+        {
+            'column_name': 'id',
+            'data_type': 'integer',
+            'udt_name': 'int4',
+            'is_nullable': 'NO',
+            'column_default': "nextval('users_id_seq'::regclass)",
+            'character_maximum_length': None,
+            'numeric_precision': 32
+        },
+        {
+            'column_name': 'name',
+            'data_type': 'character varying',
+            'udt_name': 'varchar',
+            'is_nullable': 'YES',
+            'column_default': None,
+            'character_maximum_length': 255,
+            'numeric_precision': None
+        }
+    ]
+
+    mock_conn = AsyncMock()
+    mock_conn.fetch = AsyncMock(return_value=mock_rows)
+
+    mock_pool = AsyncMock()
+    mock_pool.acquire = MagicMock(return_value=AsyncMock(
+        __aenter__=AsyncMock(return_value=mock_conn),
+        __aexit__=AsyncMock()
+    ))
+
+    postgres_tools.pool = mock_pool
+
+    result = await postgres_tools.pg_columns(table='users')
+
+    assert result['table'] == 'public.users'
+    assert result['column_count'] == 2
+    assert result['columns'][0]['name'] == 'id'
+    assert result['columns'][0]['nullable'] is False
+
+
+@pytest.mark.asyncio
+async def test_pg_schemas(postgres_tools):
+    """Test listing schemas"""
+    mock_rows = [
+        {'schema_name': 'public'},
+        {'schema_name': 'app'}
+    ]
+
+    mock_conn = AsyncMock()
+    mock_conn.fetch = AsyncMock(return_value=mock_rows)
+
+    mock_pool = AsyncMock()
+    mock_pool.acquire = MagicMock(return_value=AsyncMock(
+        __aenter__=AsyncMock(return_value=mock_conn),
+        __aexit__=AsyncMock()
+    ))
+
+    postgres_tools.pool = mock_pool
+
+    result = await postgres_tools.pg_schemas()
+
+    assert result['count'] == 2
+    assert 'public' in result['schemas']
+
+
+@pytest.mark.asyncio
+async def test_st_tables(postgres_tools):
+    """Test listing PostGIS tables"""
+    mock_rows = [
+        {
+            'table_name': 'locations',
+            'geometry_column': 'geom',
+            'geometry_type': 'POINT',
+            'srid': 4326,
+            'coord_dimension': 2
+        }
+    ]
+
+    mock_conn = AsyncMock()
+    mock_conn.fetch = AsyncMock(return_value=mock_rows)
+
+    mock_pool = AsyncMock()
+    mock_pool.acquire = MagicMock(return_value=AsyncMock(
+        __aenter__=AsyncMock(return_value=mock_conn),
+        __aexit__=AsyncMock()
+    ))
+
+    postgres_tools.pool = mock_pool
+
+    result = await postgres_tools.st_tables()
+
+    assert result['count'] == 1
+    assert result['postgis_tables'][0]['table'] == 'locations'
+    assert result['postgis_tables'][0]['srid'] == 4326
+
+
+@pytest.mark.asyncio
+async def test_st_tables_no_postgis(postgres_tools):
+    """Test st_tables when PostGIS not installed"""
+    mock_conn = AsyncMock()
+    mock_conn.fetch = AsyncMock(side_effect=Exception("relation \"geometry_columns\" does not exist"))
+
+    # Create proper async context manager
+    mock_cm = AsyncMock()
+    mock_cm.__aenter__ = AsyncMock(return_value=mock_conn)
+    mock_cm.__aexit__ = AsyncMock(return_value=None)
+
+    mock_pool = MagicMock()
+    mock_pool.acquire = MagicMock(return_value=mock_cm)
+
+    postgres_tools.pool = mock_pool
+
+    result = await postgres_tools.st_tables()
+
+    assert 'error' in result
+    assert 'PostGIS' in result['error']
+
+
+@pytest.mark.asyncio
+async def test_st_extent(postgres_tools):
+    """Test getting geometry bounding box"""
+    mock_row = {
+        'xmin': -122.5,
+        'ymin': 37.5,
+        'xmax': -122.0,
+        'ymax': 38.0
+    }
+
+    mock_conn = AsyncMock()
+    mock_conn.fetchrow = AsyncMock(return_value=mock_row)
+
+    mock_pool = AsyncMock()
+    mock_pool.acquire = MagicMock(return_value=AsyncMock(
+        __aenter__=AsyncMock(return_value=mock_conn),
+        __aexit__=AsyncMock()
+    ))
+
+    postgres_tools.pool = mock_pool
+
+    result = await postgres_tools.st_extent(table='locations', column='geom')
+
+    assert result['bbox']['xmin'] == -122.5
+    assert result['bbox']['ymax'] == 38.0
+
+
+@pytest.mark.asyncio
+async def test_error_handling(postgres_tools):
+    """Test error handling for database errors"""
+    mock_conn = AsyncMock()
+    mock_conn.fetch = AsyncMock(side_effect=Exception("Connection refused"))
+
+    # Create proper async context manager
+    mock_cm = AsyncMock()
+    mock_cm.__aenter__ = AsyncMock(return_value=mock_conn)
+    mock_cm.__aexit__ = AsyncMock(return_value=None)
+
+    mock_pool = MagicMock()
+    mock_pool.acquire = MagicMock(return_value=mock_cm)
+
+    postgres_tools.pool = mock_pool
+
+    result = await postgres_tools.pg_query('SELECT 1')
+
+    assert 'error' in result
+    assert 'Connection refused' in result['error']

mcp-servers/gitea/README.md

@@ -0,0 +1,47 @@
+# Gitea MCP Server (Marketplace Wrapper)
+
+This directory provides the virtual environment for the `gitea-mcp` package.
+
+## Package
+
+**Source:** [gitea-mcp](https://gitea.hotserv.cloud/personal-projects/gitea-mcp)
+**Registry:** Gitea PyPI at gitea.hotserv.cloud
+**Version:** >=1.0.0
+
+## Setup
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+Or use the marketplace setup script:
+
+```bash
+./scripts/setup-venvs.sh gitea
+```
+
+## Configuration
+
+See `~/.config/claude/gitea.env` for system-level config (API URL, token).
+See project `.env` for project-level config (GITEA_ORG, GITEA_REPO).
+
+## Updating
+
+```bash
+source .venv/bin/activate
+pip install --upgrade gitea-mcp \
+  --extra-index-url https://gitea.hotserv.cloud/api/packages/personal-projects/pypi/simple
+```
+
+## Features
+
+The `gitea-mcp` package provides MCP tools for:
+
+- **Issues**: CRUD, comments, dependencies, execution order
+- **Labels**: Get, suggest, create (org + repo level)
+- **Milestones**: CRUD operations
+- **Pull Requests**: List, get, diff, comments, reviews, create
+- **Wiki**: Pages, lessons learned, RFC allocation
+- **Validation**: Repository org check, branch protection

mcp-servers/gitea/requirements.txt

@@ -0,0 +1,2 @@
+--extra-index-url https://gitea.hotserv.cloud/api/packages/personal-projects/pypi/simple
+gitea-mcp>=1.0.0

mcp-servers/gitea/run.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+# Capture original working directory before any cd operations
+# This should be the user's project directory when launched by Claude Code
+export CLAUDE_PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CACHE_VENV="$HOME/.cache/claude-mcp-venvs/leo-claude-mktplace/gitea/.venv"
+LOCAL_VENV="$SCRIPT_DIR/.venv"
+
+if [[ -f "$CACHE_VENV/bin/python" ]]; then
+    PYTHON="$CACHE_VENV/bin/python"
+elif [[ -f "$LOCAL_VENV/bin/python" ]]; then
+    PYTHON="$LOCAL_VENV/bin/python"
+else
+    echo "ERROR: No venv found. Run: ./scripts/setup-venvs.sh" >&2
+    exit 1
+fi
+
+cd "$SCRIPT_DIR"
+exec "$PYTHON" -m gitea_mcp.server "$@"

mcp-servers/netbox/README.md

@@ -0,0 +1,273 @@
+# NetBox MCP Server
+
+MCP (Model Context Protocol) server for essential NetBox API integration with Claude Code.
+
+## Overview
+
+This MCP server provides Claude Code with focused access to the NetBox REST API for tracking **servers, services, IP addresses, and databases**. It has been optimized to include only essential tools:
+
+- **DCIM** - Sites, Devices (servers/VPS), Interfaces
+- **IPAM** - IP Addresses, Prefixes, Services (applications/databases)
+- **Virtualization** - Clusters, Virtual Machines, VM Interfaces
+- **Extras** - Tags, Journal Entries (audit/notes)
+
+**Total:** 37 tools (~3,700 tokens) — down from 182 tools (~19,810 tokens).
+
+## Installation
+
+### 1. Clone and Setup
+
+```bash
+cd /path/to/mcp-servers/netbox
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+pip install -r requirements.txt
+```
+
+### 2. Configure Credentials
+
+Create the system-level configuration file:
+
+```bash
+mkdir -p ~/.config/claude
+cat > ~/.config/claude/netbox.env << 'EOF'
+NETBOX_API_URL=https://your-netbox-instance/api
+NETBOX_API_TOKEN=your-api-token-here
+NETBOX_VERIFY_SSL=true
+NETBOX_TIMEOUT=30
+EOF
+```
+
+**Getting a NetBox API Token:**
+1. Log into your NetBox instance
+2. Navigate to your profile (top-right menu)
+3. Go to "API Tokens"
+4. Click "Add a token"
+5. Copy the generated token
+
+### 3. Register with Claude Code
+
+Add to your Claude Code MCP configuration (`.claude/mcp.json` or project-level `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "netbox": {
+      "command": "/path/to/mcp-servers/netbox/.venv/bin/python",
+      "args": ["-m", "mcp_server"],
+      "cwd": "/path/to/mcp-servers/netbox"
+    }
+  }
+}
+```
+
+**Windows:**
+```json
+{
+  "mcpServers": {
+    "netbox": {
+      "command": "C:\\path\\to\\mcp-servers\\netbox\\.venv\\Scripts\\python.exe",
+      "args": ["-m", "mcp_server"],
+      "cwd": "C:\\path\\to\\mcp-servers\\netbox"
+    }
+  }
+}
+```
+
+## Available Tools (37 Total)
+
+### DCIM: Sites, Devices, Interfaces (11 tools)
+
+**Sites (4):**
+| Tool | Description | Parameters |
+|------|-------------|-----------|
+| `dcim_list_sites` | List sites | `name`, `status` |
+| `dcim_get_site` | Get site by ID | `id` (required) |
+| `dcim_create_site` | Create site | `name`, `slug` (required), `status` |
+| `dcim_update_site` | Update site | `id` (required), fields to update |
+
+**Devices (4):**
+| Tool | Description | Parameters |
+|------|-------------|-----------|
+| `dcim_list_devices` | List devices (servers/VPS) | `name`, `site_id`, `status`, `role_id` |
+| `dcim_get_device` | Get device by ID | `id` (required) |
+| `dcim_create_device` | Create device | `name`, `device_type`, `role`, `site` (required) |
+| `dcim_update_device` | Update device | `id` (required), fields to update |
+
+**Interfaces (3):**
+| Tool | Description | Parameters |
+|------|-------------|-----------|
+| `dcim_list_interfaces` | List device interfaces | `device_id`, `name`, `type` |
+| `dcim_get_interface` | Get interface by ID | `id` (required) |
+| `dcim_create_interface` | Create interface | `device`, `name`, `type` (required) |
+
+### IPAM: IPs, Prefixes, Services (10 tools)
+
+**IP Addresses (4):**
+| Tool | Description | Parameters |
+|------|-------------|-----------|
+| `ipam_list_ip_addresses` | List IP addresses | `address`, `device_id`, `status` |
+| `ipam_get_ip_address` | Get IP by ID | `id` (required) |
+| `ipam_create_ip_address` | Create IP address | `address` (required), `status`, `assigned_object_type` |
+| `ipam_update_ip_address` | Update IP address | `id` (required), fields to update |
+
+**Prefixes (3):**
+| Tool | Description | Parameters |
+|------|-------------|-----------|
+| `ipam_list_prefixes` | List prefixes | `prefix`, `site_id`, `status` |
+| `ipam_get_prefix` | Get prefix by ID | `id` (required) |
+| `ipam_create_prefix` | Create prefix | `prefix` (required), `status`, `site` |
+
+**Services (3):**
+| Tool | Description | Parameters |
+|------|-------------|-----------|
+| `ipam_list_services` | List services (apps/databases) | `device_id`, `virtual_machine_id`, `name` |
+| `ipam_get_service` | Get service by ID | `id` (required) |
+| `ipam_create_service` | Create service | `name`, `ports`, `protocol` (required), `device`, `virtual_machine` |
+
+### Virtualization: Clusters, VMs, VM Interfaces (10 tools)
+
+**Clusters (3):**
+| Tool | Description | Parameters |
+|------|-------------|-----------|
+| `virt_list_clusters` | List virtualization clusters | `name`, `site_id` |
+| `virt_get_cluster` | Get cluster by ID | `id` (required) |
+| `virt_create_cluster` | Create cluster | `name`, `type` (required), `site` |
+
+**Virtual Machines (4):**
+| Tool | Description | Parameters |
+|------|-------------|-----------|
+| `virt_list_vms` | List VMs | `name`, `cluster_id`, `site_id`, `status` |
+| `virt_get_vm` | Get VM by ID | `id` (required) |
+| `virt_create_vm` | Create VM | `name`, `cluster` (required), `vcpus`, `memory`, `disk` |
+| `virt_update_vm` | Update VM | `id` (required), fields to update |
+
+**VM Interfaces (3):**
+| Tool | Description | Parameters |
+|------|-------------|-----------|
+| `virt_list_vm_ifaces` | List VM interfaces | `virtual_machine_id` |
+| `virt_get_vm_iface` | Get VM interface by ID | `id` (required) |
+| `virt_create_vm_iface` | Create VM interface | `virtual_machine`, `name` (required) |
+
+### Extras: Tags, Journal Entries (6 tools)
+
+**Tags (3):**
+| Tool | Description | Parameters |
+|------|-------------|-----------|
+| `extras_list_tags` | List tags | `name` |
+| `extras_get_tag` | Get tag by ID | `id` (required) |
+| `extras_create_tag` | Create tag | `name`, `slug` (required), `color` |
+
+**Journal Entries (3):**
+| Tool | Description | Parameters |
+|------|-------------|-----------|
+| `extras_list_journal_entries` | List journal entries | `assigned_object_type`, `assigned_object_id` |
+| `extras_get_journal_entry` | Get journal entry by ID | `id` (required) |
+| `extras_create_journal_entry` | Create journal entry | `assigned_object_type`, `assigned_object_id`, `comments` (required), `kind` |
+
+## Configuration
+
+All configuration is done via environment variables in `~/.config/claude/netbox.env`:
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `NETBOX_API_URL` | Yes | — | NetBox API URL (e.g., https://netbox.example.com/api) |
+| `NETBOX_API_TOKEN` | Yes | — | NetBox API token |
+| `NETBOX_VERIFY_SSL` | No | true | Verify SSL certificates |
+| `NETBOX_TIMEOUT` | No | 30 | Request timeout in seconds |
+
+## Architecture
+
+### Hybrid Configuration
+
+- **System-level:** `~/.config/claude/netbox.env` (credentials)
+- **Project-level:** `.env` (optional overrides)
+
+### Tool Routing
+
+Tool names follow the pattern `{module}_{action}_{resource}`:
+- `dcim_list_sites` → DCIMTools.list_sites()
+- `ipam_create_service` → IPAMTools.create_service()
+- `virt_list_vms` → VirtualizationTools.list_virtual_machines()
+
+Shortened names (virt_*) are mapped via TOOL_NAME_MAP to meet the 28-character MCP limit.
+
+### Error Handling
+
+All tools return JSON responses. Errors are caught and returned as:
+```json
+{
+  "error": "Error message",
+  "status_code": 404
+}
+```
+
+## Development
+
+### Testing
+
+```bash
+# Test import
+python -c "from mcp_server.server import NetBoxMCPServer; print('OK')"
+
+# Test tool count
+python -c "from mcp_server.server import TOOL_DEFINITIONS; print(f'{len(TOOL_DEFINITIONS)} tools')"
+```
+
+### File Structure
+
+```
+netbox/
+├── mcp_server/
+│   ├── __init__.py
+│   ├── server.py          # Main MCP server (37 TOOL_DEFINITIONS)
+│   ├── config.py          # Configuration loader
+│   ├── netbox_client.py   # HTTP client wrapper
+│   └── tools/
+│       ├── __init__.py
+│       ├── dcim.py        # Sites, Devices, Interfaces
+│       ├── ipam.py        # IPs, Prefixes, Services
+│       ├── virtualization.py  # Clusters, VMs, VM Interfaces
+│       └── extras.py      # Tags, Journal Entries
+├── .venv/                 # Python virtual environment
+├── requirements.txt
+└── README.md
+```
+
+## Troubleshooting
+
+### MCP Server Won't Start
+
+**Check configuration:**
+```bash
+cat ~/.config/claude/netbox.env
+```
+
+**Test credentials:**
+```bash
+curl -H "Authorization: Token YOUR_TOKEN" https://netbox.example.com/api/
+```
+
+### Tools Not Appearing in Claude
+
+**Verify MCP registration:**
+```bash
+cat ~/.claude/mcp.json  # or project-level .mcp.json
+```
+
+**Check MCP server logs:**
+Claude Code will show MCP server stderr in the UI.
+
+### Connection Errors
+
+- Verify `NETBOX_API_URL` ends with `/api`
+- Check firewall/network connectivity to NetBox instance
+- Ensure API token has required permissions
+
+## License
+
+MIT License - See LICENSE file for details.
+
+## Contributing
+
+This MCP server is part of the leo-claude-mktplace project. For issues or contributions, refer to the main repository.

mcp-servers/netbox/mcp_server/netbox_client.py

@@ -4,6 +4,7 @@ NetBox API client for interacting with NetBox REST API.
 Provides a generic HTTP client with methods for all standard REST operations.
 Individual tool modules use this client for their specific endpoints.
 """
+import json
 import requests
 import logging
 from typing import List, Dict, Optional, Any, Union
@@ -83,7 +84,20 @@ class NetBoxClient:
         if response.status_code == 204 or not response.content:
             return None
 
-        return response.json()
+        # Parse JSON with diagnostic error handling
+        try:
+            return response.json()
+        except json.JSONDecodeError as e:
+            logger.error(
+                f"JSON decode failed. Status: {response.status_code}, "
+                f"Content-Length: {len(response.content)}, "
+                f"Content preview: {response.content[:200]!r}"
+            )
+            raise ValueError(
+                f"Invalid JSON response from NetBox: {e}. "
+                f"Status code: {response.status_code}, "
+                f"Content length: {len(response.content)} bytes"
+            ) from e
 
     def list(
         self,

mcp-servers/netbox/mcp_server/server.py

@@ -0,0 +1,465 @@
+"""
+MCP Server entry point for NetBox integration.
+
+Provides essential NetBox tools to Claude Code via JSON-RPC 2.0 over stdio.
+Covers DCIM, IPAM, Virtualization, and Extras modules.
+"""
+import asyncio
+import logging
+import json
+from typing import Optional
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import Tool, TextContent
+
+from .config import NetBoxConfig
+from .netbox_client import NetBoxClient
+from .tools.dcim import DCIMTools
+from .tools.ipam import IPAMTools
+from .tools.virtualization import VirtualizationTools
+from .tools.extras import ExtrasTools
+
+# Suppress noisy MCP validation warnings on stderr
+logging.basicConfig(level=logging.INFO)
+logging.getLogger("root").setLevel(logging.ERROR)
+logging.getLogger("mcp").setLevel(logging.ERROR)
+logger = logging.getLogger(__name__)
+
+
+# Tool definitions - 37 essential tools for tracking servers, services, IPs, and databases
+TOOL_DEFINITIONS = {
+    # ==================== DCIM: Servers, Sites, Interfaces ====================
+    'dcim_list_sites': {
+        'description': 'List all sites in NetBox',
+        'properties': {
+            'name': {'type': 'string', 'description': 'Filter by name'},
+            'status': {'type': 'string', 'description': 'Filter by status'},
+        }
+    },
+    'dcim_get_site': {
+        'description': 'Get a specific site by ID',
+        'properties': {'id': {'type': 'integer', 'description': 'Site ID'}},
+        'required': ['id']
+    },
+    'dcim_create_site': {
+        'description': 'Create a new site',
+        'properties': {
+            'name': {'type': 'string', 'description': 'Site name'},
+            'slug': {'type': 'string', 'description': 'URL-friendly slug'},
+            'status': {'type': 'string', 'description': 'Status'},
+        },
+        'required': ['name', 'slug']
+    },
+    'dcim_update_site': {
+        'description': 'Update an existing site',
+        'properties': {
+            'id': {'type': 'integer', 'description': 'Site ID'},
+            'name': {'type': 'string', 'description': 'New name'},
+            'status': {'type': 'string', 'description': 'New status'},
+        },
+        'required': ['id']
+    },
+    'dcim_list_devices': {
+        'description': 'List all devices (servers/VPS) in NetBox',
+        'properties': {
+            'name': {'type': 'string', 'description': 'Filter by name'},
+            'site_id': {'type': 'integer', 'description': 'Filter by site'},
+            'status': {'type': 'string', 'description': 'Filter by status'},
+            'role_id': {'type': 'integer', 'description': 'Filter by role'},
+        }
+    },
+    'dcim_get_device': {
+        'description': 'Get a specific device by ID',
+        'properties': {'id': {'type': 'integer', 'description': 'Device ID'}},
+        'required': ['id']
+    },
+    'dcim_create_device': {
+        'description': 'Create a new device',
+        'properties': {
+            'name': {'type': 'string', 'description': 'Device name'},
+            'device_type': {'type': 'integer', 'description': 'Device type ID'},
+            'role': {'type': 'integer', 'description': 'Device role ID'},
+            'site': {'type': 'integer', 'description': 'Site ID'},
+            'status': {'type': 'string', 'description': 'Status'},
+        },
+        'required': ['name', 'device_type', 'role', 'site']
+    },
+    'dcim_update_device': {
+        'description': 'Update an existing device',
+        'properties': {
+            'id': {'type': 'integer', 'description': 'Device ID'},
+            'name': {'type': 'string', 'description': 'New name'},
+            'status': {'type': 'string', 'description': 'New status'},
+        },
+        'required': ['id']
+    },
+    'dcim_list_interfaces': {
+        'description': 'List device interfaces',
+        'properties': {
+            'device_id': {'type': 'integer', 'description': 'Filter by device'},
+            'name': {'type': 'string', 'description': 'Filter by name'},
+            'type': {'type': 'string', 'description': 'Filter by type'},
+        }
+    },
+    'dcim_get_interface': {
+        'description': 'Get a specific interface by ID',
+        'properties': {'id': {'type': 'integer', 'description': 'Interface ID'}},
+        'required': ['id']
+    },
+    'dcim_create_interface': {
+        'description': 'Create a new interface on a device',
+        'properties': {
+            'device': {'type': 'integer', 'description': 'Device ID'},
+            'name': {'type': 'string', 'description': 'Interface name'},
+            'type': {'type': 'string', 'description': 'Interface type'},
+        },
+        'required': ['device', 'name', 'type']
+    },
+
+    # ==================== IPAM: IPs, Prefixes, Services ====================
+    'ipam_list_ip_addresses': {
+        'description': 'List IP addresses',
+        'properties': {
+            'address': {'type': 'string', 'description': 'Filter by address'},
+            'device_id': {'type': 'integer', 'description': 'Filter by device'},
+            'status': {'type': 'string', 'description': 'Filter by status'},
+        }
+    },
+    'ipam_get_ip_address': {
+        'description': 'Get a specific IP address by ID',
+        'properties': {'id': {'type': 'integer', 'description': 'IP address ID'}},
+        'required': ['id']
+    },
+    'ipam_create_ip_address': {
+        'description': 'Create an IP address',
+        'properties': {
+            'address': {'type': 'string', 'description': 'IP address with prefix (e.g., 192.168.1.1/24)'},
+            'status': {'type': 'string', 'description': 'Status'},
+            'assigned_object_type': {'type': 'string', 'description': 'Object type (dcim.interface or virtualization.vminterface)'},
+            'assigned_object_id': {'type': 'integer', 'description': 'Object ID'},
+        },
+        'required': ['address']
+    },
+    'ipam_update_ip_address': {
+        'description': 'Update an IP address',
+        'properties': {
+            'id': {'type': 'integer', 'description': 'IP address ID'},
+            'status': {'type': 'string', 'description': 'New status'},
+        },
+        'required': ['id']
+    },
+    'ipam_list_prefixes': {
+        'description': 'List IP prefixes',
+        'properties': {
+            'prefix': {'type': 'string', 'description': 'Filter by prefix'},
+            'site_id': {'type': 'integer', 'description': 'Filter by site'},
+            'status': {'type': 'string', 'description': 'Filter by status'},
+        }
+    },
+    'ipam_get_prefix': {
+        'description': 'Get a specific prefix by ID',
+        'properties': {'id': {'type': 'integer', 'description': 'Prefix ID'}},
+        'required': ['id']
+    },
+    'ipam_create_prefix': {
+        'description': 'Create an IP prefix',
+        'properties': {
+            'prefix': {'type': 'string', 'description': 'IP prefix (e.g., 192.168.1.0/24)'},
+            'status': {'type': 'string', 'description': 'Status'},
+            'site': {'type': 'integer', 'description': 'Site ID'},
+        },
+        'required': ['prefix']
+    },
+    'ipam_list_services': {
+        'description': 'List services (applications, databases, etc.)',
+        'properties': {
+            'device_id': {'type': 'integer', 'description': 'Filter by device'},
+            'virtual_machine_id': {'type': 'integer', 'description': 'Filter by VM'},
+            'name': {'type': 'string', 'description': 'Filter by name'},
+        }
+    },
+    'ipam_get_service': {
+        'description': 'Get a specific service by ID',
+        'properties': {'id': {'type': 'integer', 'description': 'Service ID'}},
+        'required': ['id']
+    },
+    'ipam_create_service': {
+        'description': 'Create a service (app, database, etc.)',
+        'properties': {
+            'name': {'type': 'string', 'description': 'Service name'},
+            'ports': {'type': 'array', 'description': 'Port numbers', 'items': {'type': 'integer'}},
+            'protocol': {'type': 'string', 'description': 'Protocol (tcp/udp)'},
+            'device': {'type': 'integer', 'description': 'Device ID (if on physical server)'},
+            'virtual_machine': {'type': 'integer', 'description': 'VM ID (if on VM)'},
+        },
+        'required': ['name', 'ports', 'protocol']
+    },
+
+    # ==================== Virtualization: VMs, Clusters ====================
+    'virt_list_clusters': {
+        'description': 'List virtualization clusters',
+        'properties': {
+            'name': {'type': 'string', 'description': 'Filter by name'},
+            'site_id': {'type': 'integer', 'description': 'Filter by site'},
+        }
+    },
+    'virt_get_cluster': {
+        'description': 'Get a specific cluster by ID',
+        'properties': {'id': {'type': 'integer', 'description': 'Cluster ID'}},
+        'required': ['id']
+    },
+    'virt_create_cluster': {
+        'description': 'Create a virtualization cluster',
+        'properties': {
+            'name': {'type': 'string', 'description': 'Cluster name'},
+            'type': {'type': 'integer', 'description': 'Cluster type ID'},
+            'site': {'type': 'integer', 'description': 'Site ID'},
+        },
+        'required': ['name', 'type']
+    },
+    'virt_list_vms': {
+        'description': 'List virtual machines',
+        'properties': {
+            'name': {'type': 'string', 'description': 'Filter by name'},
+            'cluster_id': {'type': 'integer', 'description': 'Filter by cluster'},
+            'site_id': {'type': 'integer', 'description': 'Filter by site'},
+            'status': {'type': 'string', 'description': 'Filter by status'},
+        }
+    },
+    'virt_get_vm': {
+        'description': 'Get a specific VM by ID',
+        'properties': {'id': {'type': 'integer', 'description': 'VM ID'}},
+        'required': ['id']
+    },
+    'virt_create_vm': {
+        'description': 'Create a virtual machine',
+        'properties': {
+            'name': {'type': 'string', 'description': 'VM name'},
+            'cluster': {'type': 'integer', 'description': 'Cluster ID'},
+            'status': {'type': 'string', 'description': 'Status'},
+            'vcpus': {'type': 'number', 'description': 'vCPU count'},
+            'memory': {'type': 'integer', 'description': 'Memory in MB'},
+            'disk': {'type': 'integer', 'description': 'Disk in GB'},
+        },
+        'required': ['name', 'cluster']
+    },
+    'virt_update_vm': {
+        'description': 'Update a virtual machine',
+        'properties': {
+            'id': {'type': 'integer', 'description': 'VM ID'},
+            'name': {'type': 'string', 'description': 'New name'},
+            'status': {'type': 'string', 'description': 'New status'},
+        },
+        'required': ['id']
+    },
+    'virt_list_vm_ifaces': {
+        'description': 'List VM interfaces',
+        'properties': {
+            'virtual_machine_id': {'type': 'integer', 'description': 'Filter by VM'},
+        }
+    },
+    'virt_get_vm_iface': {
+        'description': 'Get a specific VM interface by ID',
+        'properties': {'id': {'type': 'integer', 'description': 'VM interface ID'}},
+        'required': ['id']
+    },
+    'virt_create_vm_iface': {
+        'description': 'Create a VM interface',
+        'properties': {
+            'virtual_machine': {'type': 'integer', 'description': 'VM ID'},
+            'name': {'type': 'string', 'description': 'Interface name'},
+        },
+        'required': ['virtual_machine', 'name']
+    },
+
+    # ==================== Extras: Tags, Journal Entries ====================
+    'extras_list_tags': {
+        'description': 'List all tags in NetBox',
+        'properties': {
+            'name': {'type': 'string', 'description': 'Filter by name'},
+        }
+    },
+    'extras_get_tag': {
+        'description': 'Get a specific tag by ID',
+        'properties': {'id': {'type': 'integer', 'description': 'Tag ID'}},
+        'required': ['id']
+    },
+    'extras_create_tag': {
+        'description': 'Create a new tag',
+        'properties': {
+            'name': {'type': 'string', 'description': 'Tag name'},
+            'slug': {'type': 'string', 'description': 'URL-friendly slug'},
+            'color': {'type': 'string', 'description': 'Hex color code'},
+        },
+        'required': ['name', 'slug']
+    },
+    'extras_list_journal_entries': {
+        'description': 'List journal entries (audit/notes)',
+        'properties': {
+            'assigned_object_type': {'type': 'string', 'description': 'Object type'},
+            'assigned_object_id': {'type': 'integer', 'description': 'Object ID'},
+        }
+    },
+    'extras_get_journal_entry': {
+        'description': 'Get a specific journal entry by ID',
+        'properties': {'id': {'type': 'integer', 'description': 'Entry ID'}},
+        'required': ['id']
+    },
+    'extras_create_journal_entry': {
+        'description': 'Create a journal entry',
+        'properties': {
+            'assigned_object_type': {'type': 'string', 'description': 'Object type (e.g., dcim.device)'},
+            'assigned_object_id': {'type': 'integer', 'description': 'Object ID'},
+            'comments': {'type': 'string', 'description': 'Journal entry text'},
+            'kind': {'type': 'string', 'description': 'Kind (info, success, warning, danger)'},
+        },
+        'required': ['assigned_object_type', 'assigned_object_id', 'comments']
+    },
+}
+
+
+# Tool name mappings for shortened virtualization tools (virt_ prefix)
+TOOL_NAME_MAP = {
+    # Virtualization tools (virt_ prefix -> virtualization category)
+    'virt_list_clusters': ('virtualization', 'list_clusters'),
+    'virt_get_cluster': ('virtualization', 'get_cluster'),
+    'virt_create_cluster': ('virtualization', 'create_cluster'),
+    'virt_list_vms': ('virtualization', 'list_virtual_machines'),
+    'virt_get_vm': ('virtualization', 'get_virtual_machine'),
+    'virt_create_vm': ('virtualization', 'create_virtual_machine'),
+    'virt_update_vm': ('virtualization', 'update_virtual_machine'),
+    'virt_list_vm_ifaces': ('virtualization', 'list_vm_interfaces'),
+    'virt_get_vm_iface': ('virtualization', 'get_vm_interface'),
+    'virt_create_vm_iface': ('virtualization', 'create_vm_interface'),
+}
+
+
+class NetBoxMCPServer:
+    """MCP Server for NetBox integration"""
+
+    def __init__(self):
+        self.server = Server("netbox-mcp")
+        self.config = None
+        self.client = None
+        # Tool instances - always instantiate all 4 modules
+        self.dcim_tools = None
+        self.ipam_tools = None
+        self.virtualization_tools = None
+        self.extras_tools = None
+
+    async def initialize(self):
+        """Initialize server and load configuration."""
+        try:
+            config_loader = NetBoxConfig()
+            self.config = config_loader.load()
+
+            self.client = NetBoxClient()
+
+            # Always instantiate all 4 modules
+            self.dcim_tools = DCIMTools(self.client)
+            self.ipam_tools = IPAMTools(self.client)
+            self.virtualization_tools = VirtualizationTools(self.client)
+            self.extras_tools = ExtrasTools(self.client)
+
+            tool_count = len(TOOL_DEFINITIONS)
+            logger.info(
+                f"NetBox MCP Server initialized: {tool_count} tools registered "
+                f"(modules: dcim, ipam, virtualization, extras)"
+            )
+        except Exception as e:
+            logger.error(f"Failed to initialize: {e}")
+            raise
+
+    def setup_tools(self):
+        """Register all available tools with the MCP server"""
+
+        @self.server.list_tools()
+        async def list_tools() -> list[Tool]:
+            """Return list of available tools"""
+            tools = []
+            for name, definition in TOOL_DEFINITIONS.items():
+                tools.append(Tool(
+                    name=name,
+                    description=definition['description'],
+                    inputSchema={
+                        'type': 'object',
+                        'properties': definition.get('properties', {}),
+                        'required': definition.get('required', [])
+                    }
+                ))
+            return tools
+
+        @self.server.call_tool()
+        async def call_tool(name: str, arguments: dict) -> list[TextContent]:
+            """Handle tool invocation."""
+            try:
+                result = await self._route_tool(name, arguments)
+                return [TextContent(
+                    type="text",
+                    text=json.dumps(result, indent=2, default=str)
+                )]
+            except Exception as e:
+                logger.error(f"Tool {name} failed: {e}")
+                return [TextContent(
+                    type="text",
+                    text=f"Error: {str(e)}"
+                )]
+
+    async def _route_tool(self, name: str, arguments: dict):
+        """Route tool call to appropriate handler.
+
+        Tool names may be shortened (e.g., 'virt_list_vms' instead of
+        'virtualization_list_virtual_machines') to meet the 28-character
+        limit. TOOL_NAME_MAP handles the translation to actual method names.
+        """
+        # Check if this is a mapped short name
+        if name in TOOL_NAME_MAP:
+            category, method_name = TOOL_NAME_MAP[name]
+        else:
+            # Fall back to original logic for unchanged tools
+            parts = name.split('_', 1)
+            if len(parts) != 2:
+                raise ValueError(f"Invalid tool name format: {name}")
+            category, method_name = parts[0], parts[1]
+
+        # Map category to tool class
+        tool_map = {
+            'dcim': self.dcim_tools,
+            'ipam': self.ipam_tools,
+            'virtualization': self.virtualization_tools,
+            'extras': self.extras_tools
+        }
+
+        tool_class = tool_map.get(category)
+        if not tool_class:
+            raise ValueError(f"Unknown tool category: {category}")
+
+        # Get the method
+        method = getattr(tool_class, method_name, None)
+        if not method:
+            raise ValueError(f"Unknown method: {method_name} in {category}")
+
+        # Call the method
+        return await method(**arguments)
+
+    async def run(self):
+        """Run the MCP server"""
+        await self.initialize()
+        self.setup_tools()
+
+        async with stdio_server() as (read_stream, write_stream):
+            await self.server.run(
+                read_stream,
+                write_stream,
+                self.server.create_initialization_options()
+            )
+
+
+async def main():
+    """Main entry point"""
+    server = NetBoxMCPServer()
+    await server.run()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

mcp-servers/netbox/mcp_server/tools/__init__.py

@@ -1,20 +1,12 @@
 """NetBox MCP tools package."""
 from .dcim import DCIMTools
 from .ipam import IPAMTools
-from .circuits import CircuitsTools
 from .virtualization import VirtualizationTools
-from .tenancy import TenancyTools
-from .vpn import VPNTools
-from .wireless import WirelessTools
 from .extras import ExtrasTools
 
 __all__ = [
     'DCIMTools',
     'IPAMTools',
-    'CircuitsTools',
     'VirtualizationTools',
-    'TenancyTools',
-    'VPNTools',
-    'WirelessTools',
     'ExtrasTools',
 ]

mcp-servers/netbox/mcp_server/tools/dcim.py

@@ -0,0 +1,189 @@
+"""
+DCIM (Data Center Infrastructure Management) tools for NetBox MCP Server.
+
+Covers: Sites, Devices, and Interfaces only.
+"""
+import logging
+from typing import List, Dict, Optional, Any
+from ..netbox_client import NetBoxClient
+
+logger = logging.getLogger(__name__)
+
+
+class DCIMTools:
+    """Tools for DCIM operations in NetBox"""
+
+    def __init__(self, client: NetBoxClient):
+        self.client = client
+        self.base_endpoint = 'dcim'
+
+    # ==================== Sites ====================
+
+    async def list_sites(
+        self,
+        name: Optional[str] = None,
+        slug: Optional[str] = None,
+        status: Optional[str] = None,
+        region_id: Optional[int] = None,
+        group_id: Optional[int] = None,
+        tenant_id: Optional[int] = None,
+        **kwargs
+    ) -> List[Dict]:
+        """List all sites with optional filtering."""
+        params = {k: v for k, v in {
+            'name': name, 'slug': slug, 'status': status,
+            'region_id': region_id, 'group_id': group_id, 'tenant_id': tenant_id, **kwargs
+        }.items() if v is not None}
+        return self.client.list(f'{self.base_endpoint}/sites', params=params)
+
+    async def get_site(self, id: int) -> Dict:
+        """Get a specific site by ID."""
+        return self.client.get(f'{self.base_endpoint}/sites', id)
+
+    async def create_site(
+        self,
+        name: str,
+        slug: str,
+        status: str = 'active',
+        region: Optional[int] = None,
+        group: Optional[int] = None,
+        tenant: Optional[int] = None,
+        facility: Optional[str] = None,
+        time_zone: Optional[str] = None,
+        description: Optional[str] = None,
+        physical_address: Optional[str] = None,
+        shipping_address: Optional[str] = None,
+        latitude: Optional[float] = None,
+        longitude: Optional[float] = None,
+        **kwargs
+    ) -> Dict:
+        """Create a new site."""
+        data = {'name': name, 'slug': slug, 'status': status, **kwargs}
+        for key, val in [
+            ('region', region), ('group', group), ('tenant', tenant),
+            ('facility', facility), ('time_zone', time_zone),
+            ('description', description), ('physical_address', physical_address),
+            ('shipping_address', shipping_address), ('latitude', latitude),
+            ('longitude', longitude)
+        ]:
+            if val is not None:
+                data[key] = val
+        return self.client.create(f'{self.base_endpoint}/sites', data)
+
+    async def update_site(self, id: int, **kwargs) -> Dict:
+        """Update a site."""
+        return self.client.patch(f'{self.base_endpoint}/sites', id, kwargs)
+
+    # ==================== Devices ====================
+
+    async def list_devices(
+        self,
+        name: Optional[str] = None,
+        site_id: Optional[int] = None,
+        location_id: Optional[int] = None,
+        rack_id: Optional[int] = None,
+        status: Optional[str] = None,
+        role_id: Optional[int] = None,
+        device_type_id: Optional[int] = None,
+        manufacturer_id: Optional[int] = None,
+        platform_id: Optional[int] = None,
+        tenant_id: Optional[int] = None,
+        serial: Optional[str] = None,
+        asset_tag: Optional[str] = None,
+        **kwargs
+    ) -> List[Dict]:
+        """List all devices with optional filtering."""
+        params = {k: v for k, v in {
+            'name': name, 'site_id': site_id, 'location_id': location_id,
+            'rack_id': rack_id, 'status': status, 'role_id': role_id,
+            'device_type_id': device_type_id, 'manufacturer_id': manufacturer_id,
+            'platform_id': platform_id, 'tenant_id': tenant_id,
+            'serial': serial, 'asset_tag': asset_tag, **kwargs
+        }.items() if v is not None}
+        return self.client.list(f'{self.base_endpoint}/devices', params=params)
+
+    async def get_device(self, id: int) -> Dict:
+        """Get a specific device by ID."""
+        return self.client.get(f'{self.base_endpoint}/devices', id)
+
+    async def create_device(
+        self,
+        name: str,
+        device_type: int,
+        role: int,
+        site: int,
+        status: str = 'active',
+        location: Optional[int] = None,
+        rack: Optional[int] = None,
+        position: Optional[float] = None,
+        face: Optional[str] = None,
+        platform: Optional[int] = None,
+        tenant: Optional[int] = None,
+        serial: Optional[str] = None,
+        asset_tag: Optional[str] = None,
+        primary_ip4: Optional[int] = None,
+        primary_ip6: Optional[int] = None,
+        **kwargs
+    ) -> Dict:
+        """Create a new device."""
+        data = {
+            'name': name, 'device_type': device_type, 'role': role,
+            'site': site, 'status': status, **kwargs
+        }
+        for key, val in [
+            ('location', location), ('rack', rack), ('position', position),
+            ('face', face), ('platform', platform), ('tenant', tenant),
+            ('serial', serial), ('asset_tag', asset_tag),
+            ('primary_ip4', primary_ip4), ('primary_ip6', primary_ip6)
+        ]:
+            if val is not None:
+                data[key] = val
+        return self.client.create(f'{self.base_endpoint}/devices', data)
+
+    async def update_device(self, id: int, **kwargs) -> Dict:
+        """Update a device."""
+        return self.client.patch(f'{self.base_endpoint}/devices', id, kwargs)
+
+    # ==================== Interfaces ====================
+
+    async def list_interfaces(
+        self,
+        device_id: Optional[int] = None,
+        name: Optional[str] = None,
+        type: Optional[str] = None,
+        enabled: Optional[bool] = None,
+        **kwargs
+    ) -> List[Dict]:
+        """List all interfaces."""
+        params = {k: v for k, v in {
+            'device_id': device_id, 'name': name, 'type': type, 'enabled': enabled, **kwargs
+        }.items() if v is not None}
+        return self.client.list(f'{self.base_endpoint}/interfaces', params=params)
+
+    async def get_interface(self, id: int) -> Dict:
+        """Get a specific interface by ID."""
+        return self.client.get(f'{self.base_endpoint}/interfaces', id)
+
+    async def create_interface(
+        self,
+        device: int,
+        name: str,
+        type: str,
+        enabled: bool = True,
+        mtu: Optional[int] = None,
+        mac_address: Optional[str] = None,
+        description: Optional[str] = None,
+        mode: Optional[str] = None,
+        untagged_vlan: Optional[int] = None,
+        tagged_vlans: Optional[List[int]] = None,
+        **kwargs
+    ) -> Dict:
+        """Create a new interface."""
+        data = {'device': device, 'name': name, 'type': type, 'enabled': enabled, **kwargs}
+        for key, val in [
+            ('mtu', mtu), ('mac_address', mac_address), ('description', description),
+            ('mode', mode), ('untagged_vlan', untagged_vlan), ('tagged_vlans', tagged_vlans)
+        ]:
+            if val is not None:
+                data[key] = val
+        return self.client.create(f'{self.base_endpoint}/interfaces', data)

mcp-servers/netbox/mcp_server/tools/extras.py

@@ -0,0 +1,87 @@
+"""
+Extras tools for NetBox MCP Server.
+
+Covers: Tags and Journal Entries only.
+"""
+import logging
+from typing import List, Dict, Optional, Any
+from ..netbox_client import NetBoxClient
+
+logger = logging.getLogger(__name__)
+
+
+class ExtrasTools:
+    """Tools for Extras operations in NetBox"""
+
+    def __init__(self, client: NetBoxClient):
+        self.client = client
+        self.base_endpoint = 'extras'
+
+    # ==================== Tags ====================
+
+    async def list_tags(
+        self,
+        name: Optional[str] = None,
+        slug: Optional[str] = None,
+        color: Optional[str] = None,
+        **kwargs
+    ) -> List[Dict]:
+        """List all tags with optional filtering."""
+        params = {k: v for k, v in {
+            'name': name, 'slug': slug, 'color': color, **kwargs
+        }.items() if v is not None}
+        return self.client.list(f'{self.base_endpoint}/tags', params=params)
+
+    async def get_tag(self, id: int) -> Dict:
+        """Get a specific tag by ID."""
+        return self.client.get(f'{self.base_endpoint}/tags', id)
+
+    async def create_tag(
+        self,
+        name: str,
+        slug: str,
+        color: str = '9e9e9e',
+        description: Optional[str] = None,
+        **kwargs
+    ) -> Dict:
+        """Create a new tag."""
+        data = {'name': name, 'slug': slug, 'color': color, **kwargs}
+        if description:
+            data['description'] = description
+        return self.client.create(f'{self.base_endpoint}/tags', data)
+
+    # ==================== Journal Entries ====================
+
+    async def list_journal_entries(
+        self,
+        assigned_object_type: Optional[str] = None,
+        assigned_object_id: Optional[int] = None,
+        kind: Optional[str] = None,
+        **kwargs
+    ) -> List[Dict]:
+        """List all journal entries."""
+        params = {k: v for k, v in {
+            'assigned_object_type': assigned_object_type,
+            'assigned_object_id': assigned_object_id, 'kind': kind, **kwargs
+        }.items() if v is not None}
+        return self.client.list(f'{self.base_endpoint}/journal-entries', params=params)
+
+    async def get_journal_entry(self, id: int) -> Dict:
+        """Get a specific journal entry by ID."""
+        return self.client.get(f'{self.base_endpoint}/journal-entries', id)
+
+    async def create_journal_entry(
+        self,
+        assigned_object_type: str,
+        assigned_object_id: int,
+        comments: str,
+        kind: str = 'info',
+        **kwargs
+    ) -> Dict:
+        """Create a new journal entry."""
+        data = {
+            'assigned_object_type': assigned_object_type,
+            'assigned_object_id': assigned_object_id,
+            'comments': comments, 'kind': kind, **kwargs
+        }
+        return self.client.create(f'{self.base_endpoint}/journal-entries', data)

mcp-servers/netbox/mcp_server/tools/ipam.py

@@ -0,0 +1,177 @@
+"""
+IPAM (IP Address Management) tools for NetBox MCP Server.
+
+Covers: IP Addresses, Prefixes, and Services only.
+"""
+import logging
+from typing import List, Dict, Optional, Any
+from ..netbox_client import NetBoxClient
+
+logger = logging.getLogger(__name__)
+
+
+class IPAMTools:
+    """Tools for IPAM operations in NetBox"""
+
+    def __init__(self, client: NetBoxClient):
+        self.client = client
+        self.base_endpoint = 'ipam'
+
+    # ==================== Prefixes ====================
+
+    async def list_prefixes(
+        self,
+        prefix: Optional[str] = None,
+        site_id: Optional[int] = None,
+        vrf_id: Optional[int] = None,
+        vlan_id: Optional[int] = None,
+        role_id: Optional[int] = None,
+        tenant_id: Optional[int] = None,
+        status: Optional[str] = None,
+        family: Optional[int] = None,
+        is_pool: Optional[bool] = None,
+        within: Optional[str] = None,
+        within_include: Optional[str] = None,
+        contains: Optional[str] = None,
+        **kwargs
+    ) -> List[Dict]:
+        """List all prefixes with optional filtering."""
+        params = {k: v for k, v in {
+            'prefix': prefix, 'site_id': site_id, 'vrf_id': vrf_id,
+            'vlan_id': vlan_id, 'role_id': role_id, 'tenant_id': tenant_id,
+            'status': status, 'family': family, 'is_pool': is_pool,
+            'within': within, 'within_include': within_include, 'contains': contains, **kwargs
+        }.items() if v is not None}
+        return self.client.list(f'{self.base_endpoint}/prefixes', params=params)
+
+    async def get_prefix(self, id: int) -> Dict:
+        """Get a specific prefix by ID."""
+        return self.client.get(f'{self.base_endpoint}/prefixes', id)
+
+    async def create_prefix(
+        self,
+        prefix: str,
+        status: str = 'active',
+        site: Optional[int] = None,
+        vrf: Optional[int] = None,
+        vlan: Optional[int] = None,
+        role: Optional[int] = None,
+        tenant: Optional[int] = None,
+        is_pool: bool = False,
+        mark_utilized: bool = False,
+        description: Optional[str] = None,
+        **kwargs
+    ) -> Dict:
+        """Create a new prefix."""
+        data = {'prefix': prefix, 'status': status, 'is_pool': is_pool, 'mark_utilized': mark_utilized, **kwargs}
+        for key, val in [
+            ('site', site), ('vrf', vrf), ('vlan', vlan),
+            ('role', role), ('tenant', tenant), ('description', description)
+        ]:
+            if val is not None:
+                data[key] = val
+        return self.client.create(f'{self.base_endpoint}/prefixes', data)
+
+    # ==================== IP Addresses ====================
+
+    async def list_ip_addresses(
+        self,
+        address: Optional[str] = None,
+        vrf_id: Optional[int] = None,
+        tenant_id: Optional[int] = None,
+        status: Optional[str] = None,
+        role: Optional[str] = None,
+        interface_id: Optional[int] = None,
+        device_id: Optional[int] = None,
+        virtual_machine_id: Optional[int] = None,
+        family: Optional[int] = None,
+        parent: Optional[str] = None,
+        dns_name: Optional[str] = None,
+        **kwargs
+    ) -> List[Dict]:
+        """List all IP addresses with optional filtering."""
+        params = {k: v for k, v in {
+            'address': address, 'vrf_id': vrf_id, 'tenant_id': tenant_id,
+            'status': status, 'role': role, 'interface_id': interface_id,
+            'device_id': device_id, 'virtual_machine_id': virtual_machine_id,
+            'family': family, 'parent': parent, 'dns_name': dns_name, **kwargs
+        }.items() if v is not None}
+        return self.client.list(f'{self.base_endpoint}/ip-addresses', params=params)
+
+    async def get_ip_address(self, id: int) -> Dict:
+        """Get a specific IP address by ID."""
+        return self.client.get(f'{self.base_endpoint}/ip-addresses', id)
+
+    async def create_ip_address(
+        self,
+        address: str,
+        status: str = 'active',
+        vrf: Optional[int] = None,
+        tenant: Optional[int] = None,
+        role: Optional[str] = None,
+        assigned_object_type: Optional[str] = None,
+        assigned_object_id: Optional[int] = None,
+        nat_inside: Optional[int] = None,
+        dns_name: Optional[str] = None,
+        description: Optional[str] = None,
+        **kwargs
+    ) -> Dict:
+        """Create a new IP address."""
+        data = {'address': address, 'status': status, **kwargs}
+        for key, val in [
+            ('vrf', vrf), ('tenant', tenant), ('role', role),
+            ('assigned_object_type', assigned_object_type),
+            ('assigned_object_id', assigned_object_id),
+            ('nat_inside', nat_inside), ('dns_name', dns_name),
+            ('description', description)
+        ]:
+            if val is not None:
+                data[key] = val
+        return self.client.create(f'{self.base_endpoint}/ip-addresses', data)
+
+    async def update_ip_address(self, id: int, **kwargs) -> Dict:
+        """Update an IP address."""
+        return self.client.patch(f'{self.base_endpoint}/ip-addresses', id, kwargs)
+
+    # ==================== Services ====================
+
+    async def list_services(
+        self,
+        device_id: Optional[int] = None,
+        virtual_machine_id: Optional[int] = None,
+        name: Optional[str] = None,
+        protocol: Optional[str] = None,
+        port: Optional[int] = None,
+        **kwargs
+    ) -> List[Dict]:
+        """List all services."""
+        params = {k: v for k, v in {
+            'device_id': device_id, 'virtual_machine_id': virtual_machine_id,
+            'name': name, 'protocol': protocol, 'port': port, **kwargs
+        }.items() if v is not None}
+        return self.client.list(f'{self.base_endpoint}/services', params=params)
+
+    async def get_service(self, id: int) -> Dict:
+        """Get a specific service by ID."""
+        return self.client.get(f'{self.base_endpoint}/services', id)
+
+    async def create_service(
+        self,
+        name: str,
+        ports: List[int],
+        protocol: str,
+        device: Optional[int] = None,
+        virtual_machine: Optional[int] = None,
+        ipaddresses: Optional[List[int]] = None,
+        description: Optional[str] = None,
+        **kwargs
+    ) -> Dict:
+        """Create a new service."""
+        data = {'name': name, 'ports': ports, 'protocol': protocol, **kwargs}
+        for key, val in [
+            ('device', device), ('virtual_machine', virtual_machine),
+            ('ipaddresses', ipaddresses), ('description', description)
+        ]:
+            if val is not None:
+                data[key] = val
+        return self.client.create(f'{self.base_endpoint}/services', data)

mcp-servers/netbox/mcp_server/tools/virtualization.py

@@ -1,7 +1,7 @@
 """
 Virtualization tools for NetBox MCP Server.
 
-Covers: Clusters, Virtual Machines, VM Interfaces, and related models.
+Covers: Clusters, Virtual Machines, and VM Interfaces only.
 """
 import logging
 from typing import List, Dict, Optional, Any
@@ -17,80 +17,6 @@ class VirtualizationTools:
         self.client = client
         self.base_endpoint = 'virtualization'
 
-    # ==================== Cluster Types ====================
-
-    async def list_cluster_types(
-        self,
-        name: Optional[str] = None,
-        slug: Optional[str] = None,
-        **kwargs
-    ) -> List[Dict]:
-        """List all cluster types."""
-        params = {k: v for k, v in {'name': name, 'slug': slug, **kwargs}.items() if v is not None}
-        return self.client.list(f'{self.base_endpoint}/cluster-types', params=params)
-
-    async def get_cluster_type(self, id: int) -> Dict:
-        """Get a specific cluster type by ID."""
-        return self.client.get(f'{self.base_endpoint}/cluster-types', id)
-
-    async def create_cluster_type(
-        self,
-        name: str,
-        slug: str,
-        description: Optional[str] = None,
-        **kwargs
-    ) -> Dict:
-        """Create a new cluster type."""
-        data = {'name': name, 'slug': slug, **kwargs}
-        if description:
-            data['description'] = description
-        return self.client.create(f'{self.base_endpoint}/cluster-types', data)
-
-    async def update_cluster_type(self, id: int, **kwargs) -> Dict:
-        """Update a cluster type."""
-        return self.client.patch(f'{self.base_endpoint}/cluster-types', id, kwargs)
-
-    async def delete_cluster_type(self, id: int) -> None:
-        """Delete a cluster type."""
-        self.client.delete(f'{self.base_endpoint}/cluster-types', id)
-
-    # ==================== Cluster Groups ====================
-
-    async def list_cluster_groups(
-        self,
-        name: Optional[str] = None,
-        slug: Optional[str] = None,
-        **kwargs
-    ) -> List[Dict]:
-        """List all cluster groups."""
-        params = {k: v for k, v in {'name': name, 'slug': slug, **kwargs}.items() if v is not None}
-        return self.client.list(f'{self.base_endpoint}/cluster-groups', params=params)
-
-    async def get_cluster_group(self, id: int) -> Dict:
-        """Get a specific cluster group by ID."""
-        return self.client.get(f'{self.base_endpoint}/cluster-groups', id)
-
-    async def create_cluster_group(
-        self,
-        name: str,
-        slug: str,
-        description: Optional[str] = None,
-        **kwargs
-    ) -> Dict:
-        """Create a new cluster group."""
-        data = {'name': name, 'slug': slug, **kwargs}
-        if description:
-            data['description'] = description
-        return self.client.create(f'{self.base_endpoint}/cluster-groups', data)
-
-    async def update_cluster_group(self, id: int, **kwargs) -> Dict:
-        """Update a cluster group."""
-        return self.client.patch(f'{self.base_endpoint}/cluster-groups', id, kwargs)
-
-    async def delete_cluster_group(self, id: int) -> None:
-        """Delete a cluster group."""
-        self.client.delete(f'{self.base_endpoint}/cluster-groups', id)
-
     # ==================== Clusters ====================
 
     async def list_clusters(
@@ -134,14 +60,6 @@ class VirtualizationTools:
                 data[key] = val
         return self.client.create(f'{self.base_endpoint}/clusters', data)
 
-    async def update_cluster(self, id: int, **kwargs) -> Dict:
-        """Update a cluster."""
-        return self.client.patch(f'{self.base_endpoint}/clusters', id, kwargs)
-
-    async def delete_cluster(self, id: int) -> None:
-        """Delete a cluster."""
-        self.client.delete(f'{self.base_endpoint}/clusters', id)
-
     # ==================== Virtual Machines ====================
 
     async def list_virtual_machines(
@@ -201,10 +119,6 @@ class VirtualizationTools:
         """Update a virtual machine."""
         return self.client.patch(f'{self.base_endpoint}/virtual-machines', id, kwargs)
 
-    async def delete_virtual_machine(self, id: int) -> None:
-        """Delete a virtual machine."""
-        self.client.delete(f'{self.base_endpoint}/virtual-machines', id)
-
     # ==================== VM Interfaces ====================
 
     async def list_vm_interfaces(
@@ -246,51 +160,3 @@ class VirtualizationTools:
             if val is not None:
                 data[key] = val
         return self.client.create(f'{self.base_endpoint}/interfaces', data)
-
-    async def update_vm_interface(self, id: int, **kwargs) -> Dict:
-        """Update a VM interface."""
-        return self.client.patch(f'{self.base_endpoint}/interfaces', id, kwargs)
-
-    async def delete_vm_interface(self, id: int) -> None:
-        """Delete a VM interface."""
-        self.client.delete(f'{self.base_endpoint}/interfaces', id)
-
-    # ==================== Virtual Disks ====================
-
-    async def list_virtual_disks(
-        self,
-        virtual_machine_id: Optional[int] = None,
-        name: Optional[str] = None,
-        **kwargs
-    ) -> List[Dict]:
-        """List all virtual disks."""
-        params = {k: v for k, v in {
-            'virtual_machine_id': virtual_machine_id, 'name': name, **kwargs
-        }.items() if v is not None}
-        return self.client.list(f'{self.base_endpoint}/virtual-disks', params=params)
-
-    async def get_virtual_disk(self, id: int) -> Dict:
-        """Get a specific virtual disk by ID."""
-        return self.client.get(f'{self.base_endpoint}/virtual-disks', id)
-
-    async def create_virtual_disk(
-        self,
-        virtual_machine: int,
-        name: str,
-        size: int,
-        description: Optional[str] = None,
-        **kwargs
-    ) -> Dict:
-        """Create a new virtual disk."""
-        data = {'virtual_machine': virtual_machine, 'name': name, 'size': size, **kwargs}
-        if description:
-            data['description'] = description
-        return self.client.create(f'{self.base_endpoint}/virtual-disks', data)
-
-    async def update_virtual_disk(self, id: int, **kwargs) -> Dict:
-        """Update a virtual disk."""
-        return self.client.patch(f'{self.base_endpoint}/virtual-disks', id, kwargs)
-
-    async def delete_virtual_disk(self, id: int) -> None:
-        """Delete a virtual disk."""
-        self.client.delete(f'{self.base_endpoint}/virtual-disks', id)

mcp-servers/netbox/run.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+# Capture original working directory before any cd operations
+# This should be the user's project directory when launched by Claude Code
+export CLAUDE_PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CACHE_VENV="$HOME/.cache/claude-mcp-venvs/leo-claude-mktplace/netbox/.venv"
+LOCAL_VENV="$SCRIPT_DIR/.venv"
+
+if [[ -f "$CACHE_VENV/bin/python" ]]; then
+    PYTHON="$CACHE_VENV/bin/python"
+elif [[ -f "$LOCAL_VENV/bin/python" ]]; then
+    PYTHON="$LOCAL_VENV/bin/python"
+else
+    echo "ERROR: No venv found. Run: ./scripts/setup-venvs.sh" >&2
+    exit 1
+fi
+
+cd "$SCRIPT_DIR"
+export PYTHONPATH="$SCRIPT_DIR"
+exec "$PYTHON" -m mcp_server.server "$@"

mcp-servers/viz-platform/.doc-guardian-queue

@@ -0,0 +1,5 @@
+2026-01-26T11:40:11 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/viz-platform/registry/dmc_2_5.json | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
+2026-01-26T13:46:31 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/viz-platform/tests/test_chart_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
+2026-01-26T13:46:32 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/viz-platform/tests/test_theme_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
+2026-01-26T13:46:34 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/viz-platform/tests/test_theme_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
+2026-01-26T13:46:35 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/viz-platform/tests/test_theme_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md

mcp-servers/viz-platform/README.md

@@ -0,0 +1,115 @@
+# viz-platform MCP Server
+
+Model Context Protocol (MCP) server for Dash Mantine Components validation and visualization tools.
+
+## Overview
+
+This MCP server provides 21 tools for:
+- **DMC Validation**: Version-locked component registry prevents Claude from hallucinating invalid props
+- **Chart Creation**: Plotly-based visualization with theme integration
+- **Layout Composition**: Dashboard layouts with responsive grids
+- **Theme Management**: Design token-based theming system
+- **Page Structure**: Multi-page Dash app generation
+
+## Tools
+
+### DMC Tools (3)
+
+| Tool | Description |
+|------|-------------|
+| `list_components` | List available DMC components by category |
+| `get_component_props` | Get valid props, types, and defaults for a component |
+| `validate_component` | Validate component definition before use |
+
+### Chart Tools (2)
+
+| Tool | Description |
+|------|-------------|
+| `chart_create` | Create Plotly chart (line, bar, scatter, pie, histogram, area, heatmap) |
+| `chart_configure_interaction` | Configure chart interactions (zoom, pan, hover) |
+
+### Layout Tools (5)
+
+| Tool | Description |
+|------|-------------|
+| `layout_create` | Create dashboard layout structure |
+| `layout_add_filter` | Add filter components to layout |
+| `layout_set_grid` | Configure responsive grid settings |
+| `layout_get` | Retrieve layout configuration |
+| `layout_add_section` | Add sections to layout |
+
+### Theme Tools (6)
+
+| Tool | Description |
+|------|-------------|
+| `theme_create` | Create new theme with design tokens |
+| `theme_extend` | Extend existing theme with overrides |
+| `theme_validate` | Validate theme completeness |
+| `theme_export_css` | Export theme as CSS custom properties |
+| `theme_list` | List available themes |
+| `theme_activate` | Set active theme for visualizations |
+
+### Page Tools (5)
+
+| Tool | Description |
+|------|-------------|
+| `page_create` | Create new page structure |
+| `page_add_navbar` | Add navigation bar to page |
+| `page_set_auth` | Configure page authentication |
+| `page_list` | List available pages |
+| `page_get_app_config` | Get full app configuration |
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `DMC_VERSION` | No | Dash Mantine Components version (auto-detected if installed) |
+| `VIZ_DEFAULT_THEME` | No | Default theme name |
+| `CLAUDE_PROJECT_DIR` | No | Project directory for theme storage |
+
+### Theme Storage
+
+Themes can be stored at two levels:
+- **User-level**: `~/.config/claude/themes/`
+- **Project-level**: `{project}/.viz-platform/themes/`
+
+Project-level themes take precedence.
+
+## Component Registry
+
+The server uses a static JSON registry for DMC component validation:
+- Pre-generated from DMC source code
+- Version-tagged (e.g., `dmc_2_5.json`)
+- Prevents hallucination of non-existent props
+- Fast, deterministic validation
+
+Registry files are stored in `registry/` directory.
+
+## Tests
+
+94 tests with coverage:
+- `test_config.py`: 82% coverage
+- `test_component_registry.py`: 92% coverage
+- `test_dmc_tools.py`: 88% coverage
+- `test_chart_tools.py`: 68% coverage
+- `test_theme_tools.py`: 99% coverage
+
+Run tests:
+```bash
+cd mcp-servers/viz-platform
+source .venv/bin/activate
+pytest tests/ -v
+```
+
+## Dependencies
+
+- Python 3.10+
+- FastMCP
+- plotly
+- dash-mantine-components (optional, for version detection)
+
+## Usage
+
+This MCP server is used by the `viz-platform` plugin. See the plugin's commands in `plugins/viz-platform/commands/` for usage.

mcp-servers/viz-platform/mcp_server/__init__.py

@@ -0,0 +1,7 @@
+"""
+viz-platform MCP Server package.
+
+Provides Dash Mantine Components validation and visualization tools to Claude Code.
+"""
+
+__version__ = "1.0.0"

mcp-servers/viz-platform/mcp_server/accessibility_tools.py

@@ -0,0 +1,479 @@
+"""
+Accessibility validation tools for color blindness and WCAG compliance.
+
+Provides tools for validating color palettes against color blindness
+simulations and WCAG contrast requirements.
+"""
+import logging
+import math
+from typing import Dict, List, Optional, Any, Tuple
+
+logger = logging.getLogger(__name__)
+
+
+# Color-blind safe palettes
+SAFE_PALETTES = {
+    "categorical": {
+        "name": "Paul Tol's Qualitative",
+        "colors": ["#4477AA", "#EE6677", "#228833", "#CCBB44", "#66CCEE", "#AA3377", "#BBBBBB"],
+        "description": "Distinguishable for all types of color blindness"
+    },
+    "ibm": {
+        "name": "IBM Design",
+        "colors": ["#648FFF", "#785EF0", "#DC267F", "#FE6100", "#FFB000"],
+        "description": "IBM's accessible color palette"
+    },
+    "okabe_ito": {
+        "name": "Okabe-Ito",
+        "colors": ["#E69F00", "#56B4E9", "#009E73", "#F0E442", "#0072B2", "#D55E00", "#CC79A7", "#000000"],
+        "description": "Optimized for all color vision deficiencies"
+    },
+    "tableau_colorblind": {
+        "name": "Tableau Colorblind 10",
+        "colors": ["#006BA4", "#FF800E", "#ABABAB", "#595959", "#5F9ED1",
+                   "#C85200", "#898989", "#A2C8EC", "#FFBC79", "#CFCFCF"],
+        "description": "Industry-standard accessible palette"
+    }
+}
+
+
+# Simulation matrices for color blindness (LMS color space transformation)
+# These approximate how colors appear to people with different types of color blindness
+SIMULATION_MATRICES = {
+    "deuteranopia": {
+        # Green-blind (most common)
+        "severity": "common",
+        "population": "6% males, 0.4% females",
+        "description": "Difficulty distinguishing red from green (green-blind)",
+        "matrix": [
+            [0.625, 0.375, 0.0],
+            [0.700, 0.300, 0.0],
+            [0.0, 0.300, 0.700]
+        ]
+    },
+    "protanopia": {
+        # Red-blind
+        "severity": "common",
+        "population": "2.5% males, 0.05% females",
+        "description": "Difficulty distinguishing red from green (red-blind)",
+        "matrix": [
+            [0.567, 0.433, 0.0],
+            [0.558, 0.442, 0.0],
+            [0.0, 0.242, 0.758]
+        ]
+    },
+    "tritanopia": {
+        # Blue-blind (rare)
+        "severity": "rare",
+        "population": "0.01% total",
+        "description": "Difficulty distinguishing blue from yellow",
+        "matrix": [
+            [0.950, 0.050, 0.0],
+            [0.0, 0.433, 0.567],
+            [0.0, 0.475, 0.525]
+        ]
+    }
+}
+
+
+class AccessibilityTools:
+    """
+    Color accessibility validation tools.
+
+    Validates colors for WCAG compliance and color blindness accessibility.
+    """
+
+    def __init__(self, theme_store=None):
+        """
+        Initialize accessibility tools.
+
+        Args:
+            theme_store: Optional ThemeStore for theme color extraction
+        """
+        self.theme_store = theme_store
+
+    def _hex_to_rgb(self, hex_color: str) -> Tuple[int, int, int]:
+        """Convert hex color to RGB tuple."""
+        hex_color = hex_color.lstrip('#')
+        if len(hex_color) == 3:
+            hex_color = ''.join([c * 2 for c in hex_color])
+        return tuple(int(hex_color[i:i+2], 16) for i in (0, 2, 4))
+
+    def _rgb_to_hex(self, rgb: Tuple[int, int, int]) -> str:
+        """Convert RGB tuple to hex color."""
+        return '#{:02x}{:02x}{:02x}'.format(
+            max(0, min(255, int(rgb[0]))),
+            max(0, min(255, int(rgb[1]))),
+            max(0, min(255, int(rgb[2])))
+        )
+
+    def _get_relative_luminance(self, rgb: Tuple[int, int, int]) -> float:
+        """
+        Calculate relative luminance per WCAG 2.1.
+
+        https://www.w3.org/WAI/GL/wiki/Relative_luminance
+        """
+        def channel_luminance(value: int) -> float:
+            v = value / 255
+            return v / 12.92 if v <= 0.03928 else ((v + 0.055) / 1.055) ** 2.4
+
+        r, g, b = rgb
+        return (
+            0.2126 * channel_luminance(r) +
+            0.7152 * channel_luminance(g) +
+            0.0722 * channel_luminance(b)
+        )
+
+    def _get_contrast_ratio(self, color1: str, color2: str) -> float:
+        """
+        Calculate contrast ratio between two colors per WCAG 2.1.
+
+        Returns ratio between 1:1 and 21:1.
+        """
+        rgb1 = self._hex_to_rgb(color1)
+        rgb2 = self._hex_to_rgb(color2)
+
+        l1 = self._get_relative_luminance(rgb1)
+        l2 = self._get_relative_luminance(rgb2)
+
+        lighter = max(l1, l2)
+        darker = min(l1, l2)
+
+        return (lighter + 0.05) / (darker + 0.05)
+
+    def _simulate_color_blindness(
+        self,
+        hex_color: str,
+        deficiency_type: str
+    ) -> str:
+        """
+        Simulate how a color appears with a specific color blindness type.
+
+        Uses linear RGB transformation approximation.
+        """
+        if deficiency_type not in SIMULATION_MATRICES:
+            return hex_color
+
+        rgb = self._hex_to_rgb(hex_color)
+        matrix = SIMULATION_MATRICES[deficiency_type]["matrix"]
+
+        # Apply transformation matrix
+        r = rgb[0] * matrix[0][0] + rgb[1] * matrix[0][1] + rgb[2] * matrix[0][2]
+        g = rgb[0] * matrix[1][0] + rgb[1] * matrix[1][1] + rgb[2] * matrix[1][2]
+        b = rgb[0] * matrix[2][0] + rgb[1] * matrix[2][1] + rgb[2] * matrix[2][2]
+
+        return self._rgb_to_hex((r, g, b))
+
+    def _get_color_distance(self, color1: str, color2: str) -> float:
+        """
+        Calculate perceptual color distance (CIE76 approximation).
+
+        Returns a value where < 20 means colors may be hard to distinguish.
+        """
+        rgb1 = self._hex_to_rgb(color1)
+        rgb2 = self._hex_to_rgb(color2)
+
+        # Simple Euclidean distance in RGB space (approximation)
+        # For production, should use CIEDE2000
+        return math.sqrt(
+            (rgb1[0] - rgb2[0]) ** 2 +
+            (rgb1[1] - rgb2[1]) ** 2 +
+            (rgb1[2] - rgb2[2]) ** 2
+        )
+
+    async def accessibility_validate_colors(
+        self,
+        colors: List[str],
+        check_types: Optional[List[str]] = None,
+        min_contrast_ratio: float = 4.5
+    ) -> Dict[str, Any]:
+        """
+        Validate a list of colors for accessibility.
+
+        Args:
+            colors: List of hex colors to validate
+            check_types: Color blindness types to check (default: all)
+            min_contrast_ratio: Minimum WCAG contrast ratio (default: 4.5 for AA)
+
+        Returns:
+            Dict with:
+                - issues: List of accessibility issues found
+                - simulations: How colors appear under each deficiency
+                - recommendations: Suggestions for improvement
+                - safe_palettes: Color-blind safe palette suggestions
+        """
+        check_types = check_types or list(SIMULATION_MATRICES.keys())
+        issues = []
+        simulations = {}
+
+        # Normalize colors
+        normalized_colors = [c.upper() if c.startswith('#') else f'#{c.upper()}' for c in colors]
+
+        # Simulate each color blindness type
+        for deficiency in check_types:
+            if deficiency not in SIMULATION_MATRICES:
+                continue
+
+            simulated = [self._simulate_color_blindness(c, deficiency) for c in normalized_colors]
+            simulations[deficiency] = {
+                "original": normalized_colors,
+                "simulated": simulated,
+                "info": SIMULATION_MATRICES[deficiency]
+            }
+
+            # Check if any color pairs become indistinguishable
+            for i in range(len(normalized_colors)):
+                for j in range(i + 1, len(normalized_colors)):
+                    distance = self._get_color_distance(simulated[i], simulated[j])
+                    if distance < 30:  # Threshold for distinguishability
+                        issues.append({
+                            "type": "distinguishability",
+                            "severity": "warning" if distance > 15 else "error",
+                            "colors": [normalized_colors[i], normalized_colors[j]],
+                            "affected_by": [deficiency],
+                            "simulated_colors": [simulated[i], simulated[j]],
+                            "distance": round(distance, 1),
+                            "message": f"Colors may be hard to distinguish for {deficiency} ({SIMULATION_MATRICES[deficiency]['description']})"
+                        })
+
+        # Check contrast ratios against white and black backgrounds
+        for color in normalized_colors:
+            white_contrast = self._get_contrast_ratio(color, "#FFFFFF")
+            black_contrast = self._get_contrast_ratio(color, "#000000")
+
+            if white_contrast < min_contrast_ratio and black_contrast < min_contrast_ratio:
+                issues.append({
+                    "type": "contrast_ratio",
+                    "severity": "error",
+                    "colors": [color],
+                    "white_contrast": round(white_contrast, 2),
+                    "black_contrast": round(black_contrast, 2),
+                    "required": min_contrast_ratio,
+                    "message": f"Insufficient contrast against both white ({white_contrast:.1f}:1) and black ({black_contrast:.1f}:1) backgrounds"
+                })
+
+        # Generate recommendations
+        recommendations = self._generate_recommendations(issues)
+
+        # Calculate overall score
+        error_count = sum(1 for i in issues if i["severity"] == "error")
+        warning_count = sum(1 for i in issues if i["severity"] == "warning")
+
+        if error_count == 0 and warning_count == 0:
+            score = "A"
+        elif error_count == 0 and warning_count <= 2:
+            score = "B"
+        elif error_count <= 2:
+            score = "C"
+        else:
+            score = "D"
+
+        return {
+            "colors_checked": normalized_colors,
+            "overall_score": score,
+            "issue_count": len(issues),
+            "issues": issues,
+            "simulations": simulations,
+            "recommendations": recommendations,
+            "safe_palettes": SAFE_PALETTES
+        }
+
+    async def accessibility_validate_theme(
+        self,
+        theme_name: str
+    ) -> Dict[str, Any]:
+        """
+        Validate a theme's colors for accessibility.
+
+        Args:
+            theme_name: Theme name to validate
+
+        Returns:
+            Dict with accessibility validation results
+        """
+        if not self.theme_store:
+            return {
+                "error": "Theme store not configured",
+                "theme_name": theme_name
+            }
+
+        theme = self.theme_store.get_theme(theme_name)
+        if not theme:
+            available = self.theme_store.list_themes()
+            return {
+                "error": f"Theme '{theme_name}' not found. Available: {available}",
+                "theme_name": theme_name
+            }
+
+        # Extract colors from theme
+        colors = []
+        tokens = theme.get("tokens", {})
+        color_tokens = tokens.get("colors", {})
+
+        def extract_colors(obj, prefix=""):
+            """Recursively extract color values."""
+            if isinstance(obj, str) and (obj.startswith('#') or len(obj) == 6):
+                colors.append(obj if obj.startswith('#') else f'#{obj}')
+            elif isinstance(obj, dict):
+                for key, value in obj.items():
+                    extract_colors(value, f"{prefix}.{key}")
+            elif isinstance(obj, list):
+                for item in obj:
+                    extract_colors(item, prefix)
+
+        extract_colors(color_tokens)
+
+        # Validate extracted colors
+        result = await self.accessibility_validate_colors(colors)
+        result["theme_name"] = theme_name
+
+        # Add theme-specific checks
+        primary = color_tokens.get("primary")
+        background = color_tokens.get("background", {})
+        text = color_tokens.get("text", {})
+
+        if primary and background:
+            bg_color = background.get("base") if isinstance(background, dict) else background
+            if bg_color:
+                contrast = self._get_contrast_ratio(primary, bg_color)
+                if contrast < 4.5:
+                    result["issues"].append({
+                        "type": "primary_contrast",
+                        "severity": "error",
+                        "colors": [primary, bg_color],
+                        "ratio": round(contrast, 2),
+                        "required": 4.5,
+                        "message": f"Primary color has insufficient contrast ({contrast:.1f}:1) against background"
+                    })
+
+        return result
+
+    async def accessibility_suggest_alternative(
+        self,
+        color: str,
+        deficiency_type: str
+    ) -> Dict[str, Any]:
+        """
+        Suggest accessible alternative colors.
+
+        Args:
+            color: Original hex color
+            deficiency_type: Type of color blindness to optimize for
+
+        Returns:
+            Dict with alternative color suggestions
+        """
+        rgb = self._hex_to_rgb(color)
+
+        suggestions = []
+
+        # Suggest shifting hue while maintaining saturation and brightness
+        # For red-green deficiency, shift toward blue or yellow
+        if deficiency_type in ["deuteranopia", "protanopia"]:
+            # Shift toward blue
+            blue_shift = self._rgb_to_hex((
+                max(0, rgb[0] - 50),
+                max(0, rgb[1] - 30),
+                min(255, rgb[2] + 80)
+            ))
+            suggestions.append({
+                "color": blue_shift,
+                "description": "Blue-shifted alternative",
+                "preserves": "approximate brightness"
+            })
+
+            # Shift toward yellow/orange
+            yellow_shift = self._rgb_to_hex((
+                min(255, rgb[0] + 50),
+                min(255, rgb[1] + 30),
+                max(0, rgb[2] - 80)
+            ))
+            suggestions.append({
+                "color": yellow_shift,
+                "description": "Yellow-shifted alternative",
+                "preserves": "approximate brightness"
+            })
+
+        elif deficiency_type == "tritanopia":
+            # For blue-yellow deficiency, shift toward red or green
+            red_shift = self._rgb_to_hex((
+                min(255, rgb[0] + 60),
+                max(0, rgb[1] - 20),
+                max(0, rgb[2] - 40)
+            ))
+            suggestions.append({
+                "color": red_shift,
+                "description": "Red-shifted alternative",
+                "preserves": "approximate brightness"
+            })
+
+        # Add safe palette suggestions
+        for palette_name, palette in SAFE_PALETTES.items():
+            # Find closest color in safe palette
+            min_distance = float('inf')
+            closest = None
+            for safe_color in palette["colors"]:
+                distance = self._get_color_distance(color, safe_color)
+                if distance < min_distance:
+                    min_distance = distance
+                    closest = safe_color
+
+            if closest:
+                suggestions.append({
+                    "color": closest,
+                    "description": f"From {palette['name']} palette",
+                    "palette": palette_name
+                })
+
+        return {
+            "original_color": color,
+            "deficiency_type": deficiency_type,
+            "suggestions": suggestions[:5]  # Limit to 5 suggestions
+        }
+
+    def _generate_recommendations(self, issues: List[Dict[str, Any]]) -> List[str]:
+        """Generate actionable recommendations based on issues."""
+        recommendations = []
+
+        # Check for distinguishability issues
+        distinguishability_issues = [i for i in issues if i["type"] == "distinguishability"]
+        if distinguishability_issues:
+            affected_types = set()
+            for issue in distinguishability_issues:
+                affected_types.update(issue.get("affected_by", []))
+
+            if "deuteranopia" in affected_types or "protanopia" in affected_types:
+                recommendations.append(
+                    "Avoid using red and green as the only differentiators - "
+                    "add patterns, shapes, or labels"
+                )
+
+            recommendations.append(
+                "Consider using a color-blind safe palette like Okabe-Ito or IBM Design"
+            )
+
+        # Check for contrast issues
+        contrast_issues = [i for i in issues if i["type"] in ["contrast_ratio", "primary_contrast"]]
+        if contrast_issues:
+            recommendations.append(
+                "Increase contrast by darkening colors for light backgrounds "
+                "or lightening for dark backgrounds"
+            )
+            recommendations.append(
+                "Use WCAG contrast checker tools to verify text readability"
+            )
+
+        # General recommendations
+        if len(issues) > 0:
+            recommendations.append(
+                "Add secondary visual cues (icons, patterns, labels) "
+                "to not rely solely on color"
+            )
+
+        if not recommendations:
+            recommendations.append(
+                "Color palette appears accessible! Consider adding patterns "
+                "for additional distinguishability"
+            )
+
+        return recommendations

mcp-servers/viz-platform/mcp_server/chart_tools.py

@@ -0,0 +1,533 @@
+"""
+Chart creation tools using Plotly.
+
+Provides tools for creating data visualizations with automatic theme integration.
+"""
+import base64
+import logging
+import os
+from typing import Dict, List, Optional, Any, Union
+
+logger = logging.getLogger(__name__)
+
+# Check for kaleido availability
+KALEIDO_AVAILABLE = False
+try:
+    import kaleido
+    KALEIDO_AVAILABLE = True
+except ImportError:
+    logger.debug("kaleido not installed - chart export will be unavailable")
+
+
+# Default color palette based on Mantine theme
+DEFAULT_COLORS = [
+    "#228be6",  # blue
+    "#40c057",  # green
+    "#fa5252",  # red
+    "#fab005",  # yellow
+    "#7950f2",  # violet
+    "#fd7e14",  # orange
+    "#20c997",  # teal
+    "#f783ac",  # pink
+    "#868e96",  # gray
+    "#15aabf",  # cyan
+]
+
+
+class ChartTools:
+    """
+    Plotly-based chart creation tools.
+
+    Creates charts that integrate with DMC theming system.
+    """
+
+    def __init__(self, theme_store=None):
+        """
+        Initialize chart tools.
+
+        Args:
+            theme_store: Optional ThemeStore for theme token resolution
+        """
+        self.theme_store = theme_store
+        self._active_theme = None
+
+    def set_theme(self, theme: Dict[str, Any]) -> None:
+        """Set the active theme for chart styling."""
+        self._active_theme = theme
+
+    def _get_color_palette(self) -> List[str]:
+        """Get color palette from theme or defaults."""
+        if self._active_theme and 'colors' in self._active_theme:
+            colors = self._active_theme['colors']
+            # Extract primary colors from theme
+            palette = []
+            for key in ['primary', 'secondary', 'success', 'warning', 'error']:
+                if key in colors:
+                    palette.append(colors[key])
+            if palette:
+                return palette + DEFAULT_COLORS[len(palette):]
+        return DEFAULT_COLORS
+
+    def _resolve_color(self, color: Optional[str]) -> str:
+        """Resolve a color token to actual color value."""
+        if not color:
+            return self._get_color_palette()[0]
+
+        # Check if it's a theme token
+        if self._active_theme and 'colors' in self._active_theme:
+            colors = self._active_theme['colors']
+            if color in colors:
+                return colors[color]
+
+        # Check if it's already a valid color
+        if color.startswith('#') or color.startswith('rgb'):
+            return color
+
+        # Map common color names to palette
+        color_map = {
+            'blue': DEFAULT_COLORS[0],
+            'green': DEFAULT_COLORS[1],
+            'red': DEFAULT_COLORS[2],
+            'yellow': DEFAULT_COLORS[3],
+            'violet': DEFAULT_COLORS[4],
+            'orange': DEFAULT_COLORS[5],
+            'teal': DEFAULT_COLORS[6],
+            'pink': DEFAULT_COLORS[7],
+            'gray': DEFAULT_COLORS[8],
+            'cyan': DEFAULT_COLORS[9],
+        }
+        return color_map.get(color, color)
+
+    async def chart_create(
+        self,
+        chart_type: str,
+        data: Dict[str, Any],
+        options: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """
+        Create a Plotly chart.
+
+        Args:
+            chart_type: Type of chart (line, bar, scatter, pie, heatmap, histogram, area)
+            data: Data specification with x, y values or labels/values for pie
+            options: Optional chart options (title, color, layout settings)
+
+        Returns:
+            Dict with:
+                - figure: Plotly figure JSON
+                - chart_type: Type of chart created
+                - error: Error message if creation failed
+        """
+        options = options or {}
+
+        # Validate chart type
+        valid_types = ['line', 'bar', 'scatter', 'pie', 'heatmap', 'histogram', 'area']
+        if chart_type not in valid_types:
+            return {
+                "error": f"Invalid chart_type '{chart_type}'. Must be one of: {valid_types}",
+                "chart_type": chart_type,
+                "figure": None
+            }
+
+        try:
+            # Build trace based on chart type
+            trace = self._build_trace(chart_type, data, options)
+            if 'error' in trace:
+                return trace
+
+            # Build layout
+            layout = self._build_layout(options)
+
+            # Create figure structure
+            figure = {
+                "data": [trace],
+                "layout": layout
+            }
+
+            return {
+                "figure": figure,
+                "chart_type": chart_type,
+                "trace_count": 1
+            }
+
+        except Exception as e:
+            logger.error(f"Chart creation failed: {e}")
+            return {
+                "error": str(e),
+                "chart_type": chart_type,
+                "figure": None
+            }
+
+    def _build_trace(
+        self,
+        chart_type: str,
+        data: Dict[str, Any],
+        options: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """Build Plotly trace for the chart type."""
+        color = self._resolve_color(options.get('color'))
+        palette = self._get_color_palette()
+
+        # Common trace properties
+        trace: Dict[str, Any] = {}
+
+        if chart_type == 'line':
+            trace = {
+                "type": "scatter",
+                "mode": "lines+markers",
+                "x": data.get('x', []),
+                "y": data.get('y', []),
+                "line": {"color": color},
+                "marker": {"color": color}
+            }
+            if 'name' in data:
+                trace['name'] = data['name']
+
+        elif chart_type == 'bar':
+            trace = {
+                "type": "bar",
+                "x": data.get('x', []),
+                "y": data.get('y', []),
+                "marker": {"color": color}
+            }
+            if options.get('horizontal'):
+                trace['orientation'] = 'h'
+                trace['x'], trace['y'] = trace['y'], trace['x']
+            if 'name' in data:
+                trace['name'] = data['name']
+
+        elif chart_type == 'scatter':
+            trace = {
+                "type": "scatter",
+                "mode": "markers",
+                "x": data.get('x', []),
+                "y": data.get('y', []),
+                "marker": {
+                    "color": color,
+                    "size": options.get('marker_size', 10)
+                }
+            }
+            if 'size' in data:
+                trace['marker']['size'] = data['size']
+            if 'name' in data:
+                trace['name'] = data['name']
+
+        elif chart_type == 'pie':
+            labels = data.get('labels', data.get('x', []))
+            values = data.get('values', data.get('y', []))
+            trace = {
+                "type": "pie",
+                "labels": labels,
+                "values": values,
+                "marker": {"colors": palette[:len(labels)]}
+            }
+            if options.get('donut'):
+                trace['hole'] = options.get('hole', 0.4)
+
+        elif chart_type == 'heatmap':
+            trace = {
+                "type": "heatmap",
+                "z": data.get('z', data.get('values', [])),
+                "x": data.get('x', []),
+                "y": data.get('y', []),
+                "colorscale": options.get('colorscale', 'Blues')
+            }
+
+        elif chart_type == 'histogram':
+            trace = {
+                "type": "histogram",
+                "x": data.get('x', data.get('values', [])),
+                "marker": {"color": color}
+            }
+            if 'nbins' in options:
+                trace['nbinsx'] = options['nbins']
+
+        elif chart_type == 'area':
+            trace = {
+                "type": "scatter",
+                "mode": "lines",
+                "x": data.get('x', []),
+                "y": data.get('y', []),
+                "fill": "tozeroy",
+                "line": {"color": color},
+                "fillcolor": color.replace(')', ', 0.3)').replace('rgb', 'rgba') if color.startswith('rgb') else color + '4D'
+            }
+            if 'name' in data:
+                trace['name'] = data['name']
+
+        else:
+            return {"error": f"Unsupported chart type: {chart_type}"}
+
+        return trace
+
+    def _build_layout(self, options: Dict[str, Any]) -> Dict[str, Any]:
+        """Build Plotly layout from options."""
+        layout: Dict[str, Any] = {
+            "autosize": True,
+            "margin": {"l": 50, "r": 30, "t": 50, "b": 50}
+        }
+
+        # Title
+        if 'title' in options:
+            layout['title'] = {
+                "text": options['title'],
+                "x": 0.5,
+                "xanchor": "center"
+            }
+
+        # Axis labels
+        if 'x_label' in options:
+            layout['xaxis'] = layout.get('xaxis', {})
+            layout['xaxis']['title'] = options['x_label']
+
+        if 'y_label' in options:
+            layout['yaxis'] = layout.get('yaxis', {})
+            layout['yaxis']['title'] = options['y_label']
+
+        # Theme-based styling
+        if self._active_theme:
+            colors = self._active_theme.get('colors', {})
+            bg = colors.get('background', {})
+
+            if isinstance(bg, dict):
+                layout['paper_bgcolor'] = bg.get('base', '#ffffff')
+                layout['plot_bgcolor'] = bg.get('subtle', '#f8f9fa')
+            elif isinstance(bg, str):
+                layout['paper_bgcolor'] = bg
+                layout['plot_bgcolor'] = bg
+
+            text_color = colors.get('text', {})
+            if isinstance(text_color, dict):
+                layout['font'] = {'color': text_color.get('primary', '#212529')}
+            elif isinstance(text_color, str):
+                layout['font'] = {'color': text_color}
+
+        # Additional layout options
+        if 'showlegend' in options:
+            layout['showlegend'] = options['showlegend']
+
+        if 'height' in options:
+            layout['height'] = options['height']
+
+        if 'width' in options:
+            layout['width'] = options['width']
+
+        return layout
+
+    async def chart_configure_interaction(
+        self,
+        figure: Dict[str, Any],
+        interactions: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """
+        Configure interactions for a chart.
+
+        Args:
+            figure: Plotly figure JSON to modify
+            interactions: Interaction configuration:
+                - hover_template: Custom hover text template
+                - click_data: Enable click data capture
+                - selection: Enable selection (box, lasso)
+                - zoom: Enable/disable zoom
+
+        Returns:
+            Dict with:
+                - figure: Updated figure JSON
+                - interactions_added: List of interactions configured
+                - error: Error message if configuration failed
+        """
+        if not figure or 'data' not in figure:
+            return {
+                "error": "Invalid figure: must contain 'data' key",
+                "figure": figure,
+                "interactions_added": []
+            }
+
+        try:
+            interactions_added = []
+
+            # Process each trace
+            for i, trace in enumerate(figure['data']):
+                # Hover template
+                if 'hover_template' in interactions:
+                    trace['hovertemplate'] = interactions['hover_template']
+                    if i == 0:
+                        interactions_added.append('hover_template')
+
+                # Custom hover info
+                if 'hover_info' in interactions:
+                    trace['hoverinfo'] = interactions['hover_info']
+                    if i == 0:
+                        interactions_added.append('hover_info')
+
+            # Layout-level interactions
+            layout = figure.get('layout', {})
+
+            # Click data (Dash callback integration)
+            if interactions.get('click_data', False):
+                layout['clickmode'] = 'event+select'
+                interactions_added.append('click_data')
+
+            # Selection mode
+            if 'selection' in interactions:
+                sel_mode = interactions['selection']
+                if sel_mode in ['box', 'lasso', 'box+lasso']:
+                    layout['dragmode'] = 'select' if sel_mode == 'box' else sel_mode
+                    interactions_added.append(f'selection:{sel_mode}')
+
+            # Zoom configuration
+            if 'zoom' in interactions:
+                if not interactions['zoom']:
+                    layout['xaxis'] = layout.get('xaxis', {})
+                    layout['yaxis'] = layout.get('yaxis', {})
+                    layout['xaxis']['fixedrange'] = True
+                    layout['yaxis']['fixedrange'] = True
+                    interactions_added.append('zoom:disabled')
+                else:
+                    interactions_added.append('zoom:enabled')
+
+            # Modebar configuration
+            if 'modebar' in interactions:
+                layout['modebar'] = interactions['modebar']
+                interactions_added.append('modebar')
+
+            figure['layout'] = layout
+
+            return {
+                "figure": figure,
+                "interactions_added": interactions_added
+            }
+
+        except Exception as e:
+            logger.error(f"Interaction configuration failed: {e}")
+            return {
+                "error": str(e),
+                "figure": figure,
+                "interactions_added": []
+            }
+
+    async def chart_export(
+        self,
+        figure: Dict[str, Any],
+        format: str = "png",
+        width: Optional[int] = None,
+        height: Optional[int] = None,
+        scale: float = 2.0,
+        output_path: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Export a Plotly chart to a static image format.
+
+        Args:
+            figure: Plotly figure JSON to export
+            format: Output format - png, svg, or pdf
+            width: Image width in pixels (default: from figure or 1200)
+            height: Image height in pixels (default: from figure or 800)
+            scale: Resolution scale factor (default: 2 for retina)
+            output_path: Optional file path to save the image
+
+        Returns:
+            Dict with:
+                - image_data: Base64-encoded image (if no output_path)
+                - file_path: Path to saved file (if output_path provided)
+                - format: Export format used
+                - dimensions: {width, height, scale}
+                - error: Error message if export failed
+        """
+        # Validate format
+        valid_formats = ['png', 'svg', 'pdf']
+        format = format.lower()
+        if format not in valid_formats:
+            return {
+                "error": f"Invalid format '{format}'. Must be one of: {valid_formats}",
+                "format": format,
+                "image_data": None
+            }
+
+        # Check kaleido availability
+        if not KALEIDO_AVAILABLE:
+            return {
+                "error": "kaleido package not installed. Install with: pip install kaleido",
+                "format": format,
+                "image_data": None,
+                "install_hint": "pip install kaleido"
+            }
+
+        # Validate figure
+        if not figure or 'data' not in figure:
+            return {
+                "error": "Invalid figure: must contain 'data' key",
+                "format": format,
+                "image_data": None
+            }
+
+        try:
+            import plotly.graph_objects as go
+            import plotly.io as pio
+
+            # Create Plotly figure object
+            fig = go.Figure(figure)
+
+            # Determine dimensions
+            layout = figure.get('layout', {})
+            export_width = width or layout.get('width') or 1200
+            export_height = height or layout.get('height') or 800
+
+            # Export to bytes
+            image_bytes = pio.to_image(
+                fig,
+                format=format,
+                width=export_width,
+                height=export_height,
+                scale=scale
+            )
+
+            result = {
+                "format": format,
+                "dimensions": {
+                    "width": export_width,
+                    "height": export_height,
+                    "scale": scale,
+                    "effective_width": int(export_width * scale),
+                    "effective_height": int(export_height * scale)
+                }
+            }
+
+            # Save to file or return base64
+            if output_path:
+                # Ensure directory exists
+                output_dir = os.path.dirname(output_path)
+                if output_dir and not os.path.exists(output_dir):
+                    os.makedirs(output_dir, exist_ok=True)
+
+                # Add extension if missing
+                if not output_path.endswith(f'.{format}'):
+                    output_path = f"{output_path}.{format}"
+
+                with open(output_path, 'wb') as f:
+                    f.write(image_bytes)
+
+                result["file_path"] = output_path
+                result["file_size_bytes"] = len(image_bytes)
+            else:
+                # Return as base64
+                result["image_data"] = base64.b64encode(image_bytes).decode('utf-8')
+                result["data_uri"] = f"data:image/{format};base64,{result['image_data']}"
+
+            return result
+
+        except ImportError as e:
+            logger.error(f"Chart export failed - missing dependency: {e}")
+            return {
+                "error": f"Missing dependency for export: {e}",
+                "format": format,
+                "image_data": None,
+                "install_hint": "pip install plotly kaleido"
+            }
+        except Exception as e:
+            logger.error(f"Chart export failed: {e}")
+            return {
+                "error": str(e),
+                "format": format,
+                "image_data": None
+            }

mcp-servers/viz-platform/mcp_server/component_registry.py

@@ -0,0 +1,301 @@
+"""
+DMC Component Registry for viz-platform.
+
+Provides version-locked component definitions to prevent Claude from
+hallucinating invalid props. Uses static JSON registries pre-generated
+from DMC source.
+"""
+import json
+import logging
+from pathlib import Path
+from typing import Dict, List, Optional, Any
+
+logger = logging.getLogger(__name__)
+
+
+class ComponentRegistry:
+    """
+    Version-locked registry of Dash Mantine Components.
+
+    Loads component definitions from static JSON files and provides
+    lookup methods for validation tools.
+    """
+
+    def __init__(self, dmc_version: Optional[str] = None):
+        """
+        Initialize the component registry.
+
+        Args:
+            dmc_version: Installed DMC version (e.g., "0.14.7").
+                        If None, will try to detect or use fallback.
+        """
+        self.dmc_version = dmc_version
+        self.registry_dir = Path(__file__).parent.parent / 'registry'
+        self.components: Dict[str, Dict[str, Any]] = {}
+        self.categories: Dict[str, List[str]] = {}
+        self.loaded_version: Optional[str] = None
+
+    def load(self) -> bool:
+        """
+        Load the component registry for the configured DMC version.
+
+        Returns:
+            True if registry loaded successfully, False otherwise
+        """
+        registry_file = self._find_registry_file()
+
+        if not registry_file:
+            logger.warning(
+                f"No registry found for DMC {self.dmc_version}. "
+                "Component validation will be limited."
+            )
+            return False
+
+        try:
+            with open(registry_file, 'r') as f:
+                data = json.load(f)
+
+            self.loaded_version = data.get('version')
+            self.components = data.get('components', {})
+            self.categories = data.get('categories', {})
+
+            logger.info(
+                f"Loaded component registry v{self.loaded_version} "
+                f"with {len(self.components)} components"
+            )
+            return True
+
+        except Exception as e:
+            logger.error(f"Failed to load registry: {e}")
+            return False
+
+    def _find_registry_file(self) -> Optional[Path]:
+        """
+        Find the best matching registry file for the DMC version.
+
+        Strategy:
+        1. Exact major.minor match (e.g., dmc_0_14.json for 0.14.7)
+        2. Fallback to latest available registry
+
+        Returns:
+            Path to registry file, or None if not found
+        """
+        if not self.registry_dir.exists():
+            logger.warning(f"Registry directory not found: {self.registry_dir}")
+            return None
+
+        # Try exact major.minor match
+        if self.dmc_version:
+            parts = self.dmc_version.split('.')
+            if len(parts) >= 2:
+                major_minor = f"{parts[0]}_{parts[1]}"
+                exact_match = self.registry_dir / f"dmc_{major_minor}.json"
+                if exact_match.exists():
+                    return exact_match
+
+        # Fallback: find latest registry
+        registry_files = list(self.registry_dir.glob("dmc_*.json"))
+        if registry_files:
+            # Sort by version and return latest
+            registry_files.sort(reverse=True)
+            fallback = registry_files[0]
+            if self.dmc_version:
+                logger.warning(
+                    f"No exact match for DMC {self.dmc_version}, "
+                    f"using fallback: {fallback.name}"
+                )
+            return fallback
+
+        return None
+
+    def get_component(self, name: str) -> Optional[Dict[str, Any]]:
+        """
+        Get component definition by name.
+
+        Args:
+            name: Component name (e.g., "Button", "TextInput")
+
+        Returns:
+            Component definition dict, or None if not found
+        """
+        return self.components.get(name)
+
+    def get_component_props(self, name: str) -> Optional[Dict[str, Any]]:
+        """
+        Get props schema for a component.
+
+        Args:
+            name: Component name
+
+        Returns:
+            Props dict with type info, or None if component not found
+        """
+        component = self.get_component(name)
+        if component:
+            return component.get('props', {})
+        return None
+
+    def list_components(self, category: Optional[str] = None) -> Dict[str, List[str]]:
+        """
+        List available components, optionally filtered by category.
+
+        Args:
+            category: Optional category filter (e.g., "inputs", "buttons")
+
+        Returns:
+            Dict of category -> component names
+        """
+        if category:
+            if category in self.categories:
+                return {category: self.categories[category]}
+            return {}
+        return self.categories
+
+    def get_categories(self) -> List[str]:
+        """
+        Get list of available component categories.
+
+        Returns:
+            List of category names
+        """
+        return list(self.categories.keys())
+
+    def validate_prop(
+        self,
+        component: str,
+        prop_name: str,
+        prop_value: Any
+    ) -> Dict[str, Any]:
+        """
+        Validate a single prop value against the registry.
+
+        Args:
+            component: Component name
+            prop_name: Prop name
+            prop_value: Value to validate
+
+        Returns:
+            Dict with valid: bool, error: Optional[str]
+        """
+        props = self.get_component_props(component)
+        if props is None:
+            return {
+                'valid': False,
+                'error': f"Unknown component: {component}"
+            }
+
+        if prop_name not in props:
+            # Check for similar prop names (typo detection)
+            similar = self._find_similar_props(prop_name, props.keys())
+            if similar:
+                return {
+                    'valid': False,
+                    'error': f"Unknown prop '{prop_name}' for {component}. Did you mean '{similar}'?"
+                }
+            return {
+                'valid': False,
+                'error': f"Unknown prop '{prop_name}' for {component}"
+            }
+
+        prop_schema = props[prop_name]
+        return self._validate_value(prop_value, prop_schema, prop_name)
+
+    def _validate_value(
+        self,
+        value: Any,
+        schema: Dict[str, Any],
+        prop_name: str
+    ) -> Dict[str, Any]:
+        """
+        Validate a value against a prop schema.
+
+        Args:
+            value: Value to validate
+            schema: Prop schema from registry
+            prop_name: Prop name (for error messages)
+
+        Returns:
+            Dict with valid: bool, error: Optional[str]
+        """
+        prop_type = schema.get('type', 'any')
+
+        # Any type always valid
+        if prop_type == 'any':
+            return {'valid': True}
+
+        # Check enum values
+        if 'enum' in schema:
+            if value not in schema['enum']:
+                return {
+                    'valid': False,
+                    'error': f"Prop '{prop_name}' expects one of {schema['enum']}, got '{value}'"
+                }
+            return {'valid': True}
+
+        # Type checking
+        type_checks = {
+            'string': lambda v: isinstance(v, str),
+            'number': lambda v: isinstance(v, (int, float)),
+            'integer': lambda v: isinstance(v, int),
+            'boolean': lambda v: isinstance(v, bool),
+            'array': lambda v: isinstance(v, list),
+            'object': lambda v: isinstance(v, dict),
+        }
+
+        checker = type_checks.get(prop_type)
+        if checker and not checker(value):
+            return {
+                'valid': False,
+                'error': f"Prop '{prop_name}' expects type '{prop_type}', got '{type(value).__name__}'"
+            }
+
+        return {'valid': True}
+
+    def _find_similar_props(
+        self,
+        prop_name: str,
+        available_props: List[str]
+    ) -> Optional[str]:
+        """
+        Find a similar prop name for typo suggestions.
+
+        Uses simple edit distance heuristic.
+
+        Args:
+            prop_name: The (possibly misspelled) prop name
+            available_props: List of valid prop names
+
+        Returns:
+            Most similar prop name, or None if no close match
+        """
+        prop_lower = prop_name.lower()
+
+        for prop in available_props:
+            # Exact match after lowercase
+            if prop.lower() == prop_lower:
+                return prop
+            # Common typos: extra/missing letter
+            if abs(len(prop) - len(prop_name)) == 1:
+                if prop_lower.startswith(prop.lower()[:3]):
+                    return prop
+
+        return None
+
+    def is_loaded(self) -> bool:
+        """Check if registry is loaded."""
+        return len(self.components) > 0
+
+
+def load_registry(dmc_version: Optional[str] = None) -> ComponentRegistry:
+    """
+    Convenience function to load and return a component registry.
+
+    Args:
+        dmc_version: Optional DMC version string
+
+    Returns:
+        Loaded ComponentRegistry instance
+    """
+    registry = ComponentRegistry(dmc_version)
+    registry.load()
+    return registry

mcp-servers/viz-platform/mcp_server/config.py

@@ -0,0 +1,172 @@
+"""
+Configuration loader for viz-platform MCP Server.
+
+Implements hybrid configuration system:
+- System-level: ~/.config/claude/viz-platform.env (theme preferences)
+- Project-level: .env (DMC version overrides)
+- Auto-detection: DMC package version from installed package
+"""
+from pathlib import Path
+from dotenv import load_dotenv
+import os
+import logging
+from typing import Dict, Optional
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+class VizPlatformConfig:
+    """Hybrid configuration loader for viz-platform tools"""
+
+    def __init__(self):
+        self.dmc_version: Optional[str] = None
+        self.theme_dir_user: Path = Path.home() / '.config' / 'claude' / 'themes'
+        self.theme_dir_project: Optional[Path] = None
+        self.default_theme: Optional[str] = None
+
+    def load(self) -> Dict[str, any]:
+        """
+        Load configuration from system and project levels.
+
+        Returns:
+            Dict containing dmc_version, theme directories, and availability flags
+        """
+        # Load system config
+        system_config = Path.home() / '.config' / 'claude' / 'viz-platform.env'
+        if system_config.exists():
+            load_dotenv(system_config)
+            logger.info(f"Loaded system configuration from {system_config}")
+
+        # Find project directory
+        project_dir = self._find_project_directory()
+
+        # Load project config (overrides system)
+        if project_dir:
+            project_config = project_dir / '.env'
+            if project_config.exists():
+                load_dotenv(project_config, override=True)
+                logger.info(f"Loaded project configuration from {project_config}")
+
+            # Set project theme directory
+            self.theme_dir_project = project_dir / '.viz-platform' / 'themes'
+
+        # Get DMC version (from env or auto-detect)
+        self.dmc_version = os.getenv('DMC_VERSION') or self._detect_dmc_version()
+        self.default_theme = os.getenv('VIZ_DEFAULT_THEME')
+
+        # Ensure user theme directory exists
+        self.theme_dir_user.mkdir(parents=True, exist_ok=True)
+
+        return {
+            'dmc_version': self.dmc_version,
+            'dmc_available': self.dmc_version is not None,
+            'theme_dir_user': str(self.theme_dir_user),
+            'theme_dir_project': str(self.theme_dir_project) if self.theme_dir_project else None,
+            'default_theme': self.default_theme,
+            'project_dir': str(project_dir) if project_dir else None
+        }
+
+    def _detect_dmc_version(self) -> Optional[str]:
+        """
+        Auto-detect installed Dash Mantine Components version.
+
+        Returns:
+            Version string (e.g., "0.14.7") or None if not installed
+        """
+        try:
+            from importlib.metadata import version
+            dmc_version = version('dash-mantine-components')
+            logger.info(f"Detected DMC version: {dmc_version}")
+            return dmc_version
+        except ImportError:
+            logger.warning("dash-mantine-components not installed - using registry fallback")
+            return None
+        except Exception as e:
+            logger.warning(f"Could not detect DMC version: {e}")
+            return None
+
+    def _find_project_directory(self) -> Optional[Path]:
+        """
+        Find the user's project directory.
+
+        Returns:
+            Path to project directory, or None if not found
+        """
+        # Strategy 1: Check CLAUDE_PROJECT_DIR environment variable
+        project_dir = os.getenv('CLAUDE_PROJECT_DIR')
+        if project_dir:
+            path = Path(project_dir)
+            if path.exists():
+                logger.info(f"Found project directory from CLAUDE_PROJECT_DIR: {path}")
+                return path
+
+        # Strategy 2: Check PWD
+        pwd = os.getenv('PWD')
+        if pwd:
+            path = Path(pwd)
+            if path.exists() and (
+                (path / '.git').exists() or
+                (path / '.env').exists() or
+                (path / '.viz-platform').exists()
+            ):
+                logger.info(f"Found project directory from PWD: {path}")
+                return path
+
+        # Strategy 3: Check current working directory
+        cwd = Path.cwd()
+        if (cwd / '.git').exists() or (cwd / '.env').exists() or (cwd / '.viz-platform').exists():
+            logger.info(f"Found project directory from cwd: {cwd}")
+            return cwd
+
+        logger.debug("Could not determine project directory")
+        return None
+
+
+def load_config() -> Dict[str, any]:
+    """
+    Convenience function to load configuration.
+
+    Returns:
+        Configuration dictionary
+    """
+    config = VizPlatformConfig()
+    return config.load()
+
+
+def check_dmc_version() -> Dict[str, any]:
+    """
+    Check DMC installation status for SessionStart hook.
+
+    Returns:
+        Dict with installation status and version info
+    """
+    config = load_config()
+
+    if not config.get('dmc_available'):
+        return {
+            'installed': False,
+            'message': 'dash-mantine-components not installed. Run: pip install dash-mantine-components'
+        }
+
+    version = config.get('dmc_version', 'unknown')
+
+    # Check for registry compatibility
+    registry_path = Path(__file__).parent.parent / 'registry'
+    major_minor = '.'.join(version.split('.')[:2]) if version else None
+    registry_file = registry_path / f'dmc_{major_minor.replace(".", "_")}.json' if major_minor else None
+
+    if registry_file and registry_file.exists():
+        return {
+            'installed': True,
+            'version': version,
+            'registry_available': True,
+            'message': f'DMC {version} ready with component registry'
+        }
+    else:
+        return {
+            'installed': True,
+            'version': version,
+            'registry_available': False,
+            'message': f'DMC {version} installed but no matching registry. Validation may be limited.'
+        }

mcp-servers/viz-platform/mcp_server/dmc_tools.py

@@ -0,0 +1,306 @@
+"""
+DMC (Dash Mantine Components) validation tools.
+
+Provides component constraint layer to prevent Claude from hallucinating invalid props.
+"""
+import logging
+from typing import Dict, List, Optional, Any
+
+from .component_registry import ComponentRegistry
+
+logger = logging.getLogger(__name__)
+
+
+class DMCTools:
+    """
+    DMC component validation tools.
+
+    These tools provide the "constraint layer" that validates component usage
+    against a version-locked registry of DMC components.
+    """
+
+    def __init__(self, registry: Optional[ComponentRegistry] = None):
+        """
+        Initialize DMC tools with component registry.
+
+        Args:
+            registry: ComponentRegistry instance. If None, creates one.
+        """
+        self.registry = registry
+        self._initialized = False
+
+    def initialize(self, dmc_version: Optional[str] = None) -> bool:
+        """
+        Initialize the registry if not already provided.
+
+        Args:
+            dmc_version: DMC version to load registry for
+
+        Returns:
+            True if initialized successfully
+        """
+        if self.registry is None:
+            self.registry = ComponentRegistry(dmc_version)
+
+        if not self.registry.is_loaded():
+            self.registry.load()
+
+        self._initialized = self.registry.is_loaded()
+        return self._initialized
+
+    async def list_components(
+        self,
+        category: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        List available DMC components, optionally filtered by category.
+
+        Args:
+            category: Optional category filter (e.g., "inputs", "buttons", "navigation")
+
+        Returns:
+            Dict with:
+                - components: Dict[category -> [component names]]
+                - categories: List of available categories
+                - version: Loaded DMC registry version
+                - total_count: Total number of components
+        """
+        if not self._initialized:
+            return {
+                "error": "Registry not initialized",
+                "components": {},
+                "categories": [],
+                "version": None,
+                "total_count": 0
+            }
+
+        components = self.registry.list_components(category)
+        all_categories = self.registry.get_categories()
+
+        # Count total components
+        total = sum(len(comps) for comps in components.values())
+
+        return {
+            "components": components,
+            "categories": all_categories if not category else [category],
+            "version": self.registry.loaded_version,
+            "total_count": total
+        }
+
+    async def get_component_props(self, component: str) -> Dict[str, Any]:
+        """
+        Get props schema for a specific component.
+
+        Args:
+            component: Component name (e.g., "Button", "TextInput")
+
+        Returns:
+            Dict with:
+                - component: Component name
+                - description: Component description
+                - props: Dict of prop name -> {type, default, enum, description}
+                - prop_count: Number of props
+                - required: List of required prop names
+            Or error dict if component not found
+        """
+        if not self._initialized:
+            return {
+                "error": "Registry not initialized",
+                "component": component,
+                "props": {},
+                "prop_count": 0
+            }
+
+        comp_def = self.registry.get_component(component)
+        if not comp_def:
+            # Try to suggest similar component name
+            similar = self._find_similar_component(component)
+            error_msg = f"Component '{component}' not found in registry"
+            if similar:
+                error_msg += f". Did you mean '{similar}'?"
+
+            return {
+                "error": error_msg,
+                "component": component,
+                "props": {},
+                "prop_count": 0
+            }
+
+        props = comp_def.get('props', {})
+
+        # Extract required props
+        required = [
+            name for name, schema in props.items()
+            if schema.get('required', False)
+        ]
+
+        return {
+            "component": component,
+            "description": comp_def.get('description', ''),
+            "props": props,
+            "prop_count": len(props),
+            "required": required,
+            "version": self.registry.loaded_version
+        }
+
+    async def validate_component(
+        self,
+        component: str,
+        props: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """
+        Validate component props against registry.
+
+        Args:
+            component: Component name
+            props: Props dict to validate
+
+        Returns:
+            Dict with:
+                - valid: bool - True if all props are valid
+                - errors: List of error messages
+                - warnings: List of warning messages
+                - validated_props: Number of props validated
+                - component: Component name for reference
+        """
+        if not self._initialized:
+            return {
+                "valid": False,
+                "errors": ["Registry not initialized"],
+                "warnings": [],
+                "validated_props": 0,
+                "component": component
+            }
+
+        errors: List[str] = []
+        warnings: List[str] = []
+
+        # Check if component exists
+        comp_def = self.registry.get_component(component)
+        if not comp_def:
+            similar = self._find_similar_component(component)
+            error_msg = f"Unknown component: {component}"
+            if similar:
+                error_msg += f". Did you mean '{similar}'?"
+            errors.append(error_msg)
+
+            return {
+                "valid": False,
+                "errors": errors,
+                "warnings": warnings,
+                "validated_props": 0,
+                "component": component
+            }
+
+        comp_props = comp_def.get('props', {})
+
+        # Check for required props
+        for prop_name, prop_schema in comp_props.items():
+            if prop_schema.get('required', False) and prop_name not in props:
+                errors.append(f"Missing required prop: '{prop_name}'")
+
+        # Validate each provided prop
+        for prop_name, prop_value in props.items():
+            # Skip special props that are always allowed
+            if prop_name in ('id', 'children', 'className', 'style', 'key'):
+                continue
+
+            result = self.registry.validate_prop(component, prop_name, prop_value)
+
+            if not result.get('valid', True):
+                error = result.get('error', f"Invalid prop: {prop_name}")
+                # Distinguish between typos/unknown props and type errors
+                if "Unknown prop" in error:
+                    errors.append(f"❌ {error}")
+                elif "expects one of" in error:
+                    errors.append(f"❌ {error}")
+                elif "expects type" in error:
+                    warnings.append(f"⚠️ {error}")
+                else:
+                    errors.append(f"❌ {error}")
+
+        # Check for props that exist but might have common mistakes
+        self._check_common_mistakes(component, props, warnings)
+
+        return {
+            "valid": len(errors) == 0,
+            "errors": errors,
+            "warnings": warnings,
+            "validated_props": len(props),
+            "component": component,
+            "version": self.registry.loaded_version
+        }
+
+    def _find_similar_component(self, component: str) -> Optional[str]:
+        """
+        Find a similar component name for suggestions.
+
+        Args:
+            component: The (possibly misspelled) component name
+
+        Returns:
+            Similar component name, or None if no close match
+        """
+        if not self.registry:
+            return None
+
+        comp_lower = component.lower()
+        all_components = []
+        for comps in self.registry.categories.values():
+            all_components.extend(comps)
+
+        for comp in all_components:
+            # Exact match after lowercase
+            if comp.lower() == comp_lower:
+                return comp
+            # Check if it's a prefix match
+            if comp.lower().startswith(comp_lower) or comp_lower.startswith(comp.lower()):
+                return comp
+            # Check for common typos
+            if abs(len(comp) - len(component)) <= 2:
+                if comp_lower[:4] == comp.lower()[:4]:
+                    return comp
+
+        return None
+
+    def _check_common_mistakes(
+        self,
+        component: str,
+        props: Dict[str, Any],
+        warnings: List[str]
+    ) -> None:
+        """
+        Check for common prop usage mistakes and add warnings.
+
+        Args:
+            component: Component name
+            props: Props being used
+            warnings: List to append warnings to
+        """
+        # Common mistake: using 'onclick' instead of callback pattern
+        if 'onclick' in [p.lower() for p in props.keys()]:
+            warnings.append(
+                "⚠️ Dash uses callback patterns, not inline event handlers. "
+                "Use 'n_clicks' prop with a callback instead."
+            )
+
+        # Common mistake: using 'class' instead of 'className'
+        if 'class' in props:
+            warnings.append(
+                "⚠️ Use 'className' instead of 'class' for CSS classes."
+            )
+
+        # Button-specific checks
+        if component == 'Button':
+            if 'href' in props and 'component' not in props:
+                warnings.append(
+                    "⚠️ Button with 'href' should also set 'component=\"a\"' for proper anchor behavior."
+                )
+
+        # Input-specific checks
+        if 'Input' in component:
+            if 'value' in props and 'onChange' in [p for p in props.keys()]:
+                warnings.append(
+                    "⚠️ Dash uses 'value' prop with callbacks, not 'onChange'. "
+                    "The value updates automatically through Dash callbacks."
+                )

mcp-servers/viz-platform/mcp_server/layout_tools.py

@@ -0,0 +1,553 @@
+"""
+Layout composition tools for dashboard building.
+
+Provides tools for creating structured layouts with grids, filters, and sections.
+"""
+import logging
+from typing import Dict, List, Optional, Any
+from uuid import uuid4
+
+logger = logging.getLogger(__name__)
+
+
+# Standard responsive breakpoints (Mantine/Bootstrap-aligned)
+DEFAULT_BREAKPOINTS = {
+    "xs": {
+        "min_width": "0px",
+        "max_width": "575px",
+        "cols": 1,
+        "spacing": "xs",
+        "description": "Extra small devices (phones, portrait)"
+    },
+    "sm": {
+        "min_width": "576px",
+        "max_width": "767px",
+        "cols": 2,
+        "spacing": "sm",
+        "description": "Small devices (phones, landscape)"
+    },
+    "md": {
+        "min_width": "768px",
+        "max_width": "991px",
+        "cols": 6,
+        "spacing": "md",
+        "description": "Medium devices (tablets)"
+    },
+    "lg": {
+        "min_width": "992px",
+        "max_width": "1199px",
+        "cols": 12,
+        "spacing": "md",
+        "description": "Large devices (desktops)"
+    },
+    "xl": {
+        "min_width": "1200px",
+        "max_width": None,
+        "cols": 12,
+        "spacing": "lg",
+        "description": "Extra large devices (large desktops)"
+    }
+}
+
+
+# Layout templates
+TEMPLATES = {
+    "dashboard": {
+        "sections": ["header", "filters", "main", "footer"],
+        "default_grid": {"cols": 12, "spacing": "md"},
+        "description": "Standard dashboard with header, filters, main content, and footer"
+    },
+    "report": {
+        "sections": ["title", "summary", "content", "appendix"],
+        "default_grid": {"cols": 1, "spacing": "lg"},
+        "description": "Report layout with title, summary, and content sections"
+    },
+    "form": {
+        "sections": ["header", "fields", "actions"],
+        "default_grid": {"cols": 2, "spacing": "md"},
+        "description": "Form layout with header, fields, and action buttons"
+    },
+    "blank": {
+        "sections": ["main"],
+        "default_grid": {"cols": 12, "spacing": "md"},
+        "description": "Blank canvas for custom layouts"
+    }
+}
+
+
+# Filter type definitions
+FILTER_TYPES = {
+    "dropdown": {
+        "component": "Select",
+        "props": ["label", "data", "placeholder", "clearable", "searchable", "value"]
+    },
+    "multi_select": {
+        "component": "MultiSelect",
+        "props": ["label", "data", "placeholder", "clearable", "searchable", "value"]
+    },
+    "date_range": {
+        "component": "DateRangePicker",
+        "props": ["label", "placeholder", "value", "minDate", "maxDate"]
+    },
+    "date": {
+        "component": "DatePicker",
+        "props": ["label", "placeholder", "value", "minDate", "maxDate"]
+    },
+    "search": {
+        "component": "TextInput",
+        "props": ["label", "placeholder", "value", "icon"]
+    },
+    "checkbox_group": {
+        "component": "CheckboxGroup",
+        "props": ["label", "children", "value"]
+    },
+    "radio_group": {
+        "component": "RadioGroup",
+        "props": ["label", "children", "value"]
+    },
+    "slider": {
+        "component": "Slider",
+        "props": ["label", "min", "max", "step", "value", "marks"]
+    },
+    "range_slider": {
+        "component": "RangeSlider",
+        "props": ["label", "min", "max", "step", "value", "marks"]
+    }
+}
+
+
+class LayoutTools:
+    """
+    Dashboard layout composition tools.
+
+    Creates layouts that map to DMC Grid and AppShell components.
+    """
+
+    def __init__(self):
+        """Initialize layout tools."""
+        self._layouts: Dict[str, Dict[str, Any]] = {}
+
+    async def layout_create(
+        self,
+        name: str,
+        template: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Create a new layout container.
+
+        Args:
+            name: Unique name for the layout
+            template: Optional template (dashboard, report, form, blank)
+
+        Returns:
+            Dict with:
+                - layout_ref: Reference to use in other tools
+                - template: Template used
+                - sections: Available sections
+                - grid: Default grid configuration
+        """
+        # Validate template
+        template = template or "blank"
+        if template not in TEMPLATES:
+            return {
+                "error": f"Invalid template '{template}'. Must be one of: {list(TEMPLATES.keys())}",
+                "layout_ref": None
+            }
+
+        # Check for name collision
+        if name in self._layouts:
+            return {
+                "error": f"Layout '{name}' already exists. Use a different name or modify existing.",
+                "layout_ref": name
+            }
+
+        template_config = TEMPLATES[template]
+
+        # Create layout structure
+        layout = {
+            "id": str(uuid4()),
+            "name": name,
+            "template": template,
+            "sections": {section: {"items": []} for section in template_config["sections"]},
+            "grid": template_config["default_grid"].copy(),
+            "filters": [],
+            "metadata": {
+                "description": template_config["description"]
+            }
+        }
+
+        self._layouts[name] = layout
+
+        return {
+            "layout_ref": name,
+            "template": template,
+            "sections": template_config["sections"],
+            "grid": layout["grid"],
+            "description": template_config["description"]
+        }
+
+    async def layout_add_filter(
+        self,
+        layout_ref: str,
+        filter_type: str,
+        options: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """
+        Add a filter control to a layout.
+
+        Args:
+            layout_ref: Layout name to add filter to
+            filter_type: Type of filter (dropdown, date_range, search, checkbox_group, etc.)
+            options: Filter options (label, data for dropdown, placeholder, position)
+
+        Returns:
+            Dict with:
+                - filter_id: Unique ID for the filter
+                - component: DMC component that will be used
+                - props: Props that were set
+                - position: Where filter was placed
+        """
+        # Validate layout exists
+        if layout_ref not in self._layouts:
+            return {
+                "error": f"Layout '{layout_ref}' not found. Create it first with layout_create.",
+                "filter_id": None
+            }
+
+        # Validate filter type
+        if filter_type not in FILTER_TYPES:
+            return {
+                "error": f"Invalid filter_type '{filter_type}'. Must be one of: {list(FILTER_TYPES.keys())}",
+                "filter_id": None
+            }
+
+        filter_config = FILTER_TYPES[filter_type]
+        layout = self._layouts[layout_ref]
+
+        # Generate filter ID
+        filter_id = f"filter_{filter_type}_{len(layout['filters'])}"
+
+        # Extract relevant props
+        props = {"id": filter_id}
+        for prop in filter_config["props"]:
+            if prop in options:
+                props[prop] = options[prop]
+
+        # Determine position
+        position = options.get("position", "filters")
+        if position not in layout["sections"]:
+            # Default to first available section
+            position = list(layout["sections"].keys())[0]
+
+        # Create filter definition
+        filter_def = {
+            "id": filter_id,
+            "type": filter_type,
+            "component": filter_config["component"],
+            "props": props,
+            "position": position
+        }
+
+        layout["filters"].append(filter_def)
+        layout["sections"][position]["items"].append({
+            "type": "filter",
+            "ref": filter_id
+        })
+
+        return {
+            "filter_id": filter_id,
+            "component": filter_config["component"],
+            "props": props,
+            "position": position,
+            "layout_ref": layout_ref
+        }
+
+    async def layout_set_grid(
+        self,
+        layout_ref: str,
+        grid: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """
+        Configure the grid system for a layout.
+
+        Args:
+            layout_ref: Layout name to configure
+            grid: Grid configuration:
+                - cols: Number of columns (default 12)
+                - spacing: Gap between items (xs, sm, md, lg, xl)
+                - breakpoints: Responsive breakpoints {xs: cols, sm: cols, ...}
+                - gutter: Gutter size
+
+        Returns:
+            Dict with:
+                - grid: Updated grid configuration
+                - layout_ref: Layout reference
+        """
+        # Validate layout exists
+        if layout_ref not in self._layouts:
+            return {
+                "error": f"Layout '{layout_ref}' not found. Create it first with layout_create.",
+                "grid": None
+            }
+
+        layout = self._layouts[layout_ref]
+
+        # Validate spacing if provided
+        valid_spacing = ["xs", "sm", "md", "lg", "xl"]
+        if "spacing" in grid and grid["spacing"] not in valid_spacing:
+            return {
+                "error": f"Invalid spacing '{grid['spacing']}'. Must be one of: {valid_spacing}",
+                "grid": layout["grid"]
+            }
+
+        # Validate cols
+        if "cols" in grid:
+            cols = grid["cols"]
+            if not isinstance(cols, int) or cols < 1 or cols > 24:
+                return {
+                    "error": f"Invalid cols '{cols}'. Must be integer between 1 and 24.",
+                    "grid": layout["grid"]
+                }
+
+        # Update grid configuration
+        layout["grid"].update(grid)
+
+        # Process breakpoints if provided
+        if "breakpoints" in grid:
+            bp = grid["breakpoints"]
+            layout["grid"]["breakpoints"] = bp
+
+        return {
+            "grid": layout["grid"],
+            "layout_ref": layout_ref
+        }
+
+    async def layout_get(self, layout_ref: str) -> Dict[str, Any]:
+        """
+        Get a layout's full configuration.
+
+        Args:
+            layout_ref: Layout name to retrieve
+
+        Returns:
+            Full layout configuration or error
+        """
+        if layout_ref not in self._layouts:
+            return {
+                "error": f"Layout '{layout_ref}' not found.",
+                "layout": None
+            }
+
+        layout = self._layouts[layout_ref]
+
+        return {
+            "layout": layout,
+            "filter_count": len(layout["filters"]),
+            "sections": list(layout["sections"].keys())
+        }
+
+    async def layout_add_section(
+        self,
+        layout_ref: str,
+        section_name: str,
+        position: Optional[int] = None
+    ) -> Dict[str, Any]:
+        """
+        Add a custom section to a layout.
+
+        Args:
+            layout_ref: Layout name
+            section_name: Name for the new section
+            position: Optional position index (appends if not specified)
+
+        Returns:
+            Dict with sections list and the new section name
+        """
+        if layout_ref not in self._layouts:
+            return {
+                "error": f"Layout '{layout_ref}' not found.",
+                "sections": []
+            }
+
+        layout = self._layouts[layout_ref]
+
+        if section_name in layout["sections"]:
+            return {
+                "error": f"Section '{section_name}' already exists.",
+                "sections": list(layout["sections"].keys())
+            }
+
+        # Add new section
+        layout["sections"][section_name] = {"items": []}
+
+        return {
+            "section_name": section_name,
+            "sections": list(layout["sections"].keys()),
+            "layout_ref": layout_ref
+        }
+
+    def get_available_templates(self) -> Dict[str, Any]:
+        """Get list of available layout templates."""
+        return {
+            name: {
+                "sections": config["sections"],
+                "description": config["description"]
+            }
+            for name, config in TEMPLATES.items()
+        }
+
+    def get_available_filter_types(self) -> Dict[str, Any]:
+        """Get list of available filter types."""
+        return {
+            name: {
+                "component": config["component"],
+                "props": config["props"]
+            }
+            for name, config in FILTER_TYPES.items()
+        }
+
+    async def layout_set_breakpoints(
+        self,
+        layout_ref: str,
+        breakpoints: Dict[str, Dict[str, Any]],
+        mobile_first: bool = True
+    ) -> Dict[str, Any]:
+        """
+        Configure responsive breakpoints for a layout.
+
+        Args:
+            layout_ref: Layout name to configure
+            breakpoints: Breakpoint configuration dict:
+                {
+                    "xs": {"cols": 1, "spacing": "xs"},
+                    "sm": {"cols": 2, "spacing": "sm"},
+                    "md": {"cols": 6, "spacing": "md"},
+                    "lg": {"cols": 12, "spacing": "md"},
+                    "xl": {"cols": 12, "spacing": "lg"}
+                }
+            mobile_first: If True, use min-width media queries (default)
+
+        Returns:
+            Dict with:
+                - breakpoints: Complete breakpoint configuration
+                - css_media_queries: Generated CSS media queries
+                - mobile_first: Whether mobile-first approach is used
+        """
+        # Validate layout exists
+        if layout_ref not in self._layouts:
+            return {
+                "error": f"Layout '{layout_ref}' not found. Create it first with layout_create.",
+                "breakpoints": None
+            }
+
+        layout = self._layouts[layout_ref]
+
+        # Validate breakpoint names
+        valid_breakpoints = ["xs", "sm", "md", "lg", "xl"]
+        for bp_name in breakpoints.keys():
+            if bp_name not in valid_breakpoints:
+                return {
+                    "error": f"Invalid breakpoint '{bp_name}'. Must be one of: {valid_breakpoints}",
+                    "breakpoints": layout.get("breakpoints")
+                }
+
+        # Merge with defaults
+        merged_breakpoints = {}
+        for bp_name in valid_breakpoints:
+            default = DEFAULT_BREAKPOINTS[bp_name].copy()
+            if bp_name in breakpoints:
+                default.update(breakpoints[bp_name])
+            merged_breakpoints[bp_name] = default
+
+        # Validate spacing values
+        valid_spacing = ["xs", "sm", "md", "lg", "xl"]
+        for bp_name, bp_config in merged_breakpoints.items():
+            if "spacing" in bp_config and bp_config["spacing"] not in valid_spacing:
+                return {
+                    "error": f"Invalid spacing '{bp_config['spacing']}' for breakpoint '{bp_name}'. Must be one of: {valid_spacing}",
+                    "breakpoints": layout.get("breakpoints")
+                }
+
+        # Validate column counts
+        for bp_name, bp_config in merged_breakpoints.items():
+            if "cols" in bp_config:
+                cols = bp_config["cols"]
+                if not isinstance(cols, int) or cols < 1 or cols > 24:
+                    return {
+                        "error": f"Invalid cols '{cols}' for breakpoint '{bp_name}'. Must be integer between 1 and 24.",
+                        "breakpoints": layout.get("breakpoints")
+                    }
+
+        # Generate CSS media queries
+        css_queries = self._generate_media_queries(merged_breakpoints, mobile_first)
+
+        # Store in layout
+        layout["breakpoints"] = merged_breakpoints
+        layout["mobile_first"] = mobile_first
+        layout["responsive_css"] = css_queries
+
+        return {
+            "layout_ref": layout_ref,
+            "breakpoints": merged_breakpoints,
+            "mobile_first": mobile_first,
+            "css_media_queries": css_queries
+        }
+
+    def _generate_media_queries(
+        self,
+        breakpoints: Dict[str, Dict[str, Any]],
+        mobile_first: bool
+    ) -> List[str]:
+        """Generate CSS media queries for breakpoints."""
+        queries = []
+        bp_order = ["xs", "sm", "md", "lg", "xl"]
+
+        if mobile_first:
+            # Use min-width queries (mobile-first)
+            for bp_name in bp_order[1:]:  # Skip xs (base styles)
+                bp = breakpoints[bp_name]
+                min_width = bp.get("min_width", DEFAULT_BREAKPOINTS[bp_name]["min_width"])
+                if min_width and min_width != "0px":
+                    queries.append(f"@media (min-width: {min_width}) {{ /* {bp_name} styles */ }}")
+        else:
+            # Use max-width queries (desktop-first)
+            for bp_name in reversed(bp_order[:-1]):  # Skip xl (base styles)
+                bp = breakpoints[bp_name]
+                max_width = bp.get("max_width", DEFAULT_BREAKPOINTS[bp_name]["max_width"])
+                if max_width:
+                    queries.append(f"@media (max-width: {max_width}) {{ /* {bp_name} styles */ }}")
+
+        return queries
+
+    async def layout_get_breakpoints(self, layout_ref: str) -> Dict[str, Any]:
+        """
+        Get the breakpoint configuration for a layout.
+
+        Args:
+            layout_ref: Layout name
+
+        Returns:
+            Dict with breakpoint configuration
+        """
+        if layout_ref not in self._layouts:
+            return {
+                "error": f"Layout '{layout_ref}' not found.",
+                "breakpoints": None
+            }
+
+        layout = self._layouts[layout_ref]
+
+        return {
+            "layout_ref": layout_ref,
+            "breakpoints": layout.get("breakpoints", DEFAULT_BREAKPOINTS.copy()),
+            "mobile_first": layout.get("mobile_first", True),
+            "css_media_queries": layout.get("responsive_css", [])
+        }
+
+    def get_default_breakpoints(self) -> Dict[str, Any]:
+        """Get the default breakpoint configuration."""
+        return {
+            "breakpoints": DEFAULT_BREAKPOINTS.copy(),
+            "description": "Standard responsive breakpoints aligned with Mantine/Bootstrap",
+            "mobile_first": True
+        }

mcp-servers/viz-platform/mcp_server/page_tools.py

@@ -0,0 +1,366 @@
+"""
+Multi-page app tools for viz-platform.
+
+Provides tools for building complete Dash applications with routing and navigation.
+"""
+import logging
+from typing import Dict, List, Optional, Any
+from uuid import uuid4
+
+logger = logging.getLogger(__name__)
+
+
+# Navigation position options
+NAV_POSITIONS = ["top", "left", "right"]
+
+# Auth types supported
+AUTH_TYPES = ["none", "basic", "oauth", "custom"]
+
+
+class PageTools:
+    """
+    Multi-page Dash application tools.
+
+    Creates page definitions, navigation, and auth configuration.
+    """
+
+    def __init__(self):
+        """Initialize page tools."""
+        self._pages: Dict[str, Dict[str, Any]] = {}
+        self._navbars: Dict[str, Dict[str, Any]] = {}
+        self._app_config: Dict[str, Any] = {
+            "title": "Dash App",
+            "suppress_callback_exceptions": True
+        }
+
+    async def page_create(
+        self,
+        name: str,
+        path: str,
+        layout_ref: Optional[str] = None,
+        title: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Create a new page definition.
+
+        Args:
+            name: Unique page name (used as identifier)
+            path: URL path for the page (e.g., "/", "/settings")
+            layout_ref: Optional layout reference to use for the page
+            title: Optional page title (defaults to name)
+
+        Returns:
+            Dict with:
+                - page_ref: Reference to use in other tools
+                - path: URL path
+                - registered: Whether page was registered
+        """
+        # Validate path format
+        if not path.startswith('/'):
+            return {
+                "error": f"Path must start with '/'. Got: {path}",
+                "page_ref": None
+            }
+
+        # Check for name collision
+        if name in self._pages:
+            return {
+                "error": f"Page '{name}' already exists. Use a different name.",
+                "page_ref": name
+            }
+
+        # Check for path collision
+        for page_name, page_data in self._pages.items():
+            if page_data['path'] == path:
+                return {
+                    "error": f"Path '{path}' already used by page '{page_name}'.",
+                    "page_ref": None
+                }
+
+        # Create page definition
+        page = {
+            "id": str(uuid4()),
+            "name": name,
+            "path": path,
+            "title": title or name,
+            "layout_ref": layout_ref,
+            "auth": None,
+            "metadata": {}
+        }
+
+        self._pages[name] = page
+
+        return {
+            "page_ref": name,
+            "path": path,
+            "title": page["title"],
+            "layout_ref": layout_ref,
+            "registered": True
+        }
+
+    async def page_add_navbar(
+        self,
+        pages: List[str],
+        options: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """
+        Generate a navigation component linking pages.
+
+        Args:
+            pages: List of page names to include in navigation
+            options: Navigation options:
+                - position: "top", "left", or "right"
+                - style: Style variant
+                - brand: Brand/logo text or config
+                - collapsible: Whether to collapse on mobile
+
+        Returns:
+            Dict with:
+                - navbar_id: Navigation ID
+                - pages: List of page links generated
+                - component: DMC component structure
+        """
+        options = options or {}
+
+        # Validate pages exist
+        missing_pages = [p for p in pages if p not in self._pages]
+        if missing_pages:
+            return {
+                "error": f"Pages not found: {missing_pages}. Create them first.",
+                "navbar_id": None
+            }
+
+        # Validate position
+        position = options.get("position", "top")
+        if position not in NAV_POSITIONS:
+            return {
+                "error": f"Invalid position '{position}'. Must be one of: {NAV_POSITIONS}",
+                "navbar_id": None
+            }
+
+        # Generate navbar ID
+        navbar_id = f"navbar_{len(self._navbars)}"
+
+        # Build page links
+        page_links = []
+        for page_name in pages:
+            page = self._pages[page_name]
+            page_links.append({
+                "label": page["title"],
+                "href": page["path"],
+                "page_ref": page_name
+            })
+
+        # Build DMC component structure
+        if position == "top":
+            component = self._build_top_navbar(page_links, options)
+        else:
+            component = self._build_side_navbar(page_links, options, position)
+
+        # Store navbar config
+        self._navbars[navbar_id] = {
+            "id": navbar_id,
+            "position": position,
+            "pages": pages,
+            "options": options,
+            "component": component
+        }
+
+        return {
+            "navbar_id": navbar_id,
+            "position": position,
+            "pages": page_links,
+            "component": component
+        }
+
+    async def page_set_auth(
+        self,
+        page_ref: str,
+        auth_config: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """
+        Configure authentication for a page.
+
+        Args:
+            page_ref: Page name to configure
+            auth_config: Authentication configuration:
+                - type: "none", "basic", "oauth", "custom"
+                - required: Whether auth is required (default True)
+                - roles: List of required roles (optional)
+                - redirect: Redirect path for unauthenticated users
+
+        Returns:
+            Dict with:
+                - page_ref: Page reference
+                - auth_type: Type of auth configured
+                - protected: Whether page is protected
+        """
+        # Validate page exists
+        if page_ref not in self._pages:
+            available = list(self._pages.keys())
+            return {
+                "error": f"Page '{page_ref}' not found. Available: {available}",
+                "page_ref": page_ref
+            }
+
+        # Validate auth type
+        auth_type = auth_config.get("type", "basic")
+        if auth_type not in AUTH_TYPES:
+            return {
+                "error": f"Invalid auth type '{auth_type}'. Must be one of: {AUTH_TYPES}",
+                "page_ref": page_ref
+            }
+
+        # Build auth config
+        auth = {
+            "type": auth_type,
+            "required": auth_config.get("required", True),
+            "roles": auth_config.get("roles", []),
+            "redirect": auth_config.get("redirect", "/login")
+        }
+
+        # Handle OAuth-specific config
+        if auth_type == "oauth":
+            auth["provider"] = auth_config.get("provider", "generic")
+            auth["scopes"] = auth_config.get("scopes", [])
+
+        # Update page
+        self._pages[page_ref]["auth"] = auth
+
+        return {
+            "page_ref": page_ref,
+            "auth_type": auth_type,
+            "protected": auth["required"],
+            "roles": auth["roles"],
+            "redirect": auth["redirect"]
+        }
+
+    async def page_list(self) -> Dict[str, Any]:
+        """
+        List all registered pages.
+
+        Returns:
+            Dict with pages and their configurations
+        """
+        pages_info = {}
+        for name, page in self._pages.items():
+            pages_info[name] = {
+                "path": page["path"],
+                "title": page["title"],
+                "layout_ref": page["layout_ref"],
+                "protected": page["auth"] is not None and page["auth"].get("required", False)
+            }
+
+        return {
+            "pages": pages_info,
+            "count": len(pages_info),
+            "navbars": list(self._navbars.keys())
+        }
+
+    async def page_get_app_config(self) -> Dict[str, Any]:
+        """
+        Get the complete app configuration for Dash.
+
+        Returns:
+            Dict with app config including pages, navbars, and settings
+        """
+        # Build pages config
+        pages_config = []
+        for name, page in self._pages.items():
+            pages_config.append({
+                "name": name,
+                "path": page["path"],
+                "title": page["title"],
+                "layout_ref": page["layout_ref"]
+            })
+
+        # Build routing config
+        routes = {page["path"]: name for name, page in self._pages.items()}
+
+        return {
+            "app": self._app_config,
+            "pages": pages_config,
+            "routes": routes,
+            "navbars": list(self._navbars.values()),
+            "page_count": len(self._pages)
+        }
+
+    def _build_top_navbar(
+        self,
+        page_links: List[Dict[str, str]],
+        options: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """Build a top navigation bar component."""
+        brand = options.get("brand", "App")
+
+        # Build nav links
+        nav_items = []
+        for link in page_links:
+            nav_items.append({
+                "component": "NavLink",
+                "props": {
+                    "label": link["label"],
+                    "href": link["href"]
+                }
+            })
+
+        return {
+            "component": "AppShell.Header",
+            "children": [
+                {
+                    "component": "Group",
+                    "props": {"justify": "space-between", "h": "100%", "px": "md"},
+                    "children": [
+                        {
+                            "component": "Text",
+                            "props": {"size": "lg", "fw": 700},
+                            "children": brand
+                        },
+                        {
+                            "component": "Group",
+                            "props": {"gap": "sm"},
+                            "children": nav_items
+                        }
+                    ]
+                }
+            ]
+        }
+
+    def _build_side_navbar(
+        self,
+        page_links: List[Dict[str, str]],
+        options: Dict[str, Any],
+        position: str
+    ) -> Dict[str, Any]:
+        """Build a side navigation bar component."""
+        brand = options.get("brand", "App")
+
+        # Build nav links
+        nav_items = []
+        for link in page_links:
+            nav_items.append({
+                "component": "NavLink",
+                "props": {
+                    "label": link["label"],
+                    "href": link["href"]
+                }
+            })
+
+        navbar_component = "AppShell.Navbar" if position == "left" else "AppShell.Aside"
+
+        return {
+            "component": navbar_component,
+            "props": {"p": "md"},
+            "children": [
+                {
+                    "component": "Text",
+                    "props": {"size": "lg", "fw": 700, "mb": "md"},
+                    "children": brand
+                },
+                {
+                    "component": "Stack",
+                    "props": {"gap": "xs"},
+                    "children": nav_items
+                }
+            ]
+        }

mcp-servers/viz-platform/mcp_server/server.py

@@ -0,0 +1,928 @@
+"""
+MCP Server entry point for viz-platform integration.
+
+Provides Dash Mantine Components validation, charting, layout, theming, and page tools
+to Claude Code via JSON-RPC 2.0 over stdio.
+"""
+import asyncio
+import logging
+import json
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import Tool, TextContent
+
+from .config import VizPlatformConfig
+from .dmc_tools import DMCTools
+from .chart_tools import ChartTools
+from .layout_tools import LayoutTools
+from .theme_tools import ThemeTools
+from .page_tools import PageTools
+from .accessibility_tools import AccessibilityTools
+
+# Suppress noisy MCP validation warnings on stderr
+logging.basicConfig(level=logging.INFO)
+logging.getLogger("root").setLevel(logging.ERROR)
+logging.getLogger("mcp").setLevel(logging.ERROR)
+logger = logging.getLogger(__name__)
+
+
+class VizPlatformMCPServer:
+    """MCP Server for visualization platform integration"""
+
+    def __init__(self):
+        self.server = Server("viz-platform-mcp")
+        self.config = None
+        self.dmc_tools = DMCTools()
+        self.chart_tools = ChartTools()
+        self.layout_tools = LayoutTools()
+        self.theme_tools = ThemeTools()
+        self.page_tools = PageTools()
+        self.accessibility_tools = AccessibilityTools(theme_store=self.theme_tools.store)
+
+    async def initialize(self):
+        """Initialize server and load configuration."""
+        try:
+            config_loader = VizPlatformConfig()
+            self.config = config_loader.load()
+
+            # Initialize DMC tools with detected version
+            dmc_version = self.config.get('dmc_version')
+            self.dmc_tools.initialize(dmc_version)
+
+            # Log available capabilities
+            caps = []
+            if self.config.get('dmc_available'):
+                caps.append(f"DMC {dmc_version}")
+                if self.dmc_tools._initialized:
+                    caps.append(f"Registry loaded ({self.dmc_tools.registry.loaded_version})")
+            else:
+                caps.append("DMC (not installed)")
+
+            logger.info(f"viz-platform MCP Server initialized with: {', '.join(caps)}")
+
+        except Exception as e:
+            logger.error(f"Failed to initialize: {e}")
+            raise
+
+    def setup_tools(self):
+        """Register all available tools with the MCP server"""
+
+        @self.server.list_tools()
+        async def list_tools() -> list[Tool]:
+            """Return list of available tools"""
+            tools = []
+
+            # DMC validation tools (Issue #172)
+            tools.append(Tool(
+                name="list_components",
+                description=(
+                    "List available Dash Mantine Components. "
+                    "Returns components grouped by category with version info. "
+                    "Use this to discover what components are available before building UI."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "category": {
+                            "type": "string",
+                            "description": (
+                                "Optional category filter. Available categories: "
+                                "buttons, inputs, navigation, feedback, overlays, "
+                                "typography, layout, data_display, charts, dates"
+                            )
+                        }
+                    },
+                    "required": []
+                }
+            ))
+
+            tools.append(Tool(
+                name="get_component_props",
+                description=(
+                    "Get the props schema for a specific DMC component. "
+                    "Returns all available props with types, defaults, and allowed values. "
+                    "ALWAYS use this before creating a component to ensure valid props."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "component": {
+                            "type": "string",
+                            "description": "Component name (e.g., 'Button', 'TextInput', 'Select')"
+                        }
+                    },
+                    "required": ["component"]
+                }
+            ))
+
+            tools.append(Tool(
+                name="validate_component",
+                description=(
+                    "Validate component props before use. "
+                    "Checks for invalid props, type mismatches, and common mistakes. "
+                    "Returns errors and warnings with suggestions for fixes."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "component": {
+                            "type": "string",
+                            "description": "Component name to validate"
+                        },
+                        "props": {
+                            "type": "object",
+                            "description": "Props object to validate"
+                        }
+                    },
+                    "required": ["component", "props"]
+                }
+            ))
+
+            # Chart tools (Issue #173)
+            tools.append(Tool(
+                name="chart_create",
+                description=(
+                    "Create a Plotly chart for data visualization. "
+                    "Supports line, bar, scatter, pie, heatmap, histogram, and area charts. "
+                    "Automatically applies theme colors when a theme is active."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "chart_type": {
+                            "type": "string",
+                            "enum": ["line", "bar", "scatter", "pie", "heatmap", "histogram", "area"],
+                            "description": "Type of chart to create"
+                        },
+                        "data": {
+                            "type": "object",
+                            "description": (
+                                "Data for the chart. For most charts: {x: [], y: []}. "
+                                "For pie: {labels: [], values: []}. "
+                                "For heatmap: {x: [], y: [], z: [[]]}"
+                            )
+                        },
+                        "options": {
+                            "type": "object",
+                            "description": (
+                                "Optional settings: title, x_label, y_label, color, "
+                                "showlegend, height, width, horizontal (for bar)"
+                            )
+                        }
+                    },
+                    "required": ["chart_type", "data"]
+                }
+            ))
+
+            tools.append(Tool(
+                name="chart_configure_interaction",
+                description=(
+                    "Configure interactions on an existing chart. "
+                    "Add hover templates, enable click data capture, selection modes, "
+                    "and zoom behavior for Dash callback integration."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "figure": {
+                            "type": "object",
+                            "description": "Plotly figure JSON to modify"
+                        },
+                        "interactions": {
+                            "type": "object",
+                            "description": (
+                                "Interaction config: hover_template (string), "
+                                "click_data (bool), selection ('box'|'lasso'), zoom (bool)"
+                            )
+                        }
+                    },
+                    "required": ["figure", "interactions"]
+                }
+            ))
+
+            # Chart export tool (Issue #247)
+            tools.append(Tool(
+                name="chart_export",
+                description=(
+                    "Export a Plotly chart to static image format (PNG, SVG, PDF). "
+                    "Requires kaleido package. Returns base64 image data or saves to file."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "figure": {
+                            "type": "object",
+                            "description": "Plotly figure JSON to export"
+                        },
+                        "format": {
+                            "type": "string",
+                            "enum": ["png", "svg", "pdf"],
+                            "description": "Output format (default: png)"
+                        },
+                        "width": {
+                            "type": "integer",
+                            "description": "Image width in pixels (default: 1200)"
+                        },
+                        "height": {
+                            "type": "integer",
+                            "description": "Image height in pixels (default: 800)"
+                        },
+                        "scale": {
+                            "type": "number",
+                            "description": "Resolution scale factor (default: 2 for retina)"
+                        },
+                        "output_path": {
+                            "type": "string",
+                            "description": "Optional file path to save image"
+                        }
+                    },
+                    "required": ["figure"]
+                }
+            ))
+
+            # Layout tools (Issue #174)
+            tools.append(Tool(
+                name="layout_create",
+                description=(
+                    "Create a new dashboard layout container. "
+                    "Templates available: dashboard, report, form, blank. "
+                    "Returns layout reference for use with other layout tools."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "name": {
+                            "type": "string",
+                            "description": "Unique name for the layout"
+                        },
+                        "template": {
+                            "type": "string",
+                            "enum": ["dashboard", "report", "form", "blank"],
+                            "description": "Layout template to use (default: blank)"
+                        }
+                    },
+                    "required": ["name"]
+                }
+            ))
+
+            tools.append(Tool(
+                name="layout_add_filter",
+                description=(
+                    "Add a filter control to a layout. "
+                    "Filter types: dropdown, multi_select, date_range, date, search, "
+                    "checkbox_group, radio_group, slider, range_slider."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "layout_ref": {
+                            "type": "string",
+                            "description": "Layout name to add filter to"
+                        },
+                        "filter_type": {
+                            "type": "string",
+                            "enum": ["dropdown", "multi_select", "date_range", "date",
+                                    "search", "checkbox_group", "radio_group", "slider", "range_slider"],
+                            "description": "Type of filter control"
+                        },
+                        "options": {
+                            "type": "object",
+                            "description": (
+                                "Filter options: label, data (for dropdown), placeholder, "
+                                "position (section name), value, etc."
+                            )
+                        }
+                    },
+                    "required": ["layout_ref", "filter_type", "options"]
+                }
+            ))
+
+            tools.append(Tool(
+                name="layout_set_grid",
+                description=(
+                    "Configure the grid system for a layout. "
+                    "Uses DMC Grid component patterns with 12 or 24 column system."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "layout_ref": {
+                            "type": "string",
+                            "description": "Layout name to configure"
+                        },
+                        "grid": {
+                            "type": "object",
+                            "description": (
+                                "Grid config: cols (1-24), spacing (xs|sm|md|lg|xl), "
+                                "breakpoints ({xs: cols, sm: cols, ...}), gutter"
+                            )
+                        }
+                    },
+                    "required": ["layout_ref", "grid"]
+                }
+            ))
+
+            # Responsive breakpoints tool (Issue #249)
+            tools.append(Tool(
+                name="layout_set_breakpoints",
+                description=(
+                    "Configure responsive breakpoints for a layout. "
+                    "Supports xs, sm, md, lg, xl breakpoints with mobile-first approach. "
+                    "Each breakpoint can define cols, spacing, and other grid properties."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "layout_ref": {
+                            "type": "string",
+                            "description": "Layout name to configure"
+                        },
+                        "breakpoints": {
+                            "type": "object",
+                            "description": (
+                                "Breakpoint config: {xs: {cols, spacing}, sm: {...}, md: {...}, lg: {...}, xl: {...}}"
+                            )
+                        },
+                        "mobile_first": {
+                            "type": "boolean",
+                            "description": "Use mobile-first (min-width) media queries (default: true)"
+                        }
+                    },
+                    "required": ["layout_ref", "breakpoints"]
+                }
+            ))
+
+            # Theme tools (Issue #175)
+            tools.append(Tool(
+                name="theme_create",
+                description=(
+                    "Create a new design theme with tokens. "
+                    "Tokens include colors, spacing, typography, radii. "
+                    "Missing tokens are filled from defaults."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "name": {
+                            "type": "string",
+                            "description": "Unique theme name"
+                        },
+                        "tokens": {
+                            "type": "object",
+                            "description": (
+                                "Design tokens: colors (primary, background, text), "
+                                "spacing (xs-xl), typography (fontFamily, fontSize), radii (sm-xl)"
+                            )
+                        }
+                    },
+                    "required": ["name", "tokens"]
+                }
+            ))
+
+            tools.append(Tool(
+                name="theme_extend",
+                description=(
+                    "Create a new theme by extending an existing one. "
+                    "Only specify the tokens you want to override."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "base_theme": {
+                            "type": "string",
+                            "description": "Theme to extend (e.g., 'default')"
+                        },
+                        "overrides": {
+                            "type": "object",
+                            "description": "Token overrides to apply"
+                        },
+                        "new_name": {
+                            "type": "string",
+                            "description": "Name for the new theme (optional)"
+                        }
+                    },
+                    "required": ["base_theme", "overrides"]
+                }
+            ))
+
+            tools.append(Tool(
+                name="theme_validate",
+                description=(
+                    "Validate a theme for completeness. "
+                    "Checks for required tokens and common issues."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "theme_name": {
+                            "type": "string",
+                            "description": "Theme to validate"
+                        }
+                    },
+                    "required": ["theme_name"]
+                }
+            ))
+
+            tools.append(Tool(
+                name="theme_export_css",
+                description=(
+                    "Export a theme as CSS custom properties. "
+                    "Generates :root CSS variables for all tokens."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "theme_name": {
+                            "type": "string",
+                            "description": "Theme to export"
+                        }
+                    },
+                    "required": ["theme_name"]
+                }
+            ))
+
+            # Page tools (Issue #176)
+            tools.append(Tool(
+                name="page_create",
+                description=(
+                    "Create a new page for a multi-page Dash application. "
+                    "Defines page routing and can link to a layout."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "name": {
+                            "type": "string",
+                            "description": "Unique page name (identifier)"
+                        },
+                        "path": {
+                            "type": "string",
+                            "description": "URL path (e.g., '/', '/settings')"
+                        },
+                        "layout_ref": {
+                            "type": "string",
+                            "description": "Optional layout reference to use"
+                        },
+                        "title": {
+                            "type": "string",
+                            "description": "Page title (defaults to name)"
+                        }
+                    },
+                    "required": ["name", "path"]
+                }
+            ))
+
+            tools.append(Tool(
+                name="page_add_navbar",
+                description=(
+                    "Generate navigation component linking pages. "
+                    "Creates top or side navigation with DMC components."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "pages": {
+                            "type": "array",
+                            "items": {"type": "string"},
+                            "description": "List of page names to include"
+                        },
+                        "options": {
+                            "type": "object",
+                            "description": (
+                                "Navigation options: position (top|left|right), "
+                                "brand (app name), collapsible (bool)"
+                            )
+                        }
+                    },
+                    "required": ["pages"]
+                }
+            ))
+
+            tools.append(Tool(
+                name="page_set_auth",
+                description=(
+                    "Configure authentication for a page. "
+                    "Sets auth requirements, roles, and redirect behavior."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "page_ref": {
+                            "type": "string",
+                            "description": "Page name to configure"
+                        },
+                        "auth_config": {
+                            "type": "object",
+                            "description": (
+                                "Auth config: type (none|basic|oauth|custom), "
+                                "required (bool), roles (array), redirect (path)"
+                            )
+                        }
+                    },
+                    "required": ["page_ref", "auth_config"]
+                }
+            ))
+
+            # Accessibility tools (Issue #248)
+            tools.append(Tool(
+                name="accessibility_validate_colors",
+                description=(
+                    "Validate colors for color blind accessibility. "
+                    "Checks contrast ratios for deuteranopia, protanopia, tritanopia. "
+                    "Returns issues, simulations, and accessible palette suggestions."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "colors": {
+                            "type": "array",
+                            "items": {"type": "string"},
+                            "description": "List of hex colors to validate (e.g., ['#228be6', '#40c057'])"
+                        },
+                        "check_types": {
+                            "type": "array",
+                            "items": {"type": "string"},
+                            "description": "Color blindness types to check: deuteranopia, protanopia, tritanopia (default: all)"
+                        },
+                        "min_contrast_ratio": {
+                            "type": "number",
+                            "description": "Minimum WCAG contrast ratio (default: 4.5 for AA)"
+                        }
+                    },
+                    "required": ["colors"]
+                }
+            ))
+
+            tools.append(Tool(
+                name="accessibility_validate_theme",
+                description=(
+                    "Validate a theme's colors for accessibility. "
+                    "Extracts all colors from theme tokens and checks for color blind safety."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "theme_name": {
+                            "type": "string",
+                            "description": "Theme name to validate"
+                        }
+                    },
+                    "required": ["theme_name"]
+                }
+            ))
+
+            tools.append(Tool(
+                name="accessibility_suggest_alternative",
+                description=(
+                    "Suggest accessible alternative colors for a given color. "
+                    "Provides alternatives optimized for specific color blindness types."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "color": {
+                            "type": "string",
+                            "description": "Hex color to find alternatives for"
+                        },
+                        "deficiency_type": {
+                            "type": "string",
+                            "enum": ["deuteranopia", "protanopia", "tritanopia"],
+                            "description": "Color blindness type to optimize for"
+                        }
+                    },
+                    "required": ["color", "deficiency_type"]
+                }
+            ))
+
+            return tools
+
+        @self.server.call_tool()
+        async def call_tool(name: str, arguments: dict) -> list[TextContent]:
+            """Handle tool invocation."""
+            try:
+                # DMC validation tools
+                if name == "list_components":
+                    result = await self.dmc_tools.list_components(
+                        category=arguments.get('category')
+                    )
+                    return [TextContent(
+                        type="text",
+                        text=json.dumps(result, indent=2)
+                    )]
+
+                elif name == "get_component_props":
+                    component = arguments.get('component')
+                    if not component:
+                        return [TextContent(
+                            type="text",
+                            text=json.dumps({"error": "component is required"}, indent=2)
+                        )]
+                    result = await self.dmc_tools.get_component_props(component)
+                    return [TextContent(
+                        type="text",
+                        text=json.dumps(result, indent=2)
+                    )]
+
+                elif name == "validate_component":
+                    component = arguments.get('component')
+                    props = arguments.get('props', {})
+                    if not component:
+                        return [TextContent(
+                            type="text",
+                            text=json.dumps({"error": "component is required"}, indent=2)
+                        )]
+                    result = await self.dmc_tools.validate_component(component, props)
+                    return [TextContent(
+                        type="text",
+                        text=json.dumps(result, indent=2)
+                    )]
+
+                # Chart tools
+                elif name == "chart_create":
+                    chart_type = arguments.get('chart_type')
+                    data = arguments.get('data', {})
+                    options = arguments.get('options', {})
+                    if not chart_type:
+                        return [TextContent(
+                            type="text",
+                            text=json.dumps({"error": "chart_type is required"}, indent=2)
+                        )]
+                    result = await self.chart_tools.chart_create(chart_type, data, options)
+                    return [TextContent(
+                        type="text",
+                        text=json.dumps(result, indent=2)
+                    )]
+
+                elif name == "chart_configure_interaction":
+                    figure = arguments.get('figure')
+                    interactions = arguments.get('interactions', {})
+                    if not figure:
+                        return [TextContent(
+                            type="text",
+                            text=json.dumps({"error": "figure is required"}, indent=2)
+                        )]
+                    result = await self.chart_tools.chart_configure_interaction(figure, interactions)
+                    return [TextContent(
+                        type="text",
+                        text=json.dumps(result, indent=2)
+                    )]
+
+                elif name == "chart_export":
+                    figure = arguments.get('figure')
+                    if not figure:
+                        return [TextContent(
+                            type="text",
+                            text=json.dumps({"error": "figure is required"}, indent=2)
+                        )]
+                    result = await self.chart_tools.chart_export(
+                        figure=figure,
+                        format=arguments.get('format', 'png'),
+                        width=arguments.get('width'),
+                        height=arguments.get('height'),
+                        scale=arguments.get('scale', 2.0),
+                        output_path=arguments.get('output_path')
+                    )
+                    return [TextContent(
+                        type="text",
+                        text=json.dumps(result, indent=2)
+                    )]
+
+                # Layout tools
+                elif name == "layout_create":
+                    layout_name = arguments.get('name')
+                    template = arguments.get('template')
+                    if not layout_name:
+                        return [TextContent(
+                            type="text",
+                            text=json.dumps({"error": "name is required"}, indent=2)
+                        )]
+                    result = await self.layout_tools.layout_create(layout_name, template)
+                    return [TextContent(
+                        type="text",
+                        text=json.dumps(result, indent=2)
+                    )]
+
+                elif name == "layout_add_filter":
+                    layout_ref = arguments.get('layout_ref')
+                    filter_type = arguments.get('filter_type')
+                    options = arguments.get('options', {})
+                    if not layout_ref or not filter_type:
+                        return [TextContent(
+                            type="text",
+                            text=json.dumps({"error": "layout_ref and filter_type are required"}, indent=2)
+                        )]
+                    result = await self.layout_tools.layout_add_filter(layout_ref, filter_type, options)
+                    return [TextContent(
+                        type="text",
+                        text=json.dumps(result, indent=2)
+                    )]
+
+                elif name == "layout_set_grid":
+                    layout_ref = arguments.get('layout_ref')
+                    grid = arguments.get('grid', {})
+                    if not layout_ref:
+                        return [TextContent(
+                            type="text",
+                            text=json.dumps({"error": "layout_ref is required"}, indent=2)
+                        )]
+                    result = await self.layout_tools.layout_set_grid(layout_ref, grid)
+                    return [TextContent(
+                        type="text",
+                        text=json.dumps(result, indent=2)
+                    )]
+
+                elif name == "layout_set_breakpoints":
+                    layout_ref = arguments.get('layout_ref')
+                    breakpoints = arguments.get('breakpoints', {})
+                    mobile_first = arguments.get('mobile_first', True)
+                    if not layout_ref:
+                        return [TextContent(
+                            type="text",
+                            text=json.dumps({"error": "layout_ref is required"}, indent=2)
+                        )]
+                    result = await self.layout_tools.layout_set_breakpoints(
+                        layout_ref, breakpoints, mobile_first
+                    )
+                    return [TextContent(
+                        type="text",
+                        text=json.dumps(result, indent=2)
+                    )]
+
+                # Theme tools
+                elif name == "theme_create":
+                    theme_name = arguments.get('name')
+                    tokens = arguments.get('tokens', {})
+                    if not theme_name:
+                        return [TextContent(
+                            type="text",
+                            text=json.dumps({"error": "name is required"}, indent=2)
+                        )]
+                    result = await self.theme_tools.theme_create(theme_name, tokens)
+                    return [TextContent(
+                        type="text",
+                        text=json.dumps(result, indent=2)
+                    )]
+
+                elif name == "theme_extend":
+                    base_theme = arguments.get('base_theme')
+                    overrides = arguments.get('overrides', {})
+                    new_name = arguments.get('new_name')
+                    if not base_theme:
+                        return [TextContent(
+                            type="text",
+                            text=json.dumps({"error": "base_theme is required"}, indent=2)
+                        )]
+                    result = await self.theme_tools.theme_extend(base_theme, overrides, new_name)
+                    return [TextContent(
+                        type="text",
+                        text=json.dumps(result, indent=2)
+                    )]
+
+                elif name == "theme_validate":
+                    theme_name = arguments.get('theme_name')
+                    if not theme_name:
+                        return [TextContent(
+                            type="text",
+                            text=json.dumps({"error": "theme_name is required"}, indent=2)
+                        )]
+                    result = await self.theme_tools.theme_validate(theme_name)
+                    return [TextContent(
+                        type="text",
+                        text=json.dumps(result, indent=2)
+                    )]
+
+                elif name == "theme_export_css":
+                    theme_name = arguments.get('theme_name')
+                    if not theme_name:
+                        return [TextContent(
+                            type="text",
+                            text=json.dumps({"error": "theme_name is required"}, indent=2)
+                        )]
+                    result = await self.theme_tools.theme_export_css(theme_name)
+                    return [TextContent(
+                        type="text",
+                        text=json.dumps(result, indent=2)
+                    )]
+
+                # Page tools
+                elif name == "page_create":
+                    page_name = arguments.get('name')
+                    path = arguments.get('path')
+                    layout_ref = arguments.get('layout_ref')
+                    title = arguments.get('title')
+                    if not page_name or not path:
+                        return [TextContent(
+                            type="text",
+                            text=json.dumps({"error": "name and path are required"}, indent=2)
+                        )]
+                    result = await self.page_tools.page_create(page_name, path, layout_ref, title)
+                    return [TextContent(
+                        type="text",
+                        text=json.dumps(result, indent=2)
+                    )]
+
+                elif name == "page_add_navbar":
+                    pages = arguments.get('pages', [])
+                    options = arguments.get('options', {})
+                    if not pages:
+                        return [TextContent(
+                            type="text",
+                            text=json.dumps({"error": "pages list is required"}, indent=2)
+                        )]
+                    result = await self.page_tools.page_add_navbar(pages, options)
+                    return [TextContent(
+                        type="text",
+                        text=json.dumps(result, indent=2)
+                    )]
+
+                elif name == "page_set_auth":
+                    page_ref = arguments.get('page_ref')
+                    auth_config = arguments.get('auth_config', {})
+                    if not page_ref:
+                        return [TextContent(
+                            type="text",
+                            text=json.dumps({"error": "page_ref is required"}, indent=2)
+                        )]
+                    result = await self.page_tools.page_set_auth(page_ref, auth_config)
+                    return [TextContent(
+                        type="text",
+                        text=json.dumps(result, indent=2)
+                    )]
+
+                # Accessibility tools
+                elif name == "accessibility_validate_colors":
+                    colors = arguments.get('colors')
+                    if not colors:
+                        return [TextContent(
+                            type="text",
+                            text=json.dumps({"error": "colors list is required"}, indent=2)
+                        )]
+                    result = await self.accessibility_tools.accessibility_validate_colors(
+                        colors=colors,
+                        check_types=arguments.get('check_types'),
+                        min_contrast_ratio=arguments.get('min_contrast_ratio', 4.5)
+                    )
+                    return [TextContent(
+                        type="text",
+                        text=json.dumps(result, indent=2)
+                    )]
+
+                elif name == "accessibility_validate_theme":
+                    theme_name = arguments.get('theme_name')
+                    if not theme_name:
+                        return [TextContent(
+                            type="text",
+                            text=json.dumps({"error": "theme_name is required"}, indent=2)
+                        )]
+                    result = await self.accessibility_tools.accessibility_validate_theme(theme_name)
+                    return [TextContent(
+                        type="text",
+                        text=json.dumps(result, indent=2)
+                    )]
+
+                elif name == "accessibility_suggest_alternative":
+                    color = arguments.get('color')
+                    deficiency_type = arguments.get('deficiency_type')
+                    if not color or not deficiency_type:
+                        return [TextContent(
+                            type="text",
+                            text=json.dumps({"error": "color and deficiency_type are required"}, indent=2)
+                        )]
+                    result = await self.accessibility_tools.accessibility_suggest_alternative(
+                        color, deficiency_type
+                    )
+                    return [TextContent(
+                        type="text",
+                        text=json.dumps(result, indent=2)
+                    )]
+
+                raise ValueError(f"Unknown tool: {name}")
+
+            except Exception as e:
+                logger.error(f"Tool {name} failed: {e}")
+                return [TextContent(
+                    type="text",
+                    text=json.dumps({"error": str(e)}, indent=2)
+                )]
+
+    async def run(self):
+        """Run the MCP server"""
+        await self.initialize()
+        self.setup_tools()
+
+        async with stdio_server() as (read_stream, write_stream):
+            await self.server.run(
+                read_stream,
+                write_stream,
+                self.server.create_initialization_options()
+            )
+
+
+async def main():
+    """Main entry point"""
+    server = VizPlatformMCPServer()
+    await server.run()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

mcp-servers/viz-platform/mcp_server/theme_store.py

@@ -0,0 +1,259 @@
+"""
+Theme storage and persistence for viz-platform.
+
+Handles saving/loading themes from user and project locations.
+"""
+import json
+import logging
+from pathlib import Path
+from typing import Dict, List, Optional, Any
+
+logger = logging.getLogger(__name__)
+
+
+# Default theme based on Mantine defaults
+DEFAULT_THEME = {
+    "name": "default",
+    "version": "1.0.0",
+    "tokens": {
+        "colors": {
+            "primary": "#228be6",
+            "secondary": "#868e96",
+            "success": "#40c057",
+            "warning": "#fab005",
+            "error": "#fa5252",
+            "info": "#15aabf",
+            "background": {
+                "base": "#ffffff",
+                "subtle": "#f8f9fa",
+                "dark": "#212529"
+            },
+            "text": {
+                "primary": "#212529",
+                "secondary": "#495057",
+                "muted": "#868e96",
+                "inverse": "#ffffff"
+            },
+            "border": "#dee2e6"
+        },
+        "spacing": {
+            "xs": "4px",
+            "sm": "8px",
+            "md": "16px",
+            "lg": "24px",
+            "xl": "32px"
+        },
+        "typography": {
+            "fontFamily": "Inter, -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, sans-serif",
+            "fontFamilyMono": "ui-monospace, SFMono-Regular, Menlo, Monaco, monospace",
+            "fontSize": {
+                "xs": "12px",
+                "sm": "14px",
+                "md": "16px",
+                "lg": "18px",
+                "xl": "20px"
+            },
+            "fontWeight": {
+                "normal": 400,
+                "medium": 500,
+                "semibold": 600,
+                "bold": 700
+            },
+            "lineHeight": {
+                "tight": 1.25,
+                "normal": 1.5,
+                "relaxed": 1.75
+            }
+        },
+        "radii": {
+            "none": "0px",
+            "sm": "4px",
+            "md": "8px",
+            "lg": "16px",
+            "xl": "24px",
+            "full": "9999px"
+        },
+        "shadows": {
+            "none": "none",
+            "sm": "0 1px 2px 0 rgb(0 0 0 / 0.05)",
+            "md": "0 4px 6px -1px rgb(0 0 0 / 0.1)",
+            "lg": "0 10px 15px -3px rgb(0 0 0 / 0.1)",
+            "xl": "0 20px 25px -5px rgb(0 0 0 / 0.1)"
+        },
+        "transitions": {
+            "fast": "150ms",
+            "normal": "300ms",
+            "slow": "500ms"
+        }
+    }
+}
+
+
+# Required token categories for validation
+REQUIRED_TOKEN_CATEGORIES = ["colors", "spacing", "typography", "radii"]
+
+
+class ThemeStore:
+    """
+    Store and manage design themes.
+
+    Handles persistence to user-level and project-level locations.
+    """
+
+    def __init__(self, project_dir: Optional[Path] = None):
+        """
+        Initialize theme store.
+
+        Args:
+            project_dir: Project directory for project-level themes
+        """
+        self.project_dir = project_dir
+        self._themes: Dict[str, Dict[str, Any]] = {}
+        self._active_theme: Optional[str] = None
+
+        # Load default theme
+        self._themes["default"] = DEFAULT_THEME.copy()
+
+    @property
+    def user_themes_dir(self) -> Path:
+        """User-level themes directory."""
+        return Path.home() / ".config" / "claude" / "themes"
+
+    @property
+    def project_themes_dir(self) -> Optional[Path]:
+        """Project-level themes directory."""
+        if self.project_dir:
+            return self.project_dir / ".viz-platform" / "themes"
+        return None
+
+    def load_themes(self) -> int:
+        """
+        Load themes from user and project directories.
+
+        Project themes take precedence over user themes.
+
+        Returns:
+            Number of themes loaded
+        """
+        count = 0
+
+        # Load user themes
+        if self.user_themes_dir.exists():
+            for theme_file in self.user_themes_dir.glob("*.json"):
+                try:
+                    with open(theme_file, 'r') as f:
+                        theme = json.load(f)
+                    name = theme.get('name', theme_file.stem)
+                    self._themes[name] = theme
+                    count += 1
+                    logger.debug(f"Loaded user theme: {name}")
+                except Exception as e:
+                    logger.warning(f"Failed to load theme {theme_file}: {e}")
+
+        # Load project themes (override user themes)
+        if self.project_themes_dir and self.project_themes_dir.exists():
+            for theme_file in self.project_themes_dir.glob("*.json"):
+                try:
+                    with open(theme_file, 'r') as f:
+                        theme = json.load(f)
+                    name = theme.get('name', theme_file.stem)
+                    self._themes[name] = theme
+                    count += 1
+                    logger.debug(f"Loaded project theme: {name}")
+                except Exception as e:
+                    logger.warning(f"Failed to load theme {theme_file}: {e}")
+
+        return count
+
+    def save_theme(
+        self,
+        theme: Dict[str, Any],
+        location: str = "project"
+    ) -> Path:
+        """
+        Save a theme to disk.
+
+        Args:
+            theme: Theme dict to save
+            location: "user" or "project"
+
+        Returns:
+            Path where theme was saved
+        """
+        name = theme.get('name', 'unnamed')
+
+        if location == "user":
+            target_dir = self.user_themes_dir
+        else:
+            target_dir = self.project_themes_dir
+            if not target_dir:
+                target_dir = self.user_themes_dir
+
+        target_dir.mkdir(parents=True, exist_ok=True)
+        theme_path = target_dir / f"{name}.json"
+
+        with open(theme_path, 'w') as f:
+            json.dump(theme, f, indent=2)
+
+        # Update in-memory store
+        self._themes[name] = theme
+
+        return theme_path
+
+    def get_theme(self, name: str) -> Optional[Dict[str, Any]]:
+        """Get a theme by name."""
+        return self._themes.get(name)
+
+    def list_themes(self) -> List[str]:
+        """List all available theme names."""
+        return list(self._themes.keys())
+
+    def set_active_theme(self, name: str) -> bool:
+        """
+        Set the active theme.
+
+        Args:
+            name: Theme name to activate
+
+        Returns:
+            True if theme was activated
+        """
+        if name in self._themes:
+            self._active_theme = name
+            return True
+        return False
+
+    def get_active_theme(self) -> Optional[Dict[str, Any]]:
+        """Get the currently active theme."""
+        if self._active_theme:
+            return self._themes.get(self._active_theme)
+        return None
+
+    def delete_theme(self, name: str) -> bool:
+        """
+        Delete a theme.
+
+        Args:
+            name: Theme name to delete
+
+        Returns:
+            True if theme was deleted
+        """
+        if name == "default":
+            return False  # Cannot delete default theme
+
+        if name in self._themes:
+            del self._themes[name]
+
+            # Remove file if exists
+            for themes_dir in [self.user_themes_dir, self.project_themes_dir]:
+                if themes_dir and themes_dir.exists():
+                    theme_path = themes_dir / f"{name}.json"
+                    if theme_path.exists():
+                        theme_path.unlink()
+
+            if self._active_theme == name:
+                self._active_theme = None
+
+            return True
+        return False

mcp-servers/viz-platform/mcp_server/theme_tools.py

@@ -0,0 +1,391 @@
+"""
+Theme management tools for viz-platform.
+
+Provides design token-based theming system for consistent visual styling.
+"""
+import copy
+import logging
+from typing import Dict, List, Optional, Any
+
+from .theme_store import ThemeStore, DEFAULT_THEME, REQUIRED_TOKEN_CATEGORIES
+
+logger = logging.getLogger(__name__)
+
+
+class ThemeTools:
+    """
+    Design token-based theming tools.
+
+    Creates and manages themes that integrate with DMC and Plotly.
+    """
+
+    def __init__(self, store: Optional[ThemeStore] = None):
+        """
+        Initialize theme tools.
+
+        Args:
+            store: Optional ThemeStore for persistence
+        """
+        self.store = store or ThemeStore()
+
+    async def theme_create(
+        self,
+        name: str,
+        tokens: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """
+        Create a new theme with design tokens.
+
+        Args:
+            name: Unique theme name
+            tokens: Design tokens dict with colors, spacing, typography, radii
+
+        Returns:
+            Dict with:
+                - name: Theme name
+                - tokens: Full token set (merged with defaults)
+                - validation: Validation results
+        """
+        # Check for name collision
+        if self.store.get_theme(name) and name != "default":
+            return {
+                "error": f"Theme '{name}' already exists. Use theme_extend to modify it.",
+                "name": name
+            }
+
+        # Start with default tokens and merge provided ones
+        theme_tokens = copy.deepcopy(DEFAULT_THEME["tokens"])
+        theme_tokens = self._deep_merge(theme_tokens, tokens)
+
+        # Create theme object
+        theme = {
+            "name": name,
+            "version": "1.0.0",
+            "tokens": theme_tokens
+        }
+
+        # Validate the theme
+        validation = self._validate_tokens(theme_tokens)
+
+        # Save to store
+        self.store._themes[name] = theme
+
+        return {
+            "name": name,
+            "tokens": theme_tokens,
+            "validation": validation,
+            "complete": validation["complete"]
+        }
+
+    async def theme_extend(
+        self,
+        base_theme: str,
+        overrides: Dict[str, Any],
+        new_name: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Create a new theme by extending an existing one.
+
+        Args:
+            base_theme: Name of theme to extend
+            overrides: Token overrides to apply
+            new_name: Optional name for the new theme (defaults to base_theme_extended)
+
+        Returns:
+            Dict with the new theme or error
+        """
+        # Get base theme
+        base = self.store.get_theme(base_theme)
+        if not base:
+            available = self.store.list_themes()
+            return {
+                "error": f"Base theme '{base_theme}' not found. Available: {available}",
+                "name": None
+            }
+
+        # Determine new name
+        name = new_name or f"{base_theme}_extended"
+
+        # Check for collision
+        if self.store.get_theme(name) and name != base_theme:
+            return {
+                "error": f"Theme '{name}' already exists. Choose a different name.",
+                "name": name
+            }
+
+        # Merge tokens
+        theme_tokens = copy.deepcopy(base.get("tokens", {}))
+        theme_tokens = self._deep_merge(theme_tokens, overrides)
+
+        # Create theme
+        theme = {
+            "name": name,
+            "version": "1.0.0",
+            "extends": base_theme,
+            "tokens": theme_tokens
+        }
+
+        # Validate
+        validation = self._validate_tokens(theme_tokens)
+
+        # Save to store
+        self.store._themes[name] = theme
+
+        return {
+            "name": name,
+            "extends": base_theme,
+            "tokens": theme_tokens,
+            "validation": validation,
+            "complete": validation["complete"]
+        }
+
+    async def theme_validate(self, theme_name: str) -> Dict[str, Any]:
+        """
+        Validate a theme for completeness.
+
+        Args:
+            theme_name: Theme name to validate
+
+        Returns:
+            Dict with:
+                - valid: bool
+                - complete: bool (all optional tokens present)
+                - missing: List of missing required tokens
+                - warnings: List of warnings
+        """
+        theme = self.store.get_theme(theme_name)
+        if not theme:
+            available = self.store.list_themes()
+            return {
+                "error": f"Theme '{theme_name}' not found. Available: {available}",
+                "valid": False
+            }
+
+        tokens = theme.get("tokens", {})
+        validation = self._validate_tokens(tokens)
+
+        return {
+            "theme_name": theme_name,
+            "valid": validation["valid"],
+            "complete": validation["complete"],
+            "missing_required": validation["missing_required"],
+            "missing_optional": validation["missing_optional"],
+            "warnings": validation["warnings"]
+        }
+
+    async def theme_export_css(self, theme_name: str) -> Dict[str, Any]:
+        """
+        Export a theme as CSS custom properties.
+
+        Args:
+            theme_name: Theme name to export
+
+        Returns:
+            Dict with:
+                - css: CSS custom properties string
+                - variables: List of variable names
+        """
+        theme = self.store.get_theme(theme_name)
+        if not theme:
+            available = self.store.list_themes()
+            return {
+                "error": f"Theme '{theme_name}' not found. Available: {available}",
+                "css": None
+            }
+
+        tokens = theme.get("tokens", {})
+        css_vars = []
+        var_names = []
+
+        # Convert tokens to CSS custom properties
+        css_vars.append(f"/* Theme: {theme_name} */")
+        css_vars.append(":root {")
+
+        # Colors
+        colors = tokens.get("colors", {})
+        css_vars.append("  /* Colors */")
+        for key, value in self._flatten_tokens(colors, "color").items():
+            var_name = f"--{key}"
+            css_vars.append(f"  {var_name}: {value};")
+            var_names.append(var_name)
+
+        # Spacing
+        spacing = tokens.get("spacing", {})
+        css_vars.append("\n  /* Spacing */")
+        for key, value in spacing.items():
+            var_name = f"--spacing-{key}"
+            css_vars.append(f"  {var_name}: {value};")
+            var_names.append(var_name)
+
+        # Typography
+        typography = tokens.get("typography", {})
+        css_vars.append("\n  /* Typography */")
+        for key, value in self._flatten_tokens(typography, "font").items():
+            var_name = f"--{key}"
+            css_vars.append(f"  {var_name}: {value};")
+            var_names.append(var_name)
+
+        # Radii
+        radii = tokens.get("radii", {})
+        css_vars.append("\n  /* Border Radius */")
+        for key, value in radii.items():
+            var_name = f"--radius-{key}"
+            css_vars.append(f"  {var_name}: {value};")
+            var_names.append(var_name)
+
+        # Shadows
+        shadows = tokens.get("shadows", {})
+        if shadows:
+            css_vars.append("\n  /* Shadows */")
+            for key, value in shadows.items():
+                var_name = f"--shadow-{key}"
+                css_vars.append(f"  {var_name}: {value};")
+                var_names.append(var_name)
+
+        # Transitions
+        transitions = tokens.get("transitions", {})
+        if transitions:
+            css_vars.append("\n  /* Transitions */")
+            for key, value in transitions.items():
+                var_name = f"--transition-{key}"
+                css_vars.append(f"  {var_name}: {value};")
+                var_names.append(var_name)
+
+        css_vars.append("}")
+
+        css_content = "\n".join(css_vars)
+
+        return {
+            "theme_name": theme_name,
+            "css": css_content,
+            "variable_count": len(var_names),
+            "variables": var_names
+        }
+
+    async def theme_list(self) -> Dict[str, Any]:
+        """
+        List all available themes.
+
+        Returns:
+            Dict with theme names and active theme
+        """
+        themes = self.store.list_themes()
+        active = self.store._active_theme
+
+        theme_info = {}
+        for name in themes:
+            theme = self.store.get_theme(name)
+            theme_info[name] = {
+                "extends": theme.get("extends"),
+                "version": theme.get("version", "1.0.0")
+            }
+
+        return {
+            "themes": theme_info,
+            "active_theme": active,
+            "count": len(themes)
+        }
+
+    async def theme_activate(self, theme_name: str) -> Dict[str, Any]:
+        """
+        Set the active theme.
+
+        Args:
+            theme_name: Theme to activate
+
+        Returns:
+            Dict with activation status
+        """
+        if self.store.set_active_theme(theme_name):
+            return {
+                "active_theme": theme_name,
+                "success": True
+            }
+        return {
+            "error": f"Theme '{theme_name}' not found.",
+            "success": False
+        }
+
+    def _validate_tokens(self, tokens: Dict[str, Any]) -> Dict[str, Any]:
+        """Validate token structure and completeness."""
+        missing_required = []
+        missing_optional = []
+        warnings = []
+
+        # Check required categories
+        for category in REQUIRED_TOKEN_CATEGORIES:
+            if category not in tokens:
+                missing_required.append(category)
+
+        # Check colors structure
+        colors = tokens.get("colors", {})
+        required_colors = ["primary", "background", "text"]
+        for color in required_colors:
+            if color not in colors:
+                missing_required.append(f"colors.{color}")
+
+        # Check spacing
+        spacing = tokens.get("spacing", {})
+        required_spacing = ["xs", "sm", "md", "lg"]
+        for size in required_spacing:
+            if size not in spacing:
+                missing_optional.append(f"spacing.{size}")
+
+        # Check typography
+        typography = tokens.get("typography", {})
+        if "fontFamily" not in typography:
+            missing_optional.append("typography.fontFamily")
+        if "fontSize" not in typography:
+            missing_optional.append("typography.fontSize")
+
+        # Check radii
+        radii = tokens.get("radii", {})
+        if "sm" not in radii and "md" not in radii:
+            missing_optional.append("radii.sm or radii.md")
+
+        # Warnings for common issues
+        if "shadows" not in tokens:
+            warnings.append("No shadows defined - components may have no elevation")
+        if "transitions" not in tokens:
+            warnings.append("No transitions defined - animations will use defaults")
+
+        return {
+            "valid": len(missing_required) == 0,
+            "complete": len(missing_required) == 0 and len(missing_optional) == 0,
+            "missing_required": missing_required,
+            "missing_optional": missing_optional,
+            "warnings": warnings
+        }
+
+    def _deep_merge(
+        self,
+        base: Dict[str, Any],
+        override: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """Deep merge two dictionaries."""
+        result = copy.deepcopy(base)
+
+        for key, value in override.items():
+            if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+                result[key] = self._deep_merge(result[key], value)
+            else:
+                result[key] = value
+
+        return result
+
+    def _flatten_tokens(
+        self,
+        tokens: Dict[str, Any],
+        prefix: str
+    ) -> Dict[str, str]:
+        """Flatten nested token dict for CSS export."""
+        result = {}
+
+        for key, value in tokens.items():
+            if isinstance(value, dict):
+                nested = self._flatten_tokens(value, f"{prefix}-{key}")
+                result.update(nested)
+            else:
+                result[f"{prefix}-{key}"] = str(value)
+
+        return result

mcp-servers/viz-platform/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "viz-platform-mcp"
+version = "1.0.0"
+description = "MCP Server for visualization with Dash Mantine Components validation and theming"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [
+    {name = "Leo Miranda"}
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "mcp>=0.9.0",
+    "plotly>=5.18.0",
+    "dash>=2.14.0",
+    "dash-mantine-components>=2.0.0",
+    "python-dotenv>=1.0.0",
+    "pydantic>=2.5.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.3",
+    "pytest-asyncio>=0.23.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["mcp_server*"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

mcp-servers/viz-platform/registry/dmc_2_5.json

@@ -0,0 +1,668 @@
+{
+  "version": "2.5.1",
+  "generated": "2026-01-26",
+  "mantine_version": "7.x",
+  "categories": {
+    "buttons": ["Button", "ButtonGroup", "ActionIcon", "ActionIconGroup", "CopyButton", "CloseButton", "UnstyledButton"],
+    "inputs": [
+      "TextInput", "PasswordInput", "NumberInput", "Textarea", "Select", "MultiSelect",
+      "Checkbox", "CheckboxGroup", "CheckboxCard", "Switch", "Radio", "RadioGroup", "RadioCard",
+      "Slider", "RangeSlider", "ColorInput", "ColorPicker", "Autocomplete", "TagsInput",
+      "PinInput", "Rating", "SegmentedControl", "Chip", "ChipGroup", "JsonInput",
+      "NativeSelect", "FileInput", "Combobox"
+    ],
+    "navigation": ["Anchor", "Breadcrumbs", "Burger", "NavLink", "Pagination", "Stepper", "Tabs", "TabsList", "TabsTab", "TabsPanel"],
+    "feedback": ["Alert", "Loader", "Notification", "NotificationContainer", "Progress", "RingProgress", "Skeleton"],
+    "overlays": ["Modal", "Drawer", "DrawerStack", "Popover", "HoverCard", "Tooltip", "FloatingTooltip", "Menu", "MenuTarget", "MenuDropdown", "MenuItem", "Affix"],
+    "typography": ["Text", "Title", "Highlight", "Mark", "Code", "CodeHighlight", "Blockquote", "List", "ListItem", "Kbd"],
+    "layout": [
+      "AppShell", "AppShellHeader", "AppShellNavbar", "AppShellAside", "AppShellFooter", "AppShellMain", "AppShellSection",
+      "Container", "Center", "Stack", "Group", "Flex", "Grid", "GridCol", "SimpleGrid",
+      "Paper", "Card", "CardSection", "Box", "Space", "Divider", "AspectRatio", "ScrollArea"
+    ],
+    "data_display": [
+      "Accordion", "AccordionItem", "AccordionControl", "AccordionPanel",
+      "Avatar", "AvatarGroup", "Badge", "Image", "BackgroundImage",
+      "Indicator", "Spoiler", "Table", "ThemeIcon", "Timeline", "TimelineItem", "Tree"
+    ],
+    "charts": ["AreaChart", "BarChart", "LineChart", "PieChart", "DonutChart", "RadarChart", "ScatterChart", "BubbleChart", "CompositeChart", "Sparkline"],
+    "dates": ["DatePicker", "DateTimePicker", "DateInput", "DatePickerInput", "MonthPicker", "YearPicker", "TimePicker", "TimeInput", "Calendar", "MiniCalendar", "DatesProvider"]
+  },
+  "components": {
+    "Button": {
+      "description": "Button component for user interactions",
+      "props": {
+        "children": {"type": "any", "description": "Button content"},
+        "variant": {"type": "string", "enum": ["filled", "light", "outline", "transparent", "white", "subtle", "default", "gradient"], "default": "filled"},
+        "color": {"type": "string", "default": "blue", "description": "Key of theme.colors or CSS color"},
+        "size": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl", "compact-xs", "compact-sm", "compact-md", "compact-lg", "compact-xl"], "default": "sm"},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "disabled": {"type": "boolean", "default": false},
+        "loading": {"type": "boolean", "default": false},
+        "loaderProps": {"type": "object"},
+        "leftSection": {"type": "any", "description": "Content on the left side of label"},
+        "rightSection": {"type": "any", "description": "Content on the right side of label"},
+        "fullWidth": {"type": "boolean", "default": false},
+        "gradient": {"type": "object", "description": "Gradient for gradient variant"},
+        "justify": {"type": "string", "enum": ["center", "start", "end", "space-between"], "default": "center"},
+        "autoContrast": {"type": "boolean", "default": false},
+        "n_clicks": {"type": "integer", "default": 0, "description": "Dash callback trigger"}
+      }
+    },
+    "ActionIcon": {
+      "description": "Icon button without text label",
+      "props": {
+        "children": {"type": "any", "required": true, "description": "Icon element"},
+        "variant": {"type": "string", "enum": ["filled", "light", "outline", "transparent", "white", "subtle", "default", "gradient"], "default": "subtle"},
+        "color": {"type": "string", "default": "gray"},
+        "size": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "md"},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "disabled": {"type": "boolean", "default": false},
+        "loading": {"type": "boolean", "default": false},
+        "autoContrast": {"type": "boolean", "default": false},
+        "n_clicks": {"type": "integer", "default": 0}
+      }
+    },
+    "TextInput": {
+      "description": "Text input field",
+      "props": {
+        "value": {"type": "string", "default": ""},
+        "placeholder": {"type": "string"},
+        "label": {"type": "any"},
+        "description": {"type": "any"},
+        "error": {"type": "any"},
+        "disabled": {"type": "boolean", "default": false},
+        "required": {"type": "boolean", "default": false},
+        "size": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "variant": {"type": "string", "enum": ["default", "filled", "unstyled"], "default": "default"},
+        "leftSection": {"type": "any"},
+        "rightSection": {"type": "any"},
+        "withAsterisk": {"type": "boolean", "default": false},
+        "debounce": {"type": "integer", "description": "Debounce delay in ms"},
+        "leftSectionPointerEvents": {"type": "string", "enum": ["none", "all"], "default": "none"},
+        "rightSectionPointerEvents": {"type": "string", "enum": ["none", "all"], "default": "none"}
+      }
+    },
+    "NumberInput": {
+      "description": "Numeric input with optional controls",
+      "props": {
+        "value": {"type": "number"},
+        "placeholder": {"type": "string"},
+        "label": {"type": "any"},
+        "description": {"type": "any"},
+        "error": {"type": "any"},
+        "disabled": {"type": "boolean", "default": false},
+        "required": {"type": "boolean", "default": false},
+        "min": {"type": "number"},
+        "max": {"type": "number"},
+        "step": {"type": "number", "default": 1},
+        "hideControls": {"type": "boolean", "default": false},
+        "size": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "allowNegative": {"type": "boolean", "default": true},
+        "allowDecimal": {"type": "boolean", "default": true},
+        "clampBehavior": {"type": "string", "enum": ["strict", "blur", "none"], "default": "blur"},
+        "decimalScale": {"type": "integer"},
+        "fixedDecimalScale": {"type": "boolean", "default": false},
+        "thousandSeparator": {"type": "string"},
+        "decimalSeparator": {"type": "string"},
+        "prefix": {"type": "string"},
+        "suffix": {"type": "string"}
+      }
+    },
+    "Select": {
+      "description": "Dropdown select input",
+      "props": {
+        "value": {"type": "string"},
+        "data": {"type": "array", "required": true, "description": "Array of options: strings or {value, label} objects"},
+        "placeholder": {"type": "string"},
+        "label": {"type": "any"},
+        "description": {"type": "any"},
+        "error": {"type": "any"},
+        "disabled": {"type": "boolean", "default": false},
+        "required": {"type": "boolean", "default": false},
+        "searchable": {"type": "boolean", "default": false},
+        "clearable": {"type": "boolean", "default": false},
+        "nothingFoundMessage": {"type": "string"},
+        "size": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "maxDropdownHeight": {"type": "number", "default": 250},
+        "allowDeselect": {"type": "boolean", "default": true},
+        "checkIconPosition": {"type": "string", "enum": ["left", "right"], "default": "left"},
+        "comboboxProps": {"type": "object"},
+        "withScrollArea": {"type": "boolean", "default": true}
+      }
+    },
+    "MultiSelect": {
+      "description": "Multiple selection dropdown",
+      "props": {
+        "value": {"type": "array", "default": []},
+        "data": {"type": "array", "required": true},
+        "placeholder": {"type": "string"},
+        "label": {"type": "any"},
+        "description": {"type": "any"},
+        "error": {"type": "any"},
+        "disabled": {"type": "boolean", "default": false},
+        "required": {"type": "boolean", "default": false},
+        "searchable": {"type": "boolean", "default": false},
+        "clearable": {"type": "boolean", "default": false},
+        "maxValues": {"type": "integer"},
+        "hidePickedOptions": {"type": "boolean", "default": false},
+        "size": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "maxDropdownHeight": {"type": "number", "default": 250},
+        "withCheckIcon": {"type": "boolean", "default": true}
+      }
+    },
+    "Checkbox": {
+      "description": "Checkbox input",
+      "props": {
+        "checked": {"type": "boolean", "default": false},
+        "label": {"type": "any"},
+        "description": {"type": "any"},
+        "error": {"type": "any"},
+        "disabled": {"type": "boolean", "default": false},
+        "indeterminate": {"type": "boolean", "default": false},
+        "size": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "color": {"type": "string", "default": "blue"},
+        "labelPosition": {"type": "string", "enum": ["left", "right"], "default": "right"},
+        "autoContrast": {"type": "boolean", "default": false},
+        "icon": {"type": "any"},
+        "iconColor": {"type": "string"}
+      }
+    },
+    "Switch": {
+      "description": "Toggle switch input",
+      "props": {
+        "checked": {"type": "boolean", "default": false},
+        "label": {"type": "any"},
+        "description": {"type": "any"},
+        "error": {"type": "any"},
+        "disabled": {"type": "boolean", "default": false},
+        "size": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "xl"},
+        "color": {"type": "string", "default": "blue"},
+        "onLabel": {"type": "any"},
+        "offLabel": {"type": "any"},
+        "thumbIcon": {"type": "any"},
+        "labelPosition": {"type": "string", "enum": ["left", "right"], "default": "right"}
+      }
+    },
+    "Slider": {
+      "description": "Slider input for numeric values",
+      "props": {
+        "value": {"type": "number"},
+        "min": {"type": "number", "default": 0},
+        "max": {"type": "number", "default": 100},
+        "step": {"type": "number", "default": 1},
+        "label": {"type": "any"},
+        "disabled": {"type": "boolean", "default": false},
+        "marks": {"type": "array"},
+        "size": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "md"},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "xl"},
+        "color": {"type": "string", "default": "blue"},
+        "showLabelOnHover": {"type": "boolean", "default": true},
+        "labelAlwaysOn": {"type": "boolean", "default": false},
+        "thumbLabel": {"type": "string"},
+        "precision": {"type": "integer", "default": 0},
+        "inverted": {"type": "boolean", "default": false},
+        "thumbSize": {"type": "number"},
+        "restrictToMarks": {"type": "boolean", "default": false}
+      }
+    },
+    "Alert": {
+      "description": "Alert component for feedback messages",
+      "props": {
+        "children": {"type": "any"},
+        "title": {"type": "any"},
+        "color": {"type": "string", "default": "blue"},
+        "variant": {"type": "string", "enum": ["filled", "light", "outline", "default", "transparent", "white"], "default": "light"},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "icon": {"type": "any"},
+        "withCloseButton": {"type": "boolean", "default": false},
+        "closeButtonLabel": {"type": "string"},
+        "autoContrast": {"type": "boolean", "default": false}
+      }
+    },
+    "Loader": {
+      "description": "Loading indicator",
+      "props": {
+        "color": {"type": "string", "default": "blue"},
+        "size": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "md"},
+        "type": {"type": "string", "enum": ["oval", "bars", "dots"], "default": "oval"}
+      }
+    },
+    "Progress": {
+      "description": "Progress bar",
+      "props": {
+        "value": {"type": "number", "required": true},
+        "color": {"type": "string", "default": "blue"},
+        "size": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "md"},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "striped": {"type": "boolean", "default": false},
+        "animated": {"type": "boolean", "default": false},
+        "autoContrast": {"type": "boolean", "default": false},
+        "transitionDuration": {"type": "number", "default": 100}
+      }
+    },
+    "Modal": {
+      "description": "Modal dialog overlay",
+      "props": {
+        "children": {"type": "any"},
+        "opened": {"type": "boolean", "required": true},
+        "title": {"type": "any"},
+        "size": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl", "auto"], "default": "md"},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "centered": {"type": "boolean", "default": false},
+        "fullScreen": {"type": "boolean", "default": false},
+        "withCloseButton": {"type": "boolean", "default": true},
+        "closeOnClickOutside": {"type": "boolean", "default": true},
+        "closeOnEscape": {"type": "boolean", "default": true},
+        "overlayProps": {"type": "object"},
+        "padding": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "md"},
+        "transitionProps": {"type": "object"},
+        "zIndex": {"type": "number", "default": 200},
+        "trapFocus": {"type": "boolean", "default": true},
+        "returnFocus": {"type": "boolean", "default": true},
+        "lockScroll": {"type": "boolean", "default": true}
+      }
+    },
+    "Drawer": {
+      "description": "Sliding panel drawer",
+      "props": {
+        "children": {"type": "any"},
+        "opened": {"type": "boolean", "required": true},
+        "title": {"type": "any"},
+        "position": {"type": "string", "enum": ["left", "right", "top", "bottom"], "default": "left"},
+        "size": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "md"},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"]},
+        "withCloseButton": {"type": "boolean", "default": true},
+        "closeOnClickOutside": {"type": "boolean", "default": true},
+        "closeOnEscape": {"type": "boolean", "default": true},
+        "overlayProps": {"type": "object"},
+        "padding": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "md"},
+        "zIndex": {"type": "number", "default": 200},
+        "offset": {"type": "number", "default": 0},
+        "trapFocus": {"type": "boolean", "default": true},
+        "returnFocus": {"type": "boolean", "default": true},
+        "lockScroll": {"type": "boolean", "default": true}
+      }
+    },
+    "Tooltip": {
+      "description": "Tooltip on hover",
+      "props": {
+        "children": {"type": "any", "required": true},
+        "label": {"type": "any", "required": true},
+        "position": {"type": "string", "enum": ["top", "right", "bottom", "left", "top-start", "top-end", "right-start", "right-end", "bottom-start", "bottom-end", "left-start", "left-end"], "default": "top"},
+        "color": {"type": "string"},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "withArrow": {"type": "boolean", "default": false},
+        "arrowSize": {"type": "number", "default": 4},
+        "arrowOffset": {"type": "number", "default": 5},
+        "offset": {"type": "number", "default": 5},
+        "multiline": {"type": "boolean", "default": false},
+        "disabled": {"type": "boolean", "default": false},
+        "openDelay": {"type": "number", "default": 0},
+        "closeDelay": {"type": "number", "default": 0},
+        "transitionProps": {"type": "object"},
+        "zIndex": {"type": "number", "default": 300}
+      }
+    },
+    "Text": {
+      "description": "Text component with styling",
+      "props": {
+        "children": {"type": "any"},
+        "size": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"]},
+        "c": {"type": "string", "description": "Color"},
+        "fw": {"type": "number", "description": "Font weight"},
+        "fs": {"type": "string", "enum": ["normal", "italic"], "description": "Font style"},
+        "td": {"type": "string", "enum": ["none", "underline", "line-through"], "description": "Text decoration"},
+        "tt": {"type": "string", "enum": ["none", "capitalize", "uppercase", "lowercase"], "description": "Text transform"},
+        "ta": {"type": "string", "enum": ["left", "center", "right", "justify"], "description": "Text align"},
+        "lineClamp": {"type": "integer"},
+        "truncate": {"type": "boolean", "default": false},
+        "inherit": {"type": "boolean", "default": false},
+        "gradient": {"type": "object"},
+        "span": {"type": "boolean", "default": false},
+        "lh": {"type": "string", "description": "Line height"}
+      }
+    },
+    "Title": {
+      "description": "Heading component",
+      "props": {
+        "children": {"type": "any"},
+        "order": {"type": "integer", "enum": [1, 2, 3, 4, 5, 6], "default": 1},
+        "size": {"type": "string"},
+        "c": {"type": "string", "description": "Color"},
+        "ta": {"type": "string", "enum": ["left", "center", "right", "justify"]},
+        "td": {"type": "string", "enum": ["none", "underline", "line-through"]},
+        "tt": {"type": "string", "enum": ["none", "capitalize", "uppercase", "lowercase"]},
+        "lineClamp": {"type": "integer"},
+        "truncate": {"type": "boolean", "default": false}
+      }
+    },
+    "Stack": {
+      "description": "Vertical stack layout",
+      "props": {
+        "children": {"type": "any"},
+        "gap": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "md"},
+        "align": {"type": "string", "enum": ["stretch", "center", "flex-start", "flex-end"], "default": "stretch"},
+        "justify": {"type": "string", "enum": ["flex-start", "flex-end", "center", "space-between", "space-around", "space-evenly"], "default": "flex-start"}
+      }
+    },
+    "Group": {
+      "description": "Horizontal group layout",
+      "props": {
+        "children": {"type": "any"},
+        "gap": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "md"},
+        "align": {"type": "string", "enum": ["stretch", "center", "flex-start", "flex-end"], "default": "center"},
+        "justify": {"type": "string", "enum": ["flex-start", "flex-end", "center", "space-between", "space-around"], "default": "flex-start"},
+        "grow": {"type": "boolean", "default": false},
+        "wrap": {"type": "string", "enum": ["wrap", "nowrap", "wrap-reverse"], "default": "wrap"},
+        "preventGrowOverflow": {"type": "boolean", "default": true}
+      }
+    },
+    "Flex": {
+      "description": "Flexbox container",
+      "props": {
+        "children": {"type": "any"},
+        "gap": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"]},
+        "rowGap": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"]},
+        "columnGap": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"]},
+        "align": {"type": "string", "enum": ["stretch", "center", "flex-start", "flex-end", "baseline"]},
+        "justify": {"type": "string", "enum": ["flex-start", "flex-end", "center", "space-between", "space-around", "space-evenly"]},
+        "wrap": {"type": "string", "enum": ["wrap", "nowrap", "wrap-reverse"], "default": "nowrap"},
+        "direction": {"type": "string", "enum": ["row", "column", "row-reverse", "column-reverse"], "default": "row"}
+      }
+    },
+    "Grid": {
+      "description": "Grid layout component",
+      "props": {
+        "children": {"type": "any"},
+        "columns": {"type": "integer", "default": 12},
+        "gutter": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "md"},
+        "grow": {"type": "boolean", "default": false},
+        "justify": {"type": "string", "enum": ["flex-start", "flex-end", "center", "space-between", "space-around"], "default": "flex-start"},
+        "align": {"type": "string", "enum": ["stretch", "center", "flex-start", "flex-end"], "default": "stretch"},
+        "overflow": {"type": "string", "enum": ["visible", "hidden"], "default": "visible"}
+      }
+    },
+    "SimpleGrid": {
+      "description": "Simple grid with equal columns",
+      "props": {
+        "children": {"type": "any"},
+        "cols": {"type": "integer", "default": 1},
+        "spacing": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "md"},
+        "verticalSpacing": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"]}
+      }
+    },
+    "Container": {
+      "description": "Centered container with max-width",
+      "props": {
+        "children": {"type": "any"},
+        "size": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "md"},
+        "fluid": {"type": "boolean", "default": false}
+      }
+    },
+    "Paper": {
+      "description": "Paper surface component",
+      "props": {
+        "children": {"type": "any"},
+        "shadow": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"]},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "p": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "description": "Padding"},
+        "withBorder": {"type": "boolean", "default": false}
+      }
+    },
+    "Card": {
+      "description": "Card container",
+      "props": {
+        "children": {"type": "any"},
+        "shadow": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "padding": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "md"},
+        "withBorder": {"type": "boolean", "default": false}
+      }
+    },
+    "Tabs": {
+      "description": "Tabbed interface",
+      "props": {
+        "children": {"type": "any"},
+        "value": {"type": "string"},
+        "defaultValue": {"type": "string"},
+        "orientation": {"type": "string", "enum": ["horizontal", "vertical"], "default": "horizontal"},
+        "variant": {"type": "string", "enum": ["default", "outline", "pills"], "default": "default"},
+        "color": {"type": "string", "default": "blue"},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "placement": {"type": "string", "enum": ["left", "right"], "default": "left"},
+        "grow": {"type": "boolean", "default": false},
+        "inverted": {"type": "boolean", "default": false},
+        "keepMounted": {"type": "boolean", "default": true},
+        "activateTabWithKeyboard": {"type": "boolean", "default": true},
+        "allowTabDeactivation": {"type": "boolean", "default": false},
+        "autoContrast": {"type": "boolean", "default": false}
+      }
+    },
+    "Accordion": {
+      "description": "Collapsible content panels",
+      "props": {
+        "children": {"type": "any"},
+        "value": {"type": "any"},
+        "defaultValue": {"type": "any"},
+        "multiple": {"type": "boolean", "default": false},
+        "variant": {"type": "string", "enum": ["default", "contained", "filled", "separated"], "default": "default"},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "chevronPosition": {"type": "string", "enum": ["left", "right"], "default": "right"},
+        "disableChevronRotation": {"type": "boolean", "default": false},
+        "transitionDuration": {"type": "number", "default": 200},
+        "chevronSize": {"type": "any"},
+        "order": {"type": "integer", "enum": [2, 3, 4, 5, 6]}
+      }
+    },
+    "Badge": {
+      "description": "Badge for status or labels",
+      "props": {
+        "children": {"type": "any"},
+        "color": {"type": "string", "default": "blue"},
+        "variant": {"type": "string", "enum": ["filled", "light", "outline", "dot", "gradient", "default", "transparent", "white"], "default": "filled"},
+        "size": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "md"},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "xl"},
+        "fullWidth": {"type": "boolean", "default": false},
+        "leftSection": {"type": "any"},
+        "rightSection": {"type": "any"},
+        "autoContrast": {"type": "boolean", "default": false},
+        "circle": {"type": "boolean", "default": false}
+      }
+    },
+    "Avatar": {
+      "description": "User avatar image",
+      "props": {
+        "src": {"type": "string"},
+        "alt": {"type": "string"},
+        "children": {"type": "any", "description": "Fallback content"},
+        "color": {"type": "string", "default": "gray"},
+        "size": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "md"},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "xl"},
+        "variant": {"type": "string", "enum": ["filled", "light", "outline", "gradient", "default", "transparent", "white"], "default": "filled"},
+        "autoContrast": {"type": "boolean", "default": false}
+      }
+    },
+    "Image": {
+      "description": "Image with fallback",
+      "props": {
+        "src": {"type": "string"},
+        "alt": {"type": "string"},
+        "w": {"type": "any", "description": "Width"},
+        "h": {"type": "any", "description": "Height"},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"]},
+        "fit": {"type": "string", "enum": ["contain", "cover", "fill", "none", "scale-down"], "default": "cover"},
+        "fallbackSrc": {"type": "string"}
+      }
+    },
+    "Table": {
+      "description": "Data table component",
+      "props": {
+        "children": {"type": "any"},
+        "data": {"type": "object", "description": "Table data object with head, body, foot"},
+        "striped": {"type": "boolean", "default": false},
+        "highlightOnHover": {"type": "boolean", "default": false},
+        "withTableBorder": {"type": "boolean", "default": false},
+        "withColumnBorders": {"type": "boolean", "default": false},
+        "withRowBorders": {"type": "boolean", "default": true},
+        "verticalSpacing": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "xs"},
+        "horizontalSpacing": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "xs"},
+        "captionSide": {"type": "string", "enum": ["top", "bottom"], "default": "bottom"},
+        "stickyHeader": {"type": "boolean", "default": false},
+        "stickyHeaderOffset": {"type": "number", "default": 0}
+      }
+    },
+    "AreaChart": {
+      "description": "Area chart for time series data",
+      "props": {
+        "data": {"type": "array", "required": true},
+        "dataKey": {"type": "string", "required": true, "description": "X-axis data key"},
+        "series": {"type": "array", "required": true, "description": "Array of {name, color} objects"},
+        "h": {"type": "any", "description": "Chart height"},
+        "w": {"type": "any", "description": "Chart width"},
+        "curveType": {"type": "string", "enum": ["bump", "linear", "natural", "monotone", "step", "stepBefore", "stepAfter"], "default": "monotone"},
+        "connectNulls": {"type": "boolean", "default": true},
+        "withDots": {"type": "boolean", "default": true},
+        "withGradient": {"type": "boolean", "default": true},
+        "withLegend": {"type": "boolean", "default": false},
+        "withTooltip": {"type": "boolean", "default": true},
+        "withXAxis": {"type": "boolean", "default": true},
+        "withYAxis": {"type": "boolean", "default": true},
+        "gridAxis": {"type": "string", "enum": ["x", "y", "xy", "none"], "default": "x"},
+        "tickLine": {"type": "string", "enum": ["x", "y", "xy", "none"], "default": "y"},
+        "strokeDasharray": {"type": "string"},
+        "fillOpacity": {"type": "number", "default": 0.2},
+        "splitColors": {"type": "array"},
+        "areaChartProps": {"type": "object"},
+        "type": {"type": "string", "enum": ["default", "stacked", "percent", "split"], "default": "default"}
+      }
+    },
+    "BarChart": {
+      "description": "Bar chart for categorical data",
+      "props": {
+        "data": {"type": "array", "required": true},
+        "dataKey": {"type": "string", "required": true},
+        "series": {"type": "array", "required": true},
+        "h": {"type": "any"},
+        "w": {"type": "any"},
+        "orientation": {"type": "string", "enum": ["horizontal", "vertical"], "default": "vertical"},
+        "withLegend": {"type": "boolean", "default": false},
+        "withTooltip": {"type": "boolean", "default": true},
+        "withXAxis": {"type": "boolean", "default": true},
+        "withYAxis": {"type": "boolean", "default": true},
+        "gridAxis": {"type": "string", "enum": ["x", "y", "xy", "none"], "default": "x"},
+        "tickLine": {"type": "string", "enum": ["x", "y", "xy", "none"], "default": "y"},
+        "barProps": {"type": "object"},
+        "type": {"type": "string", "enum": ["default", "stacked", "percent", "waterfall"], "default": "default"}
+      }
+    },
+    "LineChart": {
+      "description": "Line chart for trends",
+      "props": {
+        "data": {"type": "array", "required": true},
+        "dataKey": {"type": "string", "required": true},
+        "series": {"type": "array", "required": true},
+        "h": {"type": "any"},
+        "w": {"type": "any"},
+        "curveType": {"type": "string", "enum": ["bump", "linear", "natural", "monotone", "step", "stepBefore", "stepAfter"], "default": "monotone"},
+        "connectNulls": {"type": "boolean", "default": true},
+        "withDots": {"type": "boolean", "default": true},
+        "withLegend": {"type": "boolean", "default": false},
+        "withTooltip": {"type": "boolean", "default": true},
+        "withXAxis": {"type": "boolean", "default": true},
+        "withYAxis": {"type": "boolean", "default": true},
+        "gridAxis": {"type": "string", "enum": ["x", "y", "xy", "none"], "default": "x"},
+        "strokeWidth": {"type": "number", "default": 2}
+      }
+    },
+    "PieChart": {
+      "description": "Pie chart for proportions",
+      "props": {
+        "data": {"type": "array", "required": true, "description": "Array of {name, value, color} objects"},
+        "h": {"type": "any"},
+        "w": {"type": "any"},
+        "withLabels": {"type": "boolean", "default": false},
+        "withLabelsLine": {"type": "boolean", "default": true},
+        "withTooltip": {"type": "boolean", "default": true},
+        "labelsPosition": {"type": "string", "enum": ["inside", "outside"], "default": "outside"},
+        "labelsType": {"type": "string", "enum": ["value", "percent"], "default": "value"},
+        "strokeWidth": {"type": "number", "default": 1},
+        "strokeColor": {"type": "string"},
+        "startAngle": {"type": "number", "default": 0},
+        "endAngle": {"type": "number", "default": 360}
+      }
+    },
+    "DonutChart": {
+      "description": "Donut chart (pie with hole)",
+      "props": {
+        "data": {"type": "array", "required": true},
+        "h": {"type": "any"},
+        "w": {"type": "any"},
+        "withLabels": {"type": "boolean", "default": false},
+        "withLabelsLine": {"type": "boolean", "default": true},
+        "withTooltip": {"type": "boolean", "default": true},
+        "thickness": {"type": "number", "default": 20},
+        "chartLabel": {"type": "any"},
+        "strokeWidth": {"type": "number", "default": 1},
+        "strokeColor": {"type": "string"},
+        "startAngle": {"type": "number", "default": 0},
+        "endAngle": {"type": "number", "default": 360},
+        "paddingAngle": {"type": "number", "default": 0}
+      }
+    },
+    "DatePicker": {
+      "description": "Date picker calendar",
+      "props": {
+        "value": {"type": "string"},
+        "type": {"type": "string", "enum": ["default", "range", "multiple"], "default": "default"},
+        "defaultValue": {"type": "any"},
+        "allowDeselect": {"type": "boolean", "default": false},
+        "allowSingleDateInRange": {"type": "boolean", "default": false},
+        "numberOfColumns": {"type": "integer", "default": 1},
+        "columnsToScroll": {"type": "integer", "default": 1},
+        "ariaLabels": {"type": "object"},
+        "hideOutsideDates": {"type": "boolean", "default": false},
+        "hideWeekdays": {"type": "boolean", "default": false},
+        "weekendDays": {"type": "array", "default": [0, 6]},
+        "renderDay": {"type": "any"},
+        "minDate": {"type": "string"},
+        "maxDate": {"type": "string"},
+        "size": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"}
+      }
+    },
+    "DatePickerInput": {
+      "description": "Date picker input field",
+      "props": {
+        "value": {"type": "string"},
+        "label": {"type": "any"},
+        "description": {"type": "any"},
+        "error": {"type": "any"},
+        "placeholder": {"type": "string"},
+        "clearable": {"type": "boolean", "default": false},
+        "type": {"type": "string", "enum": ["default", "range", "multiple"], "default": "default"},
+        "valueFormat": {"type": "string", "default": "MMMM D, YYYY"},
+        "size": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "disabled": {"type": "boolean", "default": false},
+        "required": {"type": "boolean", "default": false},
+        "minDate": {"type": "string"},
+        "maxDate": {"type": "string"},
+        "popoverProps": {"type": "object"},
+        "dropdownType": {"type": "string", "enum": ["popover", "modal"], "default": "popover"}
+      }
+    },
+    "DatesProvider": {
+      "description": "Provider for date localization settings",
+      "props": {
+        "children": {"type": "any", "required": true},
+        "settings": {"type": "object", "description": "Locale and formatting settings"}
+      }
+    }
+  }
+}

mcp-servers/viz-platform/requirements.txt

@@ -0,0 +1,16 @@
+# MCP SDK
+mcp>=0.9.0
+
+# Visualization
+plotly>=5.18.0
+dash>=2.14.0
+dash-mantine-components>=2.0.0
+kaleido>=0.2.1  # For chart export (PNG, SVG, PDF)
+
+# Utilities
+python-dotenv>=1.0.0
+pydantic>=2.5.0
+
+# Testing
+pytest>=7.4.3
+pytest-asyncio>=0.23.0

mcp-servers/viz-platform/run.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+# Capture original working directory before any cd operations
+# This should be the user's project directory when launched by Claude Code
+export CLAUDE_PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CACHE_VENV="$HOME/.cache/claude-mcp-venvs/leo-claude-mktplace/viz-platform/.venv"
+LOCAL_VENV="$SCRIPT_DIR/.venv"
+
+if [[ -f "$CACHE_VENV/bin/python" ]]; then
+    PYTHON="$CACHE_VENV/bin/python"
+elif [[ -f "$LOCAL_VENV/bin/python" ]]; then
+    PYTHON="$LOCAL_VENV/bin/python"
+else
+    echo "ERROR: No venv found. Run: ./scripts/setup-venvs.sh" >&2
+    exit 1
+fi
+
+cd "$SCRIPT_DIR"
+export PYTHONPATH="$SCRIPT_DIR"
+exec "$PYTHON" -m mcp_server.server "$@"

mcp-servers/viz-platform/scripts/generate-dmc-registry.py

@@ -0,0 +1,262 @@
+#!/usr/bin/env python3
+"""
+Generate DMC Component Registry from installed dash-mantine-components package.
+
+This script introspects the installed DMC package and generates a JSON registry
+file containing component definitions, props, types, and defaults.
+
+Usage:
+    python generate-dmc-registry.py [--output registry/dmc_X_Y.json]
+
+Requirements:
+    - dash-mantine-components must be installed
+    - Run from the mcp-servers/viz-platform directory
+"""
+import argparse
+import inspect
+import json
+import sys
+from datetime import date
+from pathlib import Path
+from typing import Any, Dict, List, Optional, get_type_hints
+
+
+def get_dmc_version() -> Optional[str]:
+    """Get installed DMC version."""
+    try:
+        from importlib.metadata import version
+        return version('dash-mantine-components')
+    except Exception:
+        return None
+
+
+def get_component_categories() -> Dict[str, List[str]]:
+    """Define component categories."""
+    return {
+        "buttons": ["Button", "ActionIcon", "CopyButton", "FileButton", "UnstyledButton"],
+        "inputs": [
+            "TextInput", "PasswordInput", "NumberInput", "Textarea",
+            "Select", "MultiSelect", "Checkbox", "Switch", "Radio",
+            "Slider", "RangeSlider", "ColorInput", "ColorPicker",
+            "DateInput", "DatePicker", "TimeInput"
+        ],
+        "navigation": ["Anchor", "Breadcrumbs", "Burger", "NavLink", "Pagination", "Stepper", "Tabs"],
+        "feedback": ["Alert", "Loader", "Notification", "Progress", "RingProgress", "Skeleton"],
+        "overlays": ["Dialog", "Drawer", "HoverCard", "Menu", "Modal", "Popover", "Tooltip"],
+        "typography": ["Blockquote", "Code", "Highlight", "Mark", "Text", "Title"],
+        "layout": [
+            "AppShell", "AspectRatio", "Center", "Container", "Flex",
+            "Grid", "Group", "Paper", "SimpleGrid", "Space", "Stack"
+        ],
+        "data": [
+            "Accordion", "Avatar", "Badge", "Card", "Image",
+            "Indicator", "Kbd", "Spoiler", "Table", "ThemeIcon", "Timeline"
+        ]
+    }
+
+
+def extract_prop_type(prop_info: Dict[str, Any]) -> Dict[str, Any]:
+    """Extract prop type information from Dash component prop."""
+    result = {"type": "any"}
+
+    if 'type' not in prop_info:
+        return result
+
+    prop_type = prop_info['type']
+
+    if isinstance(prop_type, dict):
+        type_name = prop_type.get('name', 'any')
+
+        # Map Dash types to JSON schema types
+        type_mapping = {
+            'string': 'string',
+            'number': 'number',
+            'bool': 'boolean',
+            'boolean': 'boolean',
+            'array': 'array',
+            'object': 'object',
+            'node': 'any',
+            'element': 'any',
+            'any': 'any',
+            'func': 'any',
+        }
+
+        result['type'] = type_mapping.get(type_name, 'any')
+
+        # Handle enums
+        if type_name == 'enum' and 'value' in prop_type:
+            values = prop_type['value']
+            if isinstance(values, list):
+                enum_values = []
+                for v in values:
+                    if isinstance(v, dict) and 'value' in v:
+                        # Remove quotes from string values
+                        val = v['value'].strip("'\"")
+                        enum_values.append(val)
+                    elif isinstance(v, str):
+                        enum_values.append(v.strip("'\""))
+                if enum_values:
+                    result['enum'] = enum_values
+                    result['type'] = 'string'
+
+        # Handle union types
+        elif type_name == 'union' and 'value' in prop_type:
+            # For unions, just mark as any for simplicity
+            result['type'] = 'any'
+
+    elif isinstance(prop_type, str):
+        result['type'] = prop_type
+
+    return result
+
+
+def extract_component_props(component_class) -> Dict[str, Any]:
+    """Extract props from a Dash component class."""
+    props = {}
+
+    # Try to get _prop_names or similar
+    if hasattr(component_class, '_prop_names'):
+        prop_names = component_class._prop_names
+    else:
+        prop_names = []
+
+    # Try to get _type attribute for prop definitions
+    if hasattr(component_class, '_type'):
+        prop_types = getattr(component_class, '_type', {})
+    else:
+        prop_types = {}
+
+    # Get default values
+    if hasattr(component_class, '_default_props'):
+        defaults = component_class._default_props
+    else:
+        defaults = {}
+
+    # Try to extract from _prop_descriptions
+    if hasattr(component_class, '_prop_descriptions'):
+        descriptions = component_class._prop_descriptions
+    else:
+        descriptions = {}
+
+    for prop_name in prop_names:
+        if prop_name.startswith('_'):
+            continue
+
+        prop_info = {}
+
+        # Get type info if available
+        if prop_name in prop_types:
+            prop_info = extract_prop_type({'type': prop_types[prop_name]})
+        else:
+            prop_info = {'type': 'any'}
+
+        # Add default if exists
+        if prop_name in defaults:
+            prop_info['default'] = defaults[prop_name]
+
+        # Add description if exists
+        if prop_name in descriptions:
+            prop_info['description'] = descriptions[prop_name]
+
+        props[prop_name] = prop_info
+
+    return props
+
+
+def generate_registry() -> Dict[str, Any]:
+    """Generate the component registry from installed DMC."""
+    try:
+        import dash_mantine_components as dmc
+    except ImportError:
+        print("ERROR: dash-mantine-components not installed")
+        print("Install with: pip install dash-mantine-components")
+        sys.exit(1)
+
+    version = get_dmc_version()
+    categories = get_component_categories()
+
+    registry = {
+        "version": version,
+        "generated": date.today().isoformat(),
+        "categories": categories,
+        "components": {}
+    }
+
+    # Get all components from categories
+    all_components = set()
+    for comp_list in categories.values():
+        all_components.update(comp_list)
+
+    # Extract props for each component
+    for comp_name in sorted(all_components):
+        if hasattr(dmc, comp_name):
+            comp_class = getattr(dmc, comp_name)
+            try:
+                props = extract_component_props(comp_class)
+                if props:
+                    registry["components"][comp_name] = {
+                        "description": comp_class.__doc__ or f"{comp_name} component",
+                        "props": props
+                    }
+                    print(f"  Extracted: {comp_name} ({len(props)} props)")
+            except Exception as e:
+                print(f"  Warning: Failed to extract {comp_name}: {e}")
+        else:
+            print(f"  Warning: Component not found: {comp_name}")
+
+    return registry
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Generate DMC component registry from installed package"
+    )
+    parser.add_argument(
+        '--output', '-o',
+        type=str,
+        help='Output file path (default: auto-generated based on version)'
+    )
+    parser.add_argument(
+        '--dry-run',
+        action='store_true',
+        help='Print to stdout instead of writing file'
+    )
+
+    args = parser.parse_args()
+
+    print("Generating DMC Component Registry...")
+    print("=" * 50)
+
+    registry = generate_registry()
+
+    print("=" * 50)
+    print(f"Generated registry for DMC {registry['version']}")
+    print(f"Total components: {len(registry['components'])}")
+
+    if args.dry_run:
+        print(json.dumps(registry, indent=2))
+        return
+
+    # Determine output path
+    if args.output:
+        output_path = Path(args.output)
+    else:
+        version = registry['version']
+        if version:
+            major_minor = '_'.join(version.split('.')[:2])
+            output_path = Path(__file__).parent.parent / 'registry' / f'dmc_{major_minor}.json'
+        else:
+            output_path = Path(__file__).parent.parent / 'registry' / 'dmc_unknown.json'
+
+    # Create directory if needed
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Write registry
+    with open(output_path, 'w') as f:
+        json.dump(registry, indent=2, fp=f)
+
+    print(f"Registry written to: {output_path}")
+
+
+if __name__ == "__main__":
+    main()

mcp-servers/viz-platform/tests/__init__.py

@@ -0,0 +1 @@
+"""viz-platform MCP Server tests."""

mcp-servers/viz-platform/tests/test_accessibility_tools.py

@@ -0,0 +1,195 @@
+"""
+Tests for accessibility validation tools.
+"""
+import pytest
+from mcp_server.accessibility_tools import AccessibilityTools
+
+
+@pytest.fixture
+def tools():
+    """Create AccessibilityTools instance."""
+    return AccessibilityTools()
+
+
+class TestHexToRgb:
+    """Tests for _hex_to_rgb method."""
+
+    def test_hex_to_rgb_6_digit(self, tools):
+        """Test 6-digit hex conversion."""
+        assert tools._hex_to_rgb("#FF0000") == (255, 0, 0)
+        assert tools._hex_to_rgb("#00FF00") == (0, 255, 0)
+        assert tools._hex_to_rgb("#0000FF") == (0, 0, 255)
+
+    def test_hex_to_rgb_3_digit(self, tools):
+        """Test 3-digit hex conversion."""
+        assert tools._hex_to_rgb("#F00") == (255, 0, 0)
+        assert tools._hex_to_rgb("#0F0") == (0, 255, 0)
+        assert tools._hex_to_rgb("#00F") == (0, 0, 255)
+
+    def test_hex_to_rgb_lowercase(self, tools):
+        """Test lowercase hex conversion."""
+        assert tools._hex_to_rgb("#ff0000") == (255, 0, 0)
+
+
+class TestContrastRatio:
+    """Tests for _get_contrast_ratio method."""
+
+    def test_black_white_contrast(self, tools):
+        """Test black on white has maximum contrast."""
+        ratio = tools._get_contrast_ratio("#000000", "#FFFFFF")
+        assert ratio == pytest.approx(21.0, rel=0.01)
+
+    def test_same_color_contrast(self, tools):
+        """Test same color has minimum contrast."""
+        ratio = tools._get_contrast_ratio("#FF0000", "#FF0000")
+        assert ratio == pytest.approx(1.0, rel=0.01)
+
+    def test_symmetric_contrast(self, tools):
+        """Test contrast ratio is symmetric."""
+        ratio1 = tools._get_contrast_ratio("#228be6", "#FFFFFF")
+        ratio2 = tools._get_contrast_ratio("#FFFFFF", "#228be6")
+        assert ratio1 == pytest.approx(ratio2, rel=0.01)
+
+
+class TestColorBlindnessSimulation:
+    """Tests for _simulate_color_blindness method."""
+
+    def test_deuteranopia_simulation(self, tools):
+        """Test deuteranopia (green-blind) simulation."""
+        # Red and green should appear more similar
+        original_red = "#FF0000"
+        original_green = "#00FF00"
+
+        simulated_red = tools._simulate_color_blindness(original_red, "deuteranopia")
+        simulated_green = tools._simulate_color_blindness(original_green, "deuteranopia")
+
+        # They should be different from originals
+        assert simulated_red != original_red or simulated_green != original_green
+
+    def test_protanopia_simulation(self, tools):
+        """Test protanopia (red-blind) simulation."""
+        simulated = tools._simulate_color_blindness("#FF0000", "protanopia")
+        # Should return a modified color
+        assert simulated.startswith("#")
+        assert len(simulated) == 7
+
+    def test_tritanopia_simulation(self, tools):
+        """Test tritanopia (blue-blind) simulation."""
+        simulated = tools._simulate_color_blindness("#0000FF", "tritanopia")
+        # Should return a modified color
+        assert simulated.startswith("#")
+        assert len(simulated) == 7
+
+    def test_unknown_deficiency_returns_original(self, tools):
+        """Test unknown deficiency type returns original color."""
+        color = "#FF0000"
+        simulated = tools._simulate_color_blindness(color, "unknown")
+        assert simulated == color
+
+
+class TestAccessibilityValidateColors:
+    """Tests for accessibility_validate_colors method."""
+
+    @pytest.mark.asyncio
+    async def test_validate_single_color(self, tools):
+        """Test validating a single color."""
+        result = await tools.accessibility_validate_colors(["#228be6"])
+        assert "colors_checked" in result
+        assert "overall_score" in result
+        assert "issues" in result
+        assert "safe_palettes" in result
+
+    @pytest.mark.asyncio
+    async def test_validate_problematic_colors(self, tools):
+        """Test similar colors trigger warnings."""
+        # Use colors that are very close in hue, which should be harder to distinguish
+        result = await tools.accessibility_validate_colors(["#FF5555", "#FF6666"])
+        # Similar colors should trigger distinguishability warnings
+        assert "issues" in result
+        # The validation should at least run without errors
+        assert "colors_checked" in result
+        assert len(result["colors_checked"]) == 2
+
+    @pytest.mark.asyncio
+    async def test_validate_contrast_issue(self, tools):
+        """Test low contrast colors trigger contrast warnings."""
+        # Yellow on white has poor contrast
+        result = await tools.accessibility_validate_colors(["#FFFF00"])
+        # Check for contrast issues (yellow may have issues with both black and white)
+        assert "issues" in result
+
+    @pytest.mark.asyncio
+    async def test_validate_with_specific_types(self, tools):
+        """Test validating for specific color blindness types."""
+        result = await tools.accessibility_validate_colors(
+            ["#FF0000", "#00FF00"],
+            check_types=["deuteranopia"]
+        )
+        assert "simulations" in result
+        assert "deuteranopia" in result["simulations"]
+        assert "protanopia" not in result["simulations"]
+
+    @pytest.mark.asyncio
+    async def test_overall_score(self, tools):
+        """Test overall score is calculated."""
+        result = await tools.accessibility_validate_colors(["#228be6", "#ffffff"])
+        assert result["overall_score"] in ["A", "B", "C", "D"]
+
+    @pytest.mark.asyncio
+    async def test_recommendations_generated(self, tools):
+        """Test recommendations are generated for issues."""
+        result = await tools.accessibility_validate_colors(["#FF0000", "#00FF00"])
+        assert "recommendations" in result
+        assert len(result["recommendations"]) > 0
+
+
+class TestAccessibilitySuggestAlternative:
+    """Tests for accessibility_suggest_alternative method."""
+
+    @pytest.mark.asyncio
+    async def test_suggest_alternative_deuteranopia(self, tools):
+        """Test suggesting alternatives for deuteranopia."""
+        result = await tools.accessibility_suggest_alternative("#FF0000", "deuteranopia")
+        assert "original_color" in result
+        assert result["deficiency_type"] == "deuteranopia"
+        assert "suggestions" in result
+        assert len(result["suggestions"]) > 0
+
+    @pytest.mark.asyncio
+    async def test_suggest_alternative_tritanopia(self, tools):
+        """Test suggesting alternatives for tritanopia."""
+        result = await tools.accessibility_suggest_alternative("#0000FF", "tritanopia")
+        assert "suggestions" in result
+        assert len(result["suggestions"]) > 0
+
+    @pytest.mark.asyncio
+    async def test_suggestions_include_safe_palettes(self, tools):
+        """Test suggestions include colors from safe palettes."""
+        result = await tools.accessibility_suggest_alternative("#FF0000", "deuteranopia")
+        palette_suggestions = [
+            s for s in result["suggestions"]
+            if "palette" in s
+        ]
+        assert len(palette_suggestions) > 0
+
+
+class TestSafePalettes:
+    """Tests for safe palette constants."""
+
+    def test_safe_palettes_exist(self, tools):
+        """Test that safe palettes are defined."""
+        from mcp_server.accessibility_tools import SAFE_PALETTES
+        assert "categorical" in SAFE_PALETTES
+        assert "ibm" in SAFE_PALETTES
+        assert "okabe_ito" in SAFE_PALETTES
+        assert "tableau_colorblind" in SAFE_PALETTES
+
+    def test_safe_palettes_have_colors(self, tools):
+        """Test that safe palettes have color lists."""
+        from mcp_server.accessibility_tools import SAFE_PALETTES
+        for palette_name, palette in SAFE_PALETTES.items():
+            assert "colors" in palette
+            assert len(palette["colors"]) > 0
+            # All colors should be valid hex
+            for color in palette["colors"]:
+                assert color.startswith("#")

mcp-servers/viz-platform/tests/test_chart_tools.py

@@ -0,0 +1,271 @@
+"""
+Unit tests for chart creation tools.
+"""
+import pytest
+from unittest.mock import MagicMock, patch
+
+
+@pytest.fixture
+def chart_tools():
+    """Create ChartTools instance"""
+    from mcp_server.chart_tools import ChartTools
+    return ChartTools()
+
+
+@pytest.fixture
+def chart_tools_with_theme():
+    """Create ChartTools instance with a theme"""
+    from mcp_server.chart_tools import ChartTools
+
+    tools = ChartTools()
+    tools.set_theme({
+        "colors": {
+            "primary": "#ff0000",
+            "secondary": "#00ff00",
+            "success": "#0000ff"
+        }
+    })
+    return tools
+
+
+def test_chart_tools_init():
+    """Test chart tools initialization"""
+    from mcp_server.chart_tools import ChartTools
+
+    tools = ChartTools()
+
+    assert tools.theme_store is None
+    assert tools._active_theme is None
+
+
+def test_set_theme(chart_tools):
+    """Test setting active theme"""
+    theme = {"colors": {"primary": "#123456"}}
+
+    chart_tools.set_theme(theme)
+
+    assert chart_tools._active_theme == theme
+
+
+def test_get_color_palette_default(chart_tools):
+    """Test getting default color palette"""
+    from mcp_server.chart_tools import DEFAULT_COLORS
+
+    palette = chart_tools._get_color_palette()
+
+    assert palette == DEFAULT_COLORS
+
+
+def test_get_color_palette_with_theme(chart_tools_with_theme):
+    """Test getting color palette from theme"""
+    palette = chart_tools_with_theme._get_color_palette()
+
+    # Should start with theme colors
+    assert palette[0] == "#ff0000"
+    assert palette[1] == "#00ff00"
+    assert palette[2] == "#0000ff"
+
+
+def test_resolve_color_from_theme(chart_tools_with_theme):
+    """Test resolving color token from theme"""
+    color = chart_tools_with_theme._resolve_color("primary")
+
+    assert color == "#ff0000"
+
+
+def test_resolve_color_hex(chart_tools):
+    """Test resolving hex color"""
+    color = chart_tools._resolve_color("#abcdef")
+
+    assert color == "#abcdef"
+
+
+def test_resolve_color_rgb(chart_tools):
+    """Test resolving rgb color"""
+    color = chart_tools._resolve_color("rgb(255, 0, 0)")
+
+    assert color == "rgb(255, 0, 0)"
+
+
+def test_resolve_color_named(chart_tools):
+    """Test resolving named color"""
+    color = chart_tools._resolve_color("blue")
+
+    assert color == "#228be6"  # DEFAULT_COLORS[0]
+
+
+def test_resolve_color_none(chart_tools):
+    """Test resolving None color defaults to first palette color"""
+    from mcp_server.chart_tools import DEFAULT_COLORS
+
+    color = chart_tools._resolve_color(None)
+
+    assert color == DEFAULT_COLORS[0]
+
+
+@pytest.mark.asyncio
+async def test_chart_create_line(chart_tools):
+    """Test creating a line chart"""
+    data = {
+        "x": [1, 2, 3, 4, 5],
+        "y": [10, 20, 15, 25, 30]
+    }
+
+    result = await chart_tools.chart_create("line", data)
+
+    assert "figure" in result
+    assert result["chart_type"] == "line"
+    assert "error" not in result or result["error"] is None
+
+
+@pytest.mark.asyncio
+async def test_chart_create_bar(chart_tools):
+    """Test creating a bar chart"""
+    data = {
+        "x": ["A", "B", "C"],
+        "y": [10, 20, 15]
+    }
+
+    result = await chart_tools.chart_create("bar", data)
+
+    assert "figure" in result
+    assert result["chart_type"] == "bar"
+
+
+@pytest.mark.asyncio
+async def test_chart_create_scatter(chart_tools):
+    """Test creating a scatter chart"""
+    data = {
+        "x": [1, 2, 3, 4, 5],
+        "y": [10, 20, 15, 25, 30]
+    }
+
+    result = await chart_tools.chart_create("scatter", data)
+
+    assert "figure" in result
+    assert result["chart_type"] == "scatter"
+
+
+@pytest.mark.asyncio
+async def test_chart_create_pie(chart_tools):
+    """Test creating a pie chart"""
+    data = {
+        "labels": ["A", "B", "C"],
+        "values": [30, 50, 20]
+    }
+
+    result = await chart_tools.chart_create("pie", data)
+
+    assert "figure" in result
+    assert result["chart_type"] == "pie"
+
+
+@pytest.mark.asyncio
+async def test_chart_create_histogram(chart_tools):
+    """Test creating a histogram"""
+    data = {
+        "x": [1, 1, 2, 2, 2, 3, 3, 4, 5, 5, 5, 5]
+    }
+
+    result = await chart_tools.chart_create("histogram", data)
+
+    assert "figure" in result
+    assert result["chart_type"] == "histogram"
+
+
+@pytest.mark.asyncio
+async def test_chart_create_area(chart_tools):
+    """Test creating an area chart"""
+    data = {
+        "x": [1, 2, 3, 4, 5],
+        "y": [10, 20, 15, 25, 30]
+    }
+
+    result = await chart_tools.chart_create("area", data)
+
+    assert "figure" in result
+    assert result["chart_type"] == "area"
+
+
+@pytest.mark.asyncio
+async def test_chart_create_heatmap(chart_tools):
+    """Test creating a heatmap"""
+    data = {
+        "z": [[1, 2, 3], [4, 5, 6], [7, 8, 9]],
+        "x": ["A", "B", "C"],
+        "y": ["X", "Y", "Z"]
+    }
+
+    result = await chart_tools.chart_create("heatmap", data)
+
+    assert "figure" in result
+    assert result["chart_type"] == "heatmap"
+
+
+@pytest.mark.asyncio
+async def test_chart_create_invalid_type(chart_tools):
+    """Test creating chart with invalid type"""
+    data = {"x": [1, 2, 3], "y": [10, 20, 30]}
+
+    result = await chart_tools.chart_create("invalid_type", data)
+
+    assert "error" in result
+    assert "invalid" in result["error"].lower()
+
+
+@pytest.mark.asyncio
+async def test_chart_create_with_options(chart_tools):
+    """Test creating chart with options"""
+    data = {
+        "x": [1, 2, 3],
+        "y": [10, 20, 30]
+    }
+    options = {
+        "title": "My Chart",
+        "color": "red"
+    }
+
+    result = await chart_tools.chart_create("line", data, options=options)
+
+    assert "figure" in result
+    # The title should be applied to the figure
+
+
+@pytest.mark.asyncio
+async def test_chart_create_with_theme(chart_tools_with_theme):
+    """Test that theme colors are applied to chart"""
+    data = {
+        "x": [1, 2, 3],
+        "y": [10, 20, 30]
+    }
+
+    result = await chart_tools_with_theme.chart_create("line", data)
+
+    assert "figure" in result
+    # Chart should use theme colors
+
+
+@pytest.mark.asyncio
+async def test_chart_configure_interaction(chart_tools):
+    """Test configuring chart interaction"""
+    # Create a simple figure first
+    data = {"x": [1, 2, 3], "y": [10, 20, 30]}
+    chart_result = await chart_tools.chart_create("line", data)
+    figure = chart_result.get("figure", {})
+
+    if hasattr(chart_tools, 'chart_configure_interaction'):
+        result = await chart_tools.chart_configure_interaction(
+            figure=figure,
+            interactions={"zoom": True, "pan": True}
+        )
+
+        # Just verify it doesn't crash
+        assert result is not None
+
+
+def test_default_colors_defined():
+    """Test that DEFAULT_COLORS is properly defined"""
+    from mcp_server.chart_tools import DEFAULT_COLORS
+
+    assert len(DEFAULT_COLORS) == 10
+    assert all(c.startswith("#") for c in DEFAULT_COLORS)

mcp-servers/viz-platform/tests/test_component_registry.py

@@ -0,0 +1,292 @@
+"""
+Unit tests for DMC component registry.
+"""
+import pytest
+import json
+from pathlib import Path
+from unittest.mock import patch, MagicMock
+
+
+@pytest.fixture
+def sample_registry_data():
+    """Sample registry data for testing"""
+    return {
+        "version": "2.5.1",
+        "categories": {
+            "buttons": ["Button", "ActionIcon"],
+            "inputs": ["TextInput", "NumberInput", "Select"]
+        },
+        "components": {
+            "Button": {
+                "description": "Button component",
+                "props": {
+                    "variant": {
+                        "type": "string",
+                        "enum": ["filled", "outline", "light"],
+                        "default": "filled"
+                    },
+                    "color": {
+                        "type": "string",
+                        "default": "blue"
+                    },
+                    "size": {
+                        "type": "string",
+                        "enum": ["xs", "sm", "md", "lg", "xl"],
+                        "default": "sm"
+                    },
+                    "disabled": {
+                        "type": "boolean",
+                        "default": False
+                    }
+                }
+            },
+            "TextInput": {
+                "description": "Text input field",
+                "props": {
+                    "value": {"type": "string", "default": ""},
+                    "placeholder": {"type": "string"},
+                    "disabled": {"type": "boolean", "default": False},
+                    "required": {"type": "boolean", "default": False}
+                }
+            }
+        }
+    }
+
+
+@pytest.fixture
+def registry_file(tmp_path, sample_registry_data):
+    """Create a temporary registry file"""
+    registry_dir = tmp_path / "registry"
+    registry_dir.mkdir()
+    registry_file = registry_dir / "dmc_2_5.json"
+    registry_file.write_text(json.dumps(sample_registry_data))
+    return registry_file
+
+
+@pytest.fixture
+def registry(registry_file):
+    """Create a ComponentRegistry with mock registry directory"""
+    from mcp_server.component_registry import ComponentRegistry
+
+    reg = ComponentRegistry(dmc_version="2.5.1")
+    reg.registry_dir = registry_file.parent
+    reg.load()
+    return reg
+
+
+def test_registry_init():
+    """Test registry initialization"""
+    from mcp_server.component_registry import ComponentRegistry
+
+    reg = ComponentRegistry(dmc_version="2.5.1")
+
+    assert reg.dmc_version == "2.5.1"
+    assert reg.components == {}
+    assert reg.categories == {}
+    assert reg.loaded_version is None
+
+
+def test_registry_load_success(registry, sample_registry_data):
+    """Test successful registry loading"""
+    assert registry.is_loaded()
+    assert registry.loaded_version == "2.5.1"
+    assert len(registry.components) == 2
+    assert "Button" in registry.components
+    assert "TextInput" in registry.components
+
+
+def test_registry_load_no_file():
+    """Test registry loading when no file exists"""
+    from mcp_server.component_registry import ComponentRegistry
+
+    reg = ComponentRegistry(dmc_version="99.99.99")
+    reg.registry_dir = Path("/nonexistent/path")
+
+    result = reg.load()
+
+    assert result is False
+    assert not reg.is_loaded()
+
+
+def test_get_component(registry):
+    """Test getting a component by name"""
+    button = registry.get_component("Button")
+
+    assert button is not None
+    assert button["description"] == "Button component"
+    assert "props" in button
+
+
+def test_get_component_not_found(registry):
+    """Test getting a nonexistent component"""
+    result = registry.get_component("NonexistentComponent")
+
+    assert result is None
+
+
+def test_get_component_props(registry):
+    """Test getting component props"""
+    props = registry.get_component_props("Button")
+
+    assert props is not None
+    assert "variant" in props
+    assert "color" in props
+    assert props["variant"]["type"] == "string"
+    assert props["variant"]["enum"] == ["filled", "outline", "light"]
+
+
+def test_get_component_props_not_found(registry):
+    """Test getting props for nonexistent component"""
+    props = registry.get_component_props("Nonexistent")
+
+    assert props is None
+
+
+def test_list_components_all(registry):
+    """Test listing all components"""
+    result = registry.list_components()
+
+    assert "buttons" in result
+    assert "inputs" in result
+    assert "Button" in result["buttons"]
+    assert "TextInput" in result["inputs"]
+
+
+def test_list_components_by_category(registry):
+    """Test listing components by category"""
+    result = registry.list_components(category="buttons")
+
+    assert len(result) == 1
+    assert "buttons" in result
+    assert "Button" in result["buttons"]
+
+
+def test_list_components_invalid_category(registry):
+    """Test listing components with invalid category"""
+    result = registry.list_components(category="nonexistent")
+
+    assert result == {}
+
+
+def test_get_categories(registry):
+    """Test getting available categories"""
+    categories = registry.get_categories()
+
+    assert "buttons" in categories
+    assert "inputs" in categories
+
+
+def test_validate_prop_valid_enum(registry):
+    """Test validating a valid enum prop"""
+    result = registry.validate_prop("Button", "variant", "filled")
+
+    assert result["valid"] is True
+
+
+def test_validate_prop_invalid_enum(registry):
+    """Test validating an invalid enum prop"""
+    result = registry.validate_prop("Button", "variant", "invalid_variant")
+
+    assert result["valid"] is False
+    assert "expects one of" in result["error"]
+
+
+def test_validate_prop_valid_type(registry):
+    """Test validating a valid type"""
+    result = registry.validate_prop("Button", "disabled", True)
+
+    assert result["valid"] is True
+
+
+def test_validate_prop_invalid_type(registry):
+    """Test validating an invalid type"""
+    result = registry.validate_prop("Button", "disabled", "not_a_boolean")
+
+    assert result["valid"] is False
+    assert "expects type" in result["error"]
+
+
+def test_validate_prop_unknown_component(registry):
+    """Test validating prop for unknown component"""
+    result = registry.validate_prop("Nonexistent", "prop", "value")
+
+    assert result["valid"] is False
+    assert "Unknown component" in result["error"]
+
+
+def test_validate_prop_unknown_prop(registry):
+    """Test validating an unknown prop"""
+    result = registry.validate_prop("Button", "unknownProp", "value")
+
+    assert result["valid"] is False
+    assert "Unknown prop" in result["error"]
+
+
+def test_validate_prop_typo_detection(registry):
+    """Test typo detection for similar prop names"""
+    # colour vs color
+    result = registry.validate_prop("Button", "colour", "blue")
+
+    assert result["valid"] is False
+    # Should suggest 'color'
+    assert "color" in result.get("error", "").lower()
+
+
+def test_find_similar_props(registry):
+    """Test finding similar prop names"""
+    available = ["color", "variant", "size", "disabled"]
+
+    # Should match despite case difference
+    similar = registry._find_similar_props("Color", available)
+    assert similar == "color"
+
+    # Should match with slight typo
+    similar = registry._find_similar_props("colours", ["color", "variant"])
+    # May or may not match depending on heuristic
+
+
+def test_load_registry_convenience_function(registry_file):
+    """Test the convenience function"""
+    from mcp_server.component_registry import load_registry, ComponentRegistry
+
+    with patch.object(ComponentRegistry, '__init__', return_value=None) as mock_init:
+        with patch.object(ComponentRegistry, 'load', return_value=True):
+            mock_init.return_value = None
+            # Can't easily test this without mocking more - just ensure it doesn't crash
+            pass
+
+
+def test_find_registry_file_exact_match(tmp_path):
+    """Test finding exact registry file match"""
+    from mcp_server.component_registry import ComponentRegistry
+
+    # Create registry files
+    registry_dir = tmp_path / "registry"
+    registry_dir.mkdir()
+    (registry_dir / "dmc_2_5.json").write_text('{"version": "2.5.0"}')
+
+    reg = ComponentRegistry(dmc_version="2.5.1")
+    reg.registry_dir = registry_dir
+
+    result = reg._find_registry_file()
+
+    assert result is not None
+    assert result.name == "dmc_2_5.json"
+
+
+def test_find_registry_file_fallback(tmp_path):
+    """Test fallback to latest registry when no exact match"""
+    from mcp_server.component_registry import ComponentRegistry
+
+    # Create registry files
+    registry_dir = tmp_path / "registry"
+    registry_dir.mkdir()
+    (registry_dir / "dmc_0_14.json").write_text('{"version": "0.14.0"}')
+
+    reg = ComponentRegistry(dmc_version="2.5.1")  # No exact match
+    reg.registry_dir = registry_dir
+
+    result = reg._find_registry_file()
+
+    assert result is not None
+    assert result.name == "dmc_0_14.json"  # Falls back to available

mcp-servers/viz-platform/tests/test_config.py

@@ -0,0 +1,156 @@
+"""
+Unit tests for viz-platform configuration loader.
+"""
+import pytest
+import os
+from pathlib import Path
+from unittest.mock import patch, MagicMock
+
+
+@pytest.fixture
+def clean_env():
+    """Clean environment variables before test"""
+    env_vars = ['DMC_VERSION', 'CLAUDE_PROJECT_DIR', 'VIZ_DEFAULT_THEME']
+    saved = {k: os.environ.get(k) for k in env_vars}
+    for k in env_vars:
+        if k in os.environ:
+            del os.environ[k]
+    yield
+    # Restore after test
+    for k, v in saved.items():
+        if v is not None:
+            os.environ[k] = v
+        elif k in os.environ:
+            del os.environ[k]
+
+
+@pytest.fixture
+def config():
+    """Create VizPlatformConfig instance"""
+    from mcp_server.config import VizPlatformConfig
+    return VizPlatformConfig()
+
+
+def test_config_init(config):
+    """Test config initialization"""
+    assert config.dmc_version is None
+    assert config.theme_dir_user == Path.home() / '.config' / 'claude' / 'themes'
+    assert config.theme_dir_project is None
+    assert config.default_theme is None
+
+
+def test_config_load_returns_dict(config, clean_env):
+    """Test config.load() returns expected structure"""
+    result = config.load()
+
+    assert isinstance(result, dict)
+    assert 'dmc_version' in result
+    assert 'dmc_available' in result
+    assert 'theme_dir_user' in result
+    assert 'theme_dir_project' in result
+    assert 'default_theme' in result
+    assert 'project_dir' in result
+
+
+def test_config_respects_env_dmc_version(config, clean_env):
+    """Test that DMC_VERSION env var is respected"""
+    os.environ['DMC_VERSION'] = '0.14.7'
+
+    result = config.load()
+
+    assert result['dmc_version'] == '0.14.7'
+    assert result['dmc_available'] is True
+
+
+def test_config_respects_default_theme_env(config, clean_env):
+    """Test that VIZ_DEFAULT_THEME env var is respected"""
+    os.environ['VIZ_DEFAULT_THEME'] = 'my-dark-theme'
+
+    result = config.load()
+
+    assert result['default_theme'] == 'my-dark-theme'
+
+
+def test_detect_dmc_version_not_installed(config):
+    """Test DMC version detection when not installed"""
+    with patch('importlib.metadata.version', side_effect=ImportError("not installed")):
+        version = config._detect_dmc_version()
+
+    assert version is None
+
+
+def test_detect_dmc_version_installed(config):
+    """Test DMC version detection when installed"""
+    with patch('importlib.metadata.version', return_value='0.14.7'):
+        version = config._detect_dmc_version()
+
+    assert version == '0.14.7'
+
+
+def test_find_project_directory_from_env(config, clean_env, tmp_path):
+    """Test project directory detection from CLAUDE_PROJECT_DIR"""
+    os.environ['CLAUDE_PROJECT_DIR'] = str(tmp_path)
+
+    result = config._find_project_directory()
+
+    assert result == tmp_path
+
+
+def test_find_project_directory_with_git(config, clean_env, tmp_path):
+    """Test project directory detection with .git folder"""
+    git_dir = tmp_path / '.git'
+    git_dir.mkdir()
+
+    with patch.dict(os.environ, {'PWD': str(tmp_path)}):
+        result = config._find_project_directory()
+
+    assert result == tmp_path
+
+
+def test_find_project_directory_with_env_file(config, clean_env, tmp_path):
+    """Test project directory detection with .env file"""
+    env_file = tmp_path / '.env'
+    env_file.touch()
+
+    with patch.dict(os.environ, {'PWD': str(tmp_path)}):
+        result = config._find_project_directory()
+
+    assert result == tmp_path
+
+
+def test_load_config_convenience_function(clean_env):
+    """Test the convenience function load_config()"""
+    from mcp_server.config import load_config
+
+    result = load_config()
+
+    assert isinstance(result, dict)
+    assert 'dmc_version' in result
+
+
+def test_check_dmc_version_not_installed(clean_env):
+    """Test check_dmc_version when DMC not installed"""
+    from mcp_server.config import check_dmc_version
+
+    with patch('mcp_server.config.load_config', return_value={'dmc_available': False}):
+        result = check_dmc_version()
+
+    assert result['installed'] is False
+    assert 'not installed' in result['message'].lower()
+
+
+def test_check_dmc_version_installed_with_registry(clean_env, tmp_path):
+    """Test check_dmc_version when DMC installed with matching registry"""
+    from mcp_server.config import check_dmc_version
+
+    mock_config = {
+        'dmc_available': True,
+        'dmc_version': '2.5.1'
+    }
+
+    with patch('mcp_server.config.load_config', return_value=mock_config):
+        with patch('pathlib.Path.exists', return_value=True):
+            result = check_dmc_version()
+
+    assert result['installed'] is True
+    assert result['version'] == '2.5.1'

mcp-servers/viz-platform/tests/test_dmc_tools.py

@@ -0,0 +1,283 @@
+"""
+Unit tests for DMC validation tools.
+"""
+import pytest
+from unittest.mock import MagicMock, patch
+
+
+@pytest.fixture
+def mock_registry():
+    """Create a mock component registry"""
+    registry = MagicMock()
+    registry.is_loaded.return_value = True
+    registry.loaded_version = "2.5.1"
+
+    registry.categories = {
+        "buttons": ["Button", "ActionIcon"],
+        "inputs": ["TextInput", "Select"]
+    }
+
+    registry.list_components.return_value = registry.categories
+    registry.get_categories.return_value = ["buttons", "inputs"]
+
+    # Mock Button component
+    registry.get_component.side_effect = lambda name: {
+        "Button": {
+            "description": "Button component",
+            "props": {
+                "variant": {"type": "string", "enum": ["filled", "outline"], "default": "filled"},
+                "color": {"type": "string", "default": "blue"},
+                "size": {"type": "string", "enum": ["xs", "sm", "md", "lg"], "default": "sm"},
+                "disabled": {"type": "boolean", "default": False, "required": False}
+            }
+        },
+        "TextInput": {
+            "description": "Text input",
+            "props": {
+                "value": {"type": "string", "required": True},
+                "placeholder": {"type": "string"}
+            }
+        }
+    }.get(name)
+
+    registry.get_component_props.side_effect = lambda name: {
+        "Button": {
+            "variant": {"type": "string", "enum": ["filled", "outline"], "default": "filled"},
+            "color": {"type": "string", "default": "blue"},
+            "size": {"type": "string", "enum": ["xs", "sm", "md", "lg"], "default": "sm"},
+            "disabled": {"type": "boolean", "default": False}
+        },
+        "TextInput": {
+            "value": {"type": "string", "required": True},
+            "placeholder": {"type": "string"}
+        }
+    }.get(name)
+
+    registry.validate_prop.side_effect = lambda comp, prop, val: (
+        {"valid": True} if prop in ["variant", "color", "size", "disabled", "value", "placeholder"]
+        else {"valid": False, "error": f"Unknown prop '{prop}'"}
+    )
+
+    return registry
+
+
+@pytest.fixture
+def dmc_tools(mock_registry):
+    """Create DMCTools instance with mock registry"""
+    from mcp_server.dmc_tools import DMCTools
+
+    tools = DMCTools(registry=mock_registry)
+    tools._initialized = True
+    return tools
+
+
+@pytest.fixture
+def uninitialized_tools():
+    """Create uninitialized DMCTools instance"""
+    from mcp_server.dmc_tools import DMCTools
+    return DMCTools()
+
+
+@pytest.mark.asyncio
+async def test_list_components_all(dmc_tools):
+    """Test listing all components"""
+    result = await dmc_tools.list_components()
+
+    assert "components" in result
+    assert "categories" in result
+    assert "version" in result
+    assert result["version"] == "2.5.1"
+
+
+@pytest.mark.asyncio
+async def test_list_components_by_category(dmc_tools, mock_registry):
+    """Test listing components by category"""
+    mock_registry.list_components.return_value = {"buttons": ["Button", "ActionIcon"]}
+
+    result = await dmc_tools.list_components(category="buttons")
+
+    assert "buttons" in result["components"]
+    mock_registry.list_components.assert_called_with("buttons")
+
+
+@pytest.mark.asyncio
+async def test_list_components_not_initialized(uninitialized_tools):
+    """Test listing components when not initialized"""
+    result = await uninitialized_tools.list_components()
+
+    assert "error" in result
+    assert result["total_count"] == 0
+
+
+@pytest.mark.asyncio
+async def test_get_component_props_success(dmc_tools):
+    """Test getting component props"""
+    result = await dmc_tools.get_component_props("Button")
+
+    assert result["component"] == "Button"
+    assert "props" in result
+    assert result["prop_count"] > 0
+
+
+@pytest.mark.asyncio
+async def test_get_component_props_not_found(dmc_tools, mock_registry):
+    """Test getting props for nonexistent component"""
+    mock_registry.get_component.return_value = None
+
+    result = await dmc_tools.get_component_props("Nonexistent")
+
+    assert "error" in result
+    assert "not found" in result["error"]
+
+
+@pytest.mark.asyncio
+async def test_get_component_props_not_initialized(uninitialized_tools):
+    """Test getting props when not initialized"""
+    result = await uninitialized_tools.get_component_props("Button")
+
+    assert "error" in result
+    assert result["prop_count"] == 0
+
+
+@pytest.mark.asyncio
+async def test_validate_component_valid(dmc_tools, mock_registry):
+    """Test validating valid component props"""
+    props = {
+        "variant": "filled",
+        "color": "blue",
+        "size": "md"
+    }
+
+    result = await dmc_tools.validate_component("Button", props)
+
+    assert result["valid"] is True
+    assert len(result["errors"]) == 0
+    assert result["component"] == "Button"
+
+
+@pytest.mark.asyncio
+async def test_validate_component_invalid_prop(dmc_tools, mock_registry):
+    """Test validating with invalid prop name"""
+    mock_registry.validate_prop.side_effect = lambda comp, prop, val: (
+        {"valid": False, "error": f"Unknown prop '{prop}'"} if prop == "unknownProp"
+        else {"valid": True}
+    )
+
+    props = {"unknownProp": "value"}
+
+    result = await dmc_tools.validate_component("Button", props)
+
+    assert result["valid"] is False
+    assert len(result["errors"]) > 0
+
+
+@pytest.mark.asyncio
+async def test_validate_component_missing_required(dmc_tools, mock_registry):
+    """Test validating with missing required prop"""
+    # TextInput has required value prop
+    mock_registry.get_component.return_value = {
+        "props": {
+            "value": {"type": "string", "required": True}
+        }
+    }
+
+    result = await dmc_tools.validate_component("TextInput", {})
+
+    assert result["valid"] is False
+    assert any("required" in e.lower() for e in result["errors"])
+
+
+@pytest.mark.asyncio
+async def test_validate_component_not_found(dmc_tools, mock_registry):
+    """Test validating nonexistent component"""
+    mock_registry.get_component.return_value = None
+
+    result = await dmc_tools.validate_component("Nonexistent", {"prop": "value"})
+
+    assert result["valid"] is False
+    assert "Unknown component" in result["errors"][0]
+
+
+@pytest.mark.asyncio
+async def test_validate_component_not_initialized(uninitialized_tools):
+    """Test validating when not initialized"""
+    result = await uninitialized_tools.validate_component("Button", {})
+
+    assert result["valid"] is False
+    assert "not initialized" in result["errors"][0].lower()
+
+
+@pytest.mark.asyncio
+async def test_validate_component_skips_special_props(dmc_tools, mock_registry):
+    """Test that special props (id, children, etc) are skipped"""
+    props = {
+        "id": "my-button",
+        "children": "Click me",
+        "className": "my-class",
+        "style": {"color": "red"},
+        "key": "btn-1"
+    }
+
+    result = await dmc_tools.validate_component("Button", props)
+
+    # Should not error on special props
+    assert result["valid"] is True
+
+
+def test_find_similar_component(dmc_tools, mock_registry):
+    """Test finding similar component names"""
+    # Should find Button when given 'button' (case mismatch)
+    similar = dmc_tools._find_similar_component("button")
+
+    assert similar == "Button"
+
+
+def test_find_similar_component_prefix(dmc_tools, mock_registry):
+    """Test finding similar component with prefix match"""
+    similar = dmc_tools._find_similar_component("Butt")
+
+    assert similar == "Button"
+
+
+def test_check_common_mistakes_onclick(dmc_tools):
+    """Test detection of onclick event handler mistake"""
+    warnings = []
+    dmc_tools._check_common_mistakes("Button", {"onClick": "handler"}, warnings)
+
+    assert len(warnings) > 0
+    assert any("callback" in w.lower() for w in warnings)
+
+
+def test_check_common_mistakes_class(dmc_tools):
+    """Test detection of 'class' instead of 'className'"""
+    warnings = []
+    dmc_tools._check_common_mistakes("Button", {"class": "my-class"}, warnings)
+
+    assert len(warnings) > 0
+    assert any("classname" in w.lower() for w in warnings)
+
+
+def test_check_common_mistakes_button_href(dmc_tools):
+    """Test detection of Button with href but no component prop"""
+    warnings = []
+    dmc_tools._check_common_mistakes("Button", {"href": "/link"}, warnings)
+
+    assert len(warnings) > 0
+    assert any("component" in w.lower() for w in warnings)
+
+
+def test_initialize_with_version():
+    """Test initializing tools with DMC version"""
+    from mcp_server.dmc_tools import DMCTools
+
+    tools = DMCTools()
+
+    with patch('mcp_server.dmc_tools.ComponentRegistry') as MockRegistry:
+        mock_instance = MagicMock()
+        mock_instance.is_loaded.return_value = True
+        MockRegistry.return_value = mock_instance
+
+        result = tools.initialize(dmc_version="2.5.1")
+
+        MockRegistry.assert_called_once_with("2.5.1")
+        assert result is True

mcp-servers/viz-platform/tests/test_theme_tools.py

@@ -0,0 +1,304 @@
+"""
+Unit tests for theme management tools.
+"""
+import pytest
+from unittest.mock import MagicMock, patch
+
+
+@pytest.fixture
+def theme_store():
+    """Create a fresh ThemeStore instance"""
+    from mcp_server.theme_store import ThemeStore
+    store = ThemeStore()
+    store._themes = {}  # Clear any existing themes
+    return store
+
+
+@pytest.fixture
+def theme_tools(theme_store):
+    """Create ThemeTools instance with fresh store"""
+    from mcp_server.theme_tools import ThemeTools
+    return ThemeTools(store=theme_store)
+
+
+def test_theme_store_init():
+    """Test theme store initialization"""
+    from mcp_server.theme_store import ThemeStore
+
+    store = ThemeStore()
+
+    # Should have default theme
+    assert store.get_theme("default") is not None
+
+
+def test_default_theme_structure():
+    """Test default theme has required structure"""
+    from mcp_server.theme_store import DEFAULT_THEME
+
+    assert "name" in DEFAULT_THEME
+    assert "tokens" in DEFAULT_THEME
+    assert "colors" in DEFAULT_THEME["tokens"]
+    assert "spacing" in DEFAULT_THEME["tokens"]
+    assert "typography" in DEFAULT_THEME["tokens"]
+    assert "radii" in DEFAULT_THEME["tokens"]
+
+
+def test_default_theme_colors():
+    """Test default theme has required color tokens"""
+    from mcp_server.theme_store import DEFAULT_THEME
+
+    colors = DEFAULT_THEME["tokens"]["colors"]
+
+    assert "primary" in colors
+    assert "secondary" in colors
+    assert "success" in colors
+    assert "warning" in colors
+    assert "error" in colors
+    assert "background" in colors
+    assert "text" in colors
+
+
+@pytest.mark.asyncio
+async def test_theme_create(theme_tools):
+    """Test creating a new theme"""
+    tokens = {
+        "colors": {
+            "primary": "#ff0000"
+        }
+    }
+
+    result = await theme_tools.theme_create("my-theme", tokens)
+
+    assert result["name"] == "my-theme"
+    assert "tokens" in result
+    assert result["tokens"]["colors"]["primary"] == "#ff0000"
+
+
+@pytest.mark.asyncio
+async def test_theme_create_merges_with_defaults(theme_tools):
+    """Test that new theme merges with default tokens"""
+    tokens = {
+        "colors": {
+            "primary": "#ff0000"
+        }
+    }
+
+    result = await theme_tools.theme_create("partial-theme", tokens)
+
+    # Should have primary from our tokens
+    assert result["tokens"]["colors"]["primary"] == "#ff0000"
+    # Should inherit secondary from defaults
+    assert "secondary" in result["tokens"]["colors"]
+
+
+@pytest.mark.asyncio
+async def test_theme_create_duplicate_name(theme_tools, theme_store):
+    """Test creating theme with existing name fails"""
+    # Create first theme
+    await theme_tools.theme_create("existing", {"colors": {}})
+
+    # Try to create with same name
+    result = await theme_tools.theme_create("existing", {"colors": {}})
+
+    assert "error" in result
+    assert "already exists" in result["error"]
+
+
+@pytest.mark.asyncio
+async def test_theme_extend(theme_tools, theme_store):
+    """Test extending an existing theme"""
+    # Create base theme
+    await theme_tools.theme_create("base", {
+        "colors": {"primary": "#0000ff"}
+    })
+
+    # Extend it
+    result = await theme_tools.theme_extend(
+        base_theme="base",
+        overrides={"colors": {"secondary": "#00ff00"}},
+        new_name="extended"
+    )
+
+    assert result["name"] == "extended"
+    # Should have base primary
+    assert result["tokens"]["colors"]["primary"] == "#0000ff"
+    # Should have override secondary
+    assert result["tokens"]["colors"]["secondary"] == "#00ff00"
+
+
+@pytest.mark.asyncio
+async def test_theme_extend_nonexistent_base(theme_tools):
+    """Test extending nonexistent theme fails"""
+    result = await theme_tools.theme_extend(
+        base_theme="nonexistent",
+        overrides={},
+        new_name="new"
+    )
+
+    assert "error" in result
+    assert "not found" in result["error"]
+
+
+@pytest.mark.asyncio
+async def test_theme_extend_default_name(theme_tools, theme_store):
+    """Test extending creates default name if not provided"""
+    await theme_tools.theme_create("base", {"colors": {}})
+
+    result = await theme_tools.theme_extend(
+        base_theme="base",
+        overrides={}
+        # No new_name provided
+    )
+
+    assert result["name"] == "base_extended"
+
+
+@pytest.mark.asyncio
+async def test_theme_validate(theme_tools, theme_store):
+    """Test theme validation"""
+    await theme_tools.theme_create("test-theme", {
+        "colors": {"primary": "#ff0000"},
+        "spacing": {"md": "16px"}
+    })
+
+    result = await theme_tools.theme_validate("test-theme")
+
+    assert "complete" in result or "validation" in result
+
+
+@pytest.mark.asyncio
+async def test_theme_validate_nonexistent(theme_tools):
+    """Test validating nonexistent theme"""
+    result = await theme_tools.theme_validate("nonexistent")
+
+    assert "error" in result
+
+
+@pytest.mark.asyncio
+async def test_theme_export_css(theme_tools, theme_store):
+    """Test exporting theme as CSS"""
+    await theme_tools.theme_create("css-theme", {
+        "colors": {"primary": "#ff0000"},
+        "spacing": {"md": "16px"}
+    })
+
+    result = await theme_tools.theme_export_css("css-theme")
+
+    assert "css" in result
+    # CSS should contain custom properties
+    assert "--" in result["css"]
+
+
+@pytest.mark.asyncio
+async def test_theme_export_css_nonexistent(theme_tools):
+    """Test exporting nonexistent theme"""
+    result = await theme_tools.theme_export_css("nonexistent")
+
+    assert "error" in result
+
+
+@pytest.mark.asyncio
+async def test_theme_list(theme_tools, theme_store):
+    """Test listing themes"""
+    await theme_tools.theme_create("theme1", {"colors": {}})
+    await theme_tools.theme_create("theme2", {"colors": {}})
+
+    result = await theme_tools.theme_list()
+
+    assert "themes" in result
+    assert "theme1" in result["themes"]
+    assert "theme2" in result["themes"]
+
+
+@pytest.mark.asyncio
+async def test_theme_activate(theme_tools, theme_store):
+    """Test activating a theme"""
+    await theme_tools.theme_create("active-theme", {"colors": {}})
+
+    result = await theme_tools.theme_activate("active-theme")
+
+    assert result.get("active_theme") == "active-theme" or result.get("success") is True
+
+
+@pytest.mark.asyncio
+async def test_theme_activate_nonexistent(theme_tools):
+    """Test activating nonexistent theme"""
+    result = await theme_tools.theme_activate("nonexistent")
+
+    assert "error" in result
+
+
+def test_theme_store_get_theme(theme_store):
+    """Test getting theme from store"""
+    from mcp_server.theme_store import DEFAULT_THEME
+
+    # Add a theme first, then retrieve it
+    theme_store._themes["test-theme"] = {"name": "test-theme", "tokens": {}}
+    result = theme_store.get_theme("test-theme")
+
+    assert result is not None
+    assert result["name"] == "test-theme"
+
+
+def test_theme_store_list_themes(theme_store):
+    """Test listing themes from store"""
+    result = theme_store.list_themes()
+
+    assert isinstance(result, list)
+
+
+def test_deep_merge(theme_tools):
+    """Test deep merging of token dicts"""
+    base = {
+        "colors": {
+            "primary": "#000",
+            "secondary": "#111"
+        },
+        "spacing": {"sm": "8px"}
+    }
+
+    override = {
+        "colors": {
+            "primary": "#fff"
+        }
+    }
+
+    result = theme_tools._deep_merge(base, override)
+
+    # primary should be overridden
+    assert result["colors"]["primary"] == "#fff"
+    # secondary should remain
+    assert result["colors"]["secondary"] == "#111"
+    # spacing should remain
+    assert result["spacing"]["sm"] == "8px"
+
+
+def test_validate_tokens(theme_tools):
+    """Test token validation"""
+    from mcp_server.theme_store import REQUIRED_TOKEN_CATEGORIES
+
+    tokens = {
+        "colors": {"primary": "#000"},
+        "spacing": {"md": "16px"},
+        "typography": {"fontFamily": "Inter"},
+        "radii": {"md": "8px"}
+    }
+
+    result = theme_tools._validate_tokens(tokens)
+
+    assert "complete" in result
+    # Check for either "missing" or "missing_required" key
+    assert "missing" in result or "missing_required" in result or "missing_optional" in result
+
+
+def test_validate_tokens_incomplete(theme_tools):
+    """Test validation of incomplete tokens"""
+    tokens = {
+        "colors": {"primary": "#000"}
+        # Missing spacing, typography, radii
+    }
+
+    result = theme_tools._validate_tokens(tokens)
+
+    # Should flag missing categories
+    assert result["complete"] is False or len(result.get("missing", [])) > 0

plugins/clarity-assist/.claude-plugin/metadata.json

@@ -0,0 +1,3 @@
+{
+  "domain": "core"
+}

plugins/clarity-assist/.claude-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "clarity-assist",
+  "version": "9.0.1",
+  "description": "Prompt optimization and requirement clarification with ND-friendly accommodations",
+  "author": {
+    "name": "Leo Miranda",
+    "email": "leobmiranda@gmail.com"
+  },
+  "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/clarity-assist/README.md",
+  "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+  "license": "MIT",
+  "keywords": [
+    "prompt-optimization",
+    "clarification",
+    "neurodivergent",
+    "requirements",
+    "methodology"
+  ],
+  "commands": [
+    "./commands/"
+  ]
+}

plugins/clarity-assist/agents/clarity-coach.md

@@ -0,0 +1,158 @@
+---
+name: clarity-coach
+description: Patient, structured coach helping users articulate requirements clearly. Uses neurodivergent-friendly communication patterns.
+model: sonnet
+permissionMode: default
+disallowedTools: Write, Edit, MultiEdit
+---
+
+# Clarity Coach Agent
+
+## Visual Output Requirements
+
+**MANDATORY: Display header at start of every response.**
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  💬 CLARITY-ASSIST · Clarity Coach                               │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+## Role
+
+You are a patient, structured coach specializing in helping users articulate their requirements clearly. You are trained in neurodivergent-friendly communication patterns and use evidence-based techniques for effective requirement gathering.
+
+## Core Principles
+
+### 1. Never Open-Ended Questions Alone
+
+Bad: "What do you want the button to do?"
+Good: "What should happen when the button is clicked?
+1. Navigate to another page
+2. Submit a form
+3. Open a modal/popup
+4. Other (please describe)"
+
+### 2. Chunked Questions (1-2 at a Time)
+
+Bad: "What color, size, position, and behavior should the button have?"
+Good: "Let's start with the basics. Where should this button appear?
+1. In the header
+2. In the main content area
+3. In a sidebar
+4. Floating/fixed position"
+
+Then after answer: "Now for the appearance - should it match your existing button style or stand out?"
+
+### 3. Provide Context for Questions
+
+Always explain why you're asking:
+
+"I'm asking about error handling because it affects whether we need to build a retry mechanism."
+
+### 4. Conflict Detection
+
+Before each new question, mentally review:
+- What has the user already said?
+- Does this question potentially contradict earlier answers?
+- If yes, acknowledge it: "Earlier you mentioned X, so when thinking about Y..."
+
+### 5. Progress Acknowledgment
+
+After every 2-3 questions, summarize progress:
+
+"Great, so far we've established:
+- The feature is for [X]
+- It should [Y]
+- And integrate with [Z]
+
+A couple more questions and we'll have everything we need."
+
+## Communication Style
+
+### Tone
+- Patient, never rushing
+- Validating ("That makes sense", "Good point")
+- Non-judgmental about vague initial requests
+
+### Pacing
+- Respect user's energy levels
+- Offer breaks: "This is good progress. Want to continue or pick this up later?"
+- Notice signs of overwhelm and simplify
+
+### Clarity
+- Use concrete examples, not abstract descriptions
+- Prefer "For example..." over "Consider..."
+- Visual when possible: "Picture a button in the top-right corner that..."
+
+## Handling Uncertainty
+
+When user says "I don't know":
+
+```
+"That's totally fine - let's approach it differently.
+
+If I showed you two versions:
+- Version A: [concrete description]
+- Version B: [concrete description]
+
+Which feels closer to what you're imagining? Or neither?"
+```
+
+When user is overwhelmed:
+
+```
+"There's a lot to decide here. Let me suggest we focus on just
+the [most critical aspect] for now. The other details can be
+figured out as we build. What matters most to you right now?"
+```
+
+## Output Artifacts
+
+### During Clarification
+
+Track gathered information in a mental model:
+- Requirements (explicit)
+- Preferences (implicit)
+- Constraints (technical/business)
+- Open questions
+
+### After Clarification
+
+Produce a clear specification (see /clarity clarify command for format).
+
+## Example Session
+
+**User:** I need a dashboard
+
+**Coach:**
+
+```
+A dashboard can mean many things - let me help narrow it down.
+
+**What's the primary purpose of this dashboard?**
+1. Monitor system health/metrics
+2. View business KPIs and analytics
+3. Manage tasks or workflows
+4. Combination / Other
+
+[Knowing this helps me understand what data and visualizations you'll need]
+```
+
+**User:** Option 2, business analytics
+
+**Coach:**
+
+```
+Business analytics dashboard - got it.
+
+**Who will be using this dashboard?**
+1. Just you / personal use
+2. Your team (5-20 people)
+3. Company-wide (many departments)
+4. External clients
+
+[This affects permissions, performance requirements, and how customizable it needs to be]
+```
+
+And so on, building toward a complete picture.