personal-projects/leo-claude-mktplace
Template
0
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Page: lessons/sprints/cache-clearing-breaks-mcp-tools-mid-session
Pages
Change V5.4.0: Multi-Model Agent Support Proposal Change V5.4.0: Multi-Model Support (Sprint 7 Implementation) Change V04.1.0: Proposal (Implementation 1) Change V04.1.0: Proposal Change-V5.2.0:-Plugin-Enhancements-(Sprint-4-Commands) Change-V5.2.0:-Plugin-Enhancements-(Sprint-5-Documentation) Change-V5.2.0:-Plugin-Enhancements-Proposal.- Change-V5.5.0:-Hook-Efficiency-Quick-Wins-(Sprint-8-Implementation) Change-V5.6.0:-Domain-Advisory-Pattern-(Sprint-9-Implementation).- Change V5.6.0: Domain Advisory Pattern Proposal Change-V5.7.0:-Data-Platform-Domain-Advisory-(Sprint-10-Implementation) RFC-Hook-Efficiency-Improvements RFC-Perf-Sentinel-Plugin Sprint-1-viz-platform-Implementation-Plan branding/header-templates branding/plugin-registry branding/progress-templates branding/visual-spec lessons/patterns/agent-model-field-not-supported-by-claude-code lessons/patterns/command-frontmatter-missing-name-field-causes-silent-load-failure lessons/patterns/hook-message-wording-affects-claude-continuation-behavior lessons/patterns/mcp-venv-symlinks-lost-on-marketplace-update---5-hour-debug-loop lessons/patterns/mcp_servers-field-in-pluginjson---another-failed-debug-theory lessons/patterns/plugin-hooks-must-be-in-separate-file-not-inline lessons/patterns/plugin-load-errors---missing-name-field-in-command-frontmatter lessons/patterns/plugin-load-failure---check-command-frontmatter-first lessons/patterns/plugin-manifest-validation---hooks-and-agents-format-requirements lessons/patterns/plugin-version-mismatch-causes-silent-load-failure lessons/patterns/reset-pandas-index-after-filtering-to-prevent-column-pollution lessons/patterns/session-2026-02-02---mcp-server-venv-package-installation-failures lessons/patterns/setup-wizard-url-format-mismatch lessons/patterns/sprint-4---new-commands-not-discoverable-until-session-restart lessons/patterns/startup-hooks-must-check-venv-cache-path-first lessons/patterns/sync-entire-plugin-directory-not-individual-files lessons/patterns/use-fixes-n-keyword-for-automatic-issue-closing-in-prs lessons/sprints/cache-clearing-breaks-mcp-tools-mid-session lessons/sprints/sprint-1---viz-platform-plugin-implementation lessons/sprints/sprint-10---domain-advisory-pattern-replication-success lessons/sprints/sprint-2---contract-validator-plugin-implementation lessons/sprints/sprint-3---agent-runaway-detection-and-timeout-handling lessons/sprints/sprint-3---background-agent-permissions-must-be-pre-granted lessons/sprints/sprint-3---mcp-server-branch-detection-bug-runs-from-installed-dir lessons/sprints/sprint-4---plugin-commands-implementation lessons/sprints/sprint-6---visual-branding-and-documentation-maintenance lessons/sprints/sprint-8---parallel-hook-optimization-success lessons/sprints/v400-release---wiki-workflow-and-versioning-patterns lessons/sprints/versioning-workflow---use-unreleased-and-release-script lessons-learned/sprints/hook-efficiency-rfc unnamed
Clone
1
lessons/sprints/cache-clearing-breaks-mcp-tools-mid-session
Leo Miranda edited this page 2026-01-24 17:59:24 +00:00
Table of Contents

Context

During plugin development, following CLAUDE.md instructions to clear the plugin cache mid-session caused all MCP tools to fail with TLS certificate errors.

  • Command attempted: rm -rf ~/.claude/plugins/cache/leo-claude-mktplace/
  • Error: Could not find a suitable TLS CA certificate bundle, invalid path: .../certifi/cacert.pem

Problem

The CLAUDE.md mandatory rule instructed clearing the cache after plugin updates, but this is destructive mid-session because:

  1. MCP tools load with absolute paths to the venv at session start
  2. Cache contains the venv with TLS certificates (certifi package)
  3. Deleting the cache removes the venv, but the session still references the old paths
  4. Any HTTP-based MCP tool fails with certificate errors

Solution

Updated documentation to prevent this scenario:

  • CLAUDE.md: Replaced "ALWAYS CLEAR CACHE" rule with "VERIFY AND RESTART"
  • verify-hooks.sh: Changed cache existence from error to informational message
  • DEBUGGING-CHECKLIST.md: Added section "Cache Clearing: When It's Safe vs Destructive"

Key insight: Session restart is required for plugin changes, not cache clearing.

Prevention

  1. Never clear plugin cache during an active session
  2. Cache clearing is only safe before starting a new session
  3. For plugin changes mid-session: inform user to restart Claude Code
  4. verify-hooks.sh no longer treats cache existence as a failure

Related

Tags: mcp, cache, session, bug-fix, documentation, venv, tls