diff --git a/README.md b/README.md index 7c7fc29..77a260b 100644 --- a/README.md +++ b/README.md @@ -53,6 +53,19 @@ Analyze, optimize, and create CLAUDE.md configuration files for Claude Code proj **Commands:** `/config-analyze`, `/config-optimize`, `/config-init` +#### [contract-validator](./plugins/contract-validator/README.md) *NEW in v5.0.0* +**Cross-Plugin Compatibility Validation** + +Validate plugin marketplaces for command conflicts, tool overlaps, and broken agent references. + +- Interface parsing from plugin README.md files +- Agent extraction from CLAUDE.md definitions +- Pairwise compatibility checks between all plugins +- Data flow validation for agent sequences +- Markdown or JSON reports with actionable suggestions + +**Commands:** `/validate-contracts`, `/check-agent`, `/list-interfaces`, `/initial-setup` + ### Productivity #### [clarity-assist](./plugins/clarity-assist/README.md) *NEW in v3.0.0* @@ -98,7 +111,7 @@ Full CRUD operations for network infrastructure management directly from Claude ### Data Engineering -#### [data-platform](./plugins/data-platform/README.md) *NEW* +#### [data-platform](./plugins/data-platform/README.md) *NEW in v4.0.0* **pandas, PostgreSQL/PostGIS, and dbt Integration** Comprehensive data engineering toolkit with persistent DataFrame storage. @@ -113,7 +126,7 @@ Comprehensive data engineering toolkit with persistent DataFrame storage. ### Visualization -#### [viz-platform](./plugins/viz-platform/README.md) *NEW* +#### [viz-platform](./plugins/viz-platform/README.md) *NEW in v4.0.0* **Dash Mantine Components Validation and Theming** Visualization toolkit with version-locked component validation and design token theming. @@ -157,7 +170,7 @@ Comprehensive NetBox REST API integration for infrastructure management. | Virtualization | Clusters, VMs, Interfaces | | Extras | Tags, Custom Fields, Audit Log | -### Data Platform MCP Server (shared) *NEW* +### Data Platform MCP Server (shared) *NEW in v4.0.0* pandas, PostgreSQL/PostGIS, and dbt integration for data engineering. @@ -168,7 +181,7 @@ pandas, PostgreSQL/PostGIS, and dbt integration for data engineering. | PostGIS | `st_tables`, `st_geometry_type`, `st_srid`, `st_extent` | | dbt | `dbt_parse`, `dbt_run`, `dbt_test`, `dbt_build`, `dbt_compile`, `dbt_ls`, `dbt_docs_generate`, `dbt_lineage` | -### Viz Platform MCP Server (shared) *NEW* +### Viz Platform MCP Server (shared) *NEW in v4.0.0* Dash Mantine Components validation and visualization tools. @@ -180,6 +193,16 @@ Dash Mantine Components validation and visualization tools. | Theme | `theme_create`, `theme_extend`, `theme_validate`, `theme_export_css`, `theme_list`, `theme_activate` | | Page | `page_create`, `page_add_navbar`, `page_set_auth`, `page_list`, `page_get_app_config` | +### Contract Validator MCP Server (shared) *NEW in v5.0.0* + +Cross-plugin compatibility validation tools. + +| Category | Tools | +|----------|-------| +| Parse | `parse_plugin_interface`, `parse_claude_md_agents` | +| Validation | `validate_compatibility`, `validate_agent_refs`, `validate_data_flow` | +| Report | `generate_compatibility_report`, `list_issues` | + ## Installation ### Prerequisites @@ -278,6 +301,7 @@ After installing plugins, the `/plugin` command may show `(no content)` - this i | cmdb-assistant | `/cmdb-assistant:cmdb-search` | | data-platform | `/data-platform:ingest` | | viz-platform | `/viz-platform:chart` | +| contract-validator | `/contract-validator:validate-contracts` | ## Repository Structure @@ -289,14 +313,16 @@ leo-claude-mktplace/ │ ├── gitea/ # Gitea MCP (issues, PRs, wiki) │ ├── netbox/ # NetBox MCP (CMDB) │ ├── data-platform/ # Data engineering (pandas, PostgreSQL, dbt) -│ └── viz-platform/ # Visualization (DMC, Plotly, theming) +│ ├── viz-platform/ # Visualization (DMC, Plotly, theming) +│ └── contract-validator/ # Cross-plugin validation (v5.0.0) ├── plugins/ # All plugins │ ├── projman/ # Sprint management │ ├── git-flow/ # Git workflow automation │ ├── pr-review/ # PR review │ ├── clarity-assist/ # Prompt optimization │ ├── data-platform/ # Data engineering -│ ├── viz-platform/ # Visualization (NEW) +│ ├── viz-platform/ # Visualization +│ ├── contract-validator/ # Cross-plugin validation (NEW) │ ├── claude-config-maintainer/ # CLAUDE.md optimization │ ├── cmdb-assistant/ # NetBox CMDB integration │ ├── doc-guardian/ # Documentation drift detection diff --git a/plugins/contract-validator/README.md b/plugins/contract-validator/README.md index 6af6bef..a5abf18 100644 --- a/plugins/contract-validator/README.md +++ b/plugins/contract-validator/README.md @@ -40,6 +40,7 @@ pip install -r requirements.txt | Command | Description | |---------|-------------| +| `/initial-setup` | Interactive setup wizard | | `/validate-contracts` | Full marketplace compatibility validation | | `/check-agent` | Validate single agent definition | | `/list-interfaces` | Show all plugin interfaces | diff --git a/plugins/contract-validator/commands/initial-setup.md b/plugins/contract-validator/commands/initial-setup.md new file mode 100644 index 0000000..d04c961 --- /dev/null +++ b/plugins/contract-validator/commands/initial-setup.md @@ -0,0 +1,152 @@ +--- +description: Interactive setup wizard for contract-validator plugin - verifies MCP server and shows capabilities +--- + +# Contract-Validator Setup Wizard + +This command sets up the contract-validator plugin for cross-plugin compatibility validation. + +## Important Context + +- **This command uses Bash, Read, Write, and AskUserQuestion tools** - NOT MCP tools +- **MCP tools won't work until after setup + session restart** +- **No external credentials required** - this plugin validates local files only + +--- + +## Phase 1: Environment Validation + +### Step 1.1: Check Python Version + +```bash +python3 --version +``` + +Requires Python 3.10+. If below, stop setup and inform user: +``` +Python 3.10 or higher is required. Please install it and run /initial-setup again. +``` + +--- + +## Phase 2: MCP Server Setup + +### Step 2.1: Locate Contract-Validator MCP Server + +```bash +# If running from installed marketplace +ls -la ~/.claude/plugins/marketplaces/leo-claude-mktplace/mcp-servers/contract-validator/ 2>/dev/null || echo "NOT_FOUND_INSTALLED" + +# If running from source +ls -la ~/claude-plugins-work/mcp-servers/contract-validator/ 2>/dev/null || echo "NOT_FOUND_SOURCE" +``` + +Determine which path exists and use that as the MCP server path. + +### Step 2.2: Check Virtual Environment + +```bash +ls -la /path/to/mcp-servers/contract-validator/.venv/bin/python 2>/dev/null && echo "VENV_EXISTS" || echo "VENV_MISSING" +``` + +### Step 2.3: Create Virtual Environment (if missing) + +```bash +cd /path/to/mcp-servers/contract-validator && python3 -m venv .venv && source .venv/bin/activate && pip install --upgrade pip && pip install -r requirements.txt && deactivate +``` + +**If pip install fails:** +- Show the error to the user +- Suggest: "Check your internet connection and try again." + +--- + +## Phase 3: Validation + +### Step 3.1: Verify MCP Server + +```bash +cd /path/to/mcp-servers/contract-validator && .venv/bin/python -c "from mcp_server.server import ContractValidatorMCPServer; print('MCP Server OK')" +``` + +If this fails, check the error and report it to the user. + +### Step 3.2: Summary + +Display: + +``` +╔════════════════════════════════════════════════════════════════╗ +║ CONTRACT-VALIDATOR SETUP COMPLETE ║ +╠════════════════════════════════════════════════════════════════╣ +║ MCP Server: ✓ Ready ║ +║ Parse Tools: ✓ Available (2 tools) ║ +║ Validation Tools: ✓ Available (3 tools) ║ +║ Report Tools: ✓ Available (2 tools) ║ +╚════════════════════════════════════════════════════════════════╝ +``` + +### Step 3.3: Session Restart Notice + +--- + +**Session Restart Required** + +Restart your Claude Code session for MCP tools to become available. + +**After restart, you can:** +- Run `/validate-contracts` to check all plugins for compatibility issues +- Run `/check-agent` to validate a single agent definition +- Run `/list-interfaces` to see all plugin commands and tools + +--- + +## Available Tools + +| Category | Tools | Description | +|----------|-------|-------------| +| Parse | `parse_plugin_interface`, `parse_claude_md_agents` | Extract interfaces from README.md and agents from CLAUDE.md | +| Validation | `validate_compatibility`, `validate_agent_refs`, `validate_data_flow` | Check conflicts, tool references, and data flows | +| Report | `generate_compatibility_report`, `list_issues` | Generate reports and filter issues | + +--- + +## Available Commands + +| Command | Description | +|---------|-------------| +| `/validate-contracts` | Full marketplace compatibility validation | +| `/check-agent` | Validate single agent definition | +| `/list-interfaces` | Show all plugin interfaces | + +--- + +## Use Cases + +### 1. Pre-Release Validation +Run `/validate-contracts` before releasing a new marketplace version to catch: +- Command name conflicts between plugins +- Missing tool references in agents +- Broken data flows + +### 2. Agent Development +Run `/check-agent` when creating or modifying agents to verify: +- All referenced tools exist +- Data flows are valid +- No undeclared dependencies + +### 3. Plugin Audit +Run `/list-interfaces` to get a complete view of: +- All commands across plugins +- All tools available +- Potential overlap areas + +--- + +## No Configuration Required + +This plugin doesn't require any configuration files. It reads plugin manifests and README files directly from the filesystem. + +**Paths it scans:** +- Marketplace: `~/.claude/plugins/marketplaces/leo-claude-mktplace/plugins/` +- Source (if available): `~/claude-plugins-work/plugins/`