personal-projects/leo-claude-mktplace
Template
0
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
33a7c91f4fc28b2ae82c19a167c0014231a3ef9e
leo-claude-mktplace/docs/CANONICAL-PATHS.md
lmiranda c9e054e013 fix(hooks): check venv cache path before marketplace path 
Startup hooks in data-platform and pr-review were checking for venvs
at the marketplace path (~/.claude/plugins/marketplaces/.../mcp-servers/)
which gets wiped on updates. The actual venvs live in the cache directory
(~/.cache/claude-mcp-venvs/) which survives updates.

This caused false "MCP venv missing" errors even when venvs existed,
wasting hours of debugging time.

Fixed hooks now check cache path first, matching the pattern used
by run.sh scripts.

Also updated docs/CANONICAL-PATHS.md with the correct venv path pattern
to prevent future occurrences.

Lesson learned: lessons/patterns/startup-hooks-must-check-venv-cache-path-first

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-02 22:13:40 -05:00

12 KiB
Raw Blame History

Canonical Paths - SINGLE SOURCE OF TRUTH

This file defines ALL valid paths in this repository. No exceptions. No inference. No assumptions.

Last Updated: 2026-01-30 (v5.4.1)

Repository Root Structure

leo-claude-mktplace/
├── .claude/                    # Claude Code local settings
├── .claude-plugin/             # Marketplace manifest
│   └── marketplace.json
├── .scratch/                   # Transient work (auto-cleaned)
├── docs/                       # All documentation
│   ├── architecture/           # Draw.io diagrams and specs
│   ├── 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
│   └── UPDATING.md             # Update guide
├── hooks/                      # Shared hooks (if any)
├── 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/
│   │   ├── commands/
│   │   ├── agents/
│   │   ├── skills/
│   │   └── claude-md-integration.md
│   ├── doc-guardian/           # Documentation drift detection
│   │   ├── .claude-plugin/
│   │   ├── hooks/
│   │   ├── commands/
│   │   ├── agents/
│   │   ├── 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
│   ├── project-hygiene/
│   │   ├── .claude-plugin/
│   │   ├── hooks/
│   │   └── 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/
│   │   ├── hooks/
│   │   └── claude-md-integration.md
│   ├── contract-validator/
│   │   ├── .claude-plugin/
│   │   ├── commands/
│   │   ├── agents/
│   │   └── claude-md-integration.md
│   └── viz-platform/
│       ├── .claude-plugin/
│       ├── commands/
│       ├── agents/
│       ├── hooks/
│       └── 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)
│   ├── check-venv.sh           # Check if venvs exist (read-only)
│   ├── validate-marketplace.sh # Marketplace compliance validation
│   ├── verify-hooks.sh         # Verify all hooks use correct event types
│   ├── setup-venvs.sh          # Setup MCP server venvs (create only, never delete)
│   └── release.sh              # Release automation with version bumping
├── CLAUDE.md
├── README.md
├── LICENSE
├── CHANGELOG.md
└── .gitignore

Path Patterns (MANDATORY)

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 commands plugins/{plugin-name}/commands/ plugins/projman/commands/
Plugin agents plugins/{plugin-name}/agents/ plugins/projman/agents/
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

MCP servers are shared at repository root and configured in .mcp.json.

Context Pattern Example
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/gitea/mcp_server/
MCP venv (local) mcp-servers/{server}/.venv/ mcp-servers/gitea/.venv/

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:

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

Documentation Paths

Type Location
Architecture diagrams docs/architecture/
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

Validation Rules

Before Creating Any File

  1. Check this file for the correct path pattern
  2. Verify the parent directory exists in the structure above
  3. If path not listed here, STOP AND ASK

Before Generating Any Prompt

  1. List all file paths the prompt will create/modify
  2. Verify each path against patterns in this file
  3. Show verification to user before proceeding

Relative Path Calculation

From .mcp.json (at root) to 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/:

.claude-plugin/marketplace.json
  ↑ marketplace.json is at repo root level
  → go down to plugins/projman/           (./plugins/projman/)

Result: ./plugins/projman

Anti-Patterns (NEVER DO THIS)

Wrong Why Correct
projman/ at root Plugins go in plugins/ 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 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:

{
  "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" }
  }
}

Change Log

Date Change By
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
Reference in New Issue View Git Blame Copy Permalink