myco_graft
List, validate, or explain plugins in a Myco substrate. Also list registered substrates across the machine.
Instructions
Introspect the substrate's plugin surface: list every loaded dimension / adapter / schema_upgrader / overlay_verb with (kind, name, source, scope), validate plugins by re-importing under isolation, or explain a single plugin (source path + docstring). Scope classifies each plugin as 'kernel' (shipped with myco package) or 'substrate' (loaded from /.myco/plugins/).
Use this when: debugging "why is my plugin not loading", auditing what's actually registered, or listing substrates across the machine (--list-substrates mode, reads ~/.myco/substrates.yaml). Do NOT confuse with myco_immune's dimension-listing mode — graft inspects plugin binaries, immune inspects findings.
Side effects: none. Pure read. --validate mode does re-import plugins, which executes their init.py; the execution occurs in an isolated module namespace and is idempotent — safe even for plugins that register into global registries.
Returns (by mode). --list: { exit_code, mode:'list', plugins: [...], count }. --validate: { exit_code, mode: 'validate', errors: [...] }. --explain: { exit_code, mode: 'explain', name, kind, source, scope, docstring }. --list-substrates: { exit_code, mode:'list-substrates', substrates: [...], count, live_count, stale_count }.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| list | No | When true, enumerate every plugin currently loaded in this substrate's registry (kernel + substrate-local). Returns one row per plugin with kind + name + source (file path) + scope (kernel|substrate). Mutually exclusive with validate / explain / list-substrates. | |
| validate | No | When true, re-import every substrate-local plugin in isolation and collect any exceptions. Used to sanity-check plugins after editing. Mutually exclusive with list / explain / list-substrates. | |
| explain | No | When set, return the source path + docstring + kind for the named plugin. Pass the plugin's registered name (e.g. 'M1' for a dimension, 'UrlFetcher' for an adapter). Unknown names raise UsageError. Mutually exclusive with list / validate / list-substrates. | |
| list_substrates | No | v0.5.16: list every substrate registered on this machine (reads ~/.myco/substrates.yaml), sorted by last-seen-at. Returns stale entries (exists=false) whose on-disk path no longer has a _canon.yaml for cleanup insight. Mutually exclusive with list / validate / explain. | |
| project_dir | No | Absolute path of the workspace / project whose Myco substrate this call targets. Overrides auto-discovery. When omitted, Myco resolves via MCP roots/list, then MYCO_PROJECT_DIR, then cwd — the substrate_pulse field in every response echoes which source answered. |