refactor: consolidate tool retirement logic into a dedicated module and clean up legacy registration code (#112)

Author: thunderdew-dawn

agent-docs/agents/prompts/README.md

@@ -2,7 +2,8 @@
 
 MCP Prompt Markdown is bundled with the server under
 `src/fls_pilot/context/prompts/`. That package directory is the canonical
-runtime source used by `src/fls_pilot/prompts.py`.
+runtime source used by `src/fls_pilot/prompts.py`. Only runtime prompts are
+registered as public MCP prompts.
 
 ## Three Layers: Prompts · Resources · Tools
 
@@ -30,15 +31,6 @@ runtime source used by `src/fls_pilot/prompts.py`.
 | `composition_scale_writer` | `src/fls_pilot/context/prompts/composition-scale-writer.md` | Raga/scale melody and chord composition |
 | `audio_to_midi_or_reference_analysis` | `src/fls_pilot/context/prompts/audio-to-midi.md` | Audio analysis and optional MIDI extraction |
 
-### Dev Prompts (Developer / Agent Tooling)
-
-| Prompt name | Source file | Purpose |
-|-------------|------|---------|
-| `api_probe` | `src/fls_pilot/context/prompts/api-probe.md` | Safe FL API compatibility probe |
-| `bug_triage` | `src/fls_pilot/context/prompts/bug-triage.md` | GitHub bug classification and prep |
-| `implementation_slice` | `src/fls_pilot/context/prompts/implementation-slice.md` | Narrow pre-approved dev slice execution |
-| `release_prepare` | `src/fls_pilot/context/prompts/release.md` | Release checks, tagging, validation |
-
 ## Using Prompts via MCP
 
 MCP clients that support prompts can invoke them by name:

agent-docs/concepts/api-capability-audit.md

@@ -132,19 +132,20 @@ Not currently supported:
 
 The current baseline, regenerated on 2026-06-14, reports:
 
-- 94 registered public FastMCP tools with 94 unique public names after v2.0
-  legacy low-level alias removal.
+- 91 registered public FastMCP tools with 91 unique public names after runtime-only
+  MCP cleanup.
 - 167 statically audited tool definitions.
 - 33 registered `write-safe-required` tools.
 - 0 `write-gap` tools.
 - 0 `needs-review` tools.
-- 41 registered `read-only` tools.
+- 50 registered `read-only` tools.
 - 4 `server-state` tools.
 - 2 `external-write` tools.
 - 1 registered `transient` domain tool and 6 statically audited transient
   legacy/helper tools.
-- 13 registered tools are not covered by the static AST audit because they are
-  registered via direct `mcp.tool()(fn)` calls without safety annotations.
+- 1 registered public tool remains unannotated.
+- 10 registered tools are not covered by the static AST audit because they are
+  registered via direct `mcp.tool(...)(fn)` calls.
 - 86 statically audited legacy low-level tool definitions remain in source for
   helper/test compatibility but are intentionally absent from public
   registration.

docs/mcp-integration.md

@@ -19,8 +19,7 @@ Runtime agents should start with MCP context, not repository file reads:
 
 MCP prompts are available for guided workflows such as Mix Review, Routing
 Review, Project Organizer, Project Preflight, Plugin Chain Planning,
-Composition, Audio Analysis, API probes, bug triage, implementation slices, and
-release preparation.
+Composition, and Audio Analysis.
 
 ## Domain Tools
 

pyproject.toml

@@ -80,9 +80,55 @@ Repository = "https://github.com/thunderdew-dawn/fls-pilot"
 Issues = "https://github.com/thunderdew-dawn/fls-pilot/issues"
 Upstream = "https://github.com/rosasynthesiz/flstudio-mcp"
 
+[tool.hatch.build]
+include = [
+    "/src/fls_pilot/**/*.py",
+    "/src/fls_pilot/context/**/*.md",
+    "/src/fls_pilot/context/**/*.json",
+    "/src/fls_pilot/context/**/*.yaml",
+    "/src/fls_pilot/context/**/*.yml",
+    "/knowledgebase/**/*.md",
+    "/knowledgebase/**/*.json",
+    "/knowledgebase/**/*.yaml",
+    "/knowledgebase/**/*.yml",
+    "/docs/**/*.md",
+    "/README.md",
+    "/LICENSE",
+]
+exclude = [
+    "/.github/**",
+    "/.gitignore",
+    "/.pytest_cache/**",
+    "/.ruff_cache/**",
+    "/agent-docs/**",
+    "/dist/**",
+    "/docs/community/**",
+    "/docs/requirements.txt",
+    "/knowledgebase/agent_notes/**",
+    "/scratch/**",
+    "/scripts/calibration/**",
+    "/scripts/probes/**",
+    "/tests/**",
+    "/src/fls_pilot/context/prompts/api-probe.md",
+    "/src/fls_pilot/context/prompts/bug-triage.md",
+    "/src/fls_pilot/context/prompts/implementation-slice.md",
+    "/src/fls_pilot/context/prompts/release.md",
+    "**/__pycache__/**",
+]
+
 [tool.hatch.build.targets.wheel]
 packages = ["src/fls_pilot"]
-artifacts = ["src/fls_pilot/context/**/*.md"]
+force-include = { "knowledgebase" = "knowledgebase" }
+
+[tool.hatch.build.targets.sdist]
+only-include = [
+    "src",
+    "knowledgebase",
+    "docs",
+    "README.md",
+    "LICENSE",
+    "pyproject.toml",
+]
 
 [tool.ruff]
 line-length = 100

scripts/check_tool_registration_baseline.py

@@ -19,15 +19,16 @@
 
 from fls_pilot import __version__  # noqa: E402
 from fls_pilot import server as server_module  # noqa: E402
+from fls_pilot.tools.registration import RETIRED_LOW_LEVEL_TOOLS  # noqa: E402
 
-EXPECTED_REGISTERED_TOOL_COUNT = 94
+EXPECTED_REGISTERED_TOOL_COUNT = 91
 EXPECTED_STATIC_TOOL_COUNT = 167
 EXPECTED_REGISTERED_SAFETY_SUMMARY = {
     "external-write": 2,
-    "read-only": 41,
+    "read-only": 50,
     "server-state": 4,
     "transient": 1,
-    "unannotated": 13,
+    "unannotated": 1,
     "write-safe-required": 33,
 }
 EXPECTED_STATIC_SAFETY_SUMMARY = {
@@ -152,9 +153,7 @@ def main() -> int:
     static_summary = {"write-gap": 0, **count_by_status(static_audits)}
     registered_not_static = sorted(registered_name_set - static_names)
     static_not_registered = sorted(static_names - registered_name_set)
-    expected_static_not_registered = sorted(
-        getattr(server_module, "_LEGACY_LOW_LEVEL_TOOLS", set()) & static_names
-    )
+    expected_static_not_registered = sorted(RETIRED_LOW_LEVEL_TOOLS & static_names)
 
     print("Tool registration baseline")
     print(f"- registered_public_tools: {len(registered_tools)}")

src/fls_pilot/context/docs/api-capability-audit.md

@@ -132,19 +132,20 @@ Not currently supported:
 
 The current baseline, regenerated on 2026-06-14, reports:
 
-- 94 registered public FastMCP tools with 94 unique public names after v2.0
-  legacy low-level alias removal.
+- 91 registered public FastMCP tools with 91 unique public names after runtime-only
+  MCP cleanup.
 - 167 statically audited tool definitions.
 - 33 registered `write-safe-required` tools.
 - 0 `write-gap` tools.
 - 0 `needs-review` tools.
-- 41 registered `read-only` tools.
+- 50 registered `read-only` tools.
 - 4 `server-state` tools.
 - 2 `external-write` tools.
 - 1 registered `transient` domain tool and 6 statically audited transient
   legacy/helper tools.
-- 13 registered tools are not covered by the static AST audit because they are
-  registered via direct `mcp.tool()(fn)` calls without safety annotations.
+- 1 registered public tool remains unannotated.
+- 10 registered tools are not covered by the static AST audit because they are
+  registered via direct `mcp.tool(...)(fn)` calls.
 - 86 statically audited legacy low-level tool definitions remain in source for
   helper/test compatibility but are intentionally absent from public
   registration.

src/fls_pilot/context/prompts/README.md

@@ -1,6 +1,6 @@
 # MCP Prompts — Agent Guide
 
-This directory contains the canonical Markdown content for all MCP Prompts
+This directory contains the canonical Markdown content for runtime MCP Prompts
 registered by the FLStudioPilot server.
 
 ## Three Layers: Prompts · Resources · Tools
@@ -29,15 +29,6 @@ registered by the FLStudioPilot server.
 | `composition_scale_writer` | `composition-scale-writer.md` | Raga/scale melody and chord composition |
 | `audio_to_midi_or_reference_analysis` | `audio-to-midi.md` | Audio analysis and optional MIDI extraction |
 
-### Dev Prompts (Developer / Agent Tooling)
-
-| Prompt name | File | Purpose |
-|-------------|------|---------|
-| `api_probe` | `api-probe.md` | Safe FL API compatibility probe |
-| `bug_triage` | `bug-triage.md` | GitHub bug classification and prep |
-| `implementation_slice` | `implementation-slice.md` | Narrow pre-approved dev slice execution |
-| `release_prepare` | `release.md` | Release checks, tagging, validation |
-
 ## Using Prompts via MCP
 
 MCP clients that support prompts can invoke them by name:

src/fls_pilot/prompts.py

@@ -15,9 +15,6 @@
   mix_review, routing_review, project_organizer, project_preflight,
   plugin_chain_planner, composition_scale_writer,
   audio_to_midi_or_reference_analysis
-
-Dev prompts (developer / agent tooling):
-  api_probe, bug_triage, implementation_slice, release_prepare
 """
 
 from __future__ import annotations
@@ -126,31 +123,6 @@ def _workflow_preamble(workflow_key: str) -> str:
         "audio_analysis",
         "Analyze an audio file for tempo/key/melody; optionally write MIDI to Piano Roll.",
     ),
-    # Dev prompts
-    (
-        "api_probe",
-        "api-probe.md",
-        None,
-        "Plan a safe API/compatibility probe for an undocumented FL Studio behavior.",
-    ),
-    (
-        "bug_triage",
-        "bug-triage.md",
-        None,
-        "Classify and prepare a GitHub bug report before implementation.",
-    ),
-    (
-        "implementation_slice",
-        "implementation-slice.md",
-        None,
-        "Claim and execute a narrow pre-approved development slice.",
-    ),
-    (
-        "release_prepare",
-        "release.md",
-        None,
-        "Prepare a release: checks, tagging, dist validation, rollback plan.",
-    ),
 ]
 
 

src/fls_pilot/server.py

@@ -23,6 +23,7 @@
 from fastmcp import FastMCP
 
 from . import __version__
+from . import prompts as prompt_defs
 from .connection import list_ports
 from .protocol import port_from_fl_name, port_to_fl_name
 from .runtime_config import DEFAULT_SSE_HOST, DEFAULT_SSE_PORT
@@ -36,15 +37,13 @@
 from .tools import color as color_tools
 from .tools import compose as compose_tools
 from .tools import effect as effect_domain_tools
-from .tools import effects as effects_tools
 from .tools import export as export_tools
 from .tools import knowledgebase as knowledgebase_tools
 from .tools import mix_doctor as mix_doctor_tools
 from .tools import mixer as mixer_tools
 from .tools import mixer_core as mixer_core_tools
 from .tools import mixing as mixing_tools
 from .tools import pattern as pattern_domain_tools
-from .tools import patterns_playlist as patterns_playlist_tools
 from .tools import pianoroll as pianoroll_tools
 from .tools import playlist as playlist_domain_tools
 from .tools import plugin as plugin_tools
@@ -56,107 +55,9 @@
 from .tools import routing as routing_tools
 from .tools import transport as transport_tools
 from .tools import workflow_context as workflow_context_tools
-from . import prompts as prompt_defs
 
 logger = logging.getLogger("fls_pilot")
 
-_LEGACY_LOW_LEVEL_TOOLS = {
-    # Transport one-off aliases. Use fl_transport(action, params).
-    "fl_ping",
-    "fl_get_tempo",
-    "fl_set_tempo",
-    "fl_play",
-    "fl_stop",
-    "fl_toggle_play",
-    "fl_record",
-    "fl_get_play_state",
-    "fl_get_song_position",
-    "fl_set_song_position",
-    "fl_get_time_signature",
-    "fl_set_time_signature",
-    # Mixer/channel core aliases. Use fl_mixer/fl_channel or retained safety tools.
-    "fl_get_mixer_state",
-    "fl_get_channel_state",
-    "fl_set_mixer_volume",
-    "fl_set_mixer_pan",
-    "fl_set_mixer_mute",
-    "fl_set_mixer_solo",
-    "fl_set_mixer_name",
-    "fl_set_channel_volume",
-    "fl_set_channel_pan",
-    "fl_set_channel_mute",
-    "fl_set_channel_solo",
-    "fl_mixer_list_tracks",
-    "fl_mixer_get_track",
-    "fl_mixer_set_volume",
-    "fl_mixer_set_pan",
-    "fl_mixer_set_mute",
-    "fl_mixer_set_solo",
-    "fl_mixer_select_track",
-    "fl_mixer_get_route",
-    "fl_mixer_set_route",
-    "fl_mixer_set_stereo_separation",
-    # Channel organizer aliases that are covered by fl_channel.
-    "fl_get_channel_details",
-    "fl_set_channel_name",
-    "fl_set_channel_mixer_track",
-    "fl_channel_get_grid",
-    "fl_channel_set_grid_bit",
-    "fl_channel_set_step_param",
-    "fl_channel_set_steps",
-    "fl_channel_clear_grid",
-    "fl_classify_channels",
-    # Routing one-off aliases covered by fl_mixer route actions.
-    "fl_get_routing",
-    "fl_set_route",
-    # Pattern and playlist one-off aliases. Use fl_pattern/fl_playlist.
-    "fl_pattern_list",
-    "fl_pattern_get",
-    "fl_pattern_get_length",
-    "fl_pattern_select",
-    "fl_pattern_rename",
-    "fl_pattern_set_color",
-    "fl_pattern_set_length",
-    "fl_pattern_find_empty",
-    "fl_playlist_list_tracks",
-    "fl_playlist_get_track",
-    "fl_playlist_set_mute",
-    "fl_playlist_set_solo",
-    "fl_playlist_set_name",
-    "fl_playlist_set_color",
-    "fl_playlist_select_track",
-    # Effect slot and native EQ one-off aliases. Use fl_effect.
-    "fl_effect_get_slot",
-    "fl_effect_list_slots",
-    "fl_effect_set_slot_mix",
-    "fl_effect_get_track_slots_enabled",
-    "fl_effect_set_track_slots_enabled",
-    "fl_effect_set_slot_enabled",
-    "fl_eq_get",
-    "fl_eq_set_band",
-    # Already-loaded plugin parameter aliases. Use fl_plugin.
-    "fl_plugin_list",
-    "fl_plugin_get_params",
-    "fl_plugin_set_param",
-    "fl_plugin_list_params",
-    "fl_plugin_get_param",
-    # Piano Roll one-off aliases. Use fl_piano_roll.
-    "fl_write_piano_roll_notes",
-    "fl_quantize_pattern",
-    "fl_piano_write_notes",
-    "fl_piano_write_chord",
-    "fl_piano_clear",
-    "fl_piano_quantize",
-    "fl_piano_transpose",
-    "fl_piano_duplicate",
-    "fl_piano_velocity_ramp",
-    "fl_piano_probe_return_channel",
-    "fl_piano_add_marker",
-    "fl_piano_add_time_signature_marker",
-    "fl_piano_clear_markers",
-    "fl_piano_get_notes",
-}
-
 
 SERVER_INSTRUCTIONS = """\
 FL Studio Pilot server -- control FL Studio from an AI assistant.
@@ -219,7 +120,6 @@ def build_server() -> FastMCP:
     channel_tools.register(mcp)  # Channel organizer: details, names, mixer assignment
     pianoroll_tools.register(mcp)  # Phase 2: write notes into the piano roll
     plugin_tools.register(mcp)  # Phase 1B: plugin param read/write (name or index)
-    effects_tools.register(mcp)  # Effect slot + native EQ pack
     mixing_tools.register(mcp)  # Slice B: high-level EQ mixing intents
     routing_tools.register(mcp)  # Routing/cleanup Slice 1: read-only
     bulk_tools.register(mcp)  # Bulk mute/solo: server-side group orchestration
@@ -234,12 +134,9 @@ def build_server() -> FastMCP:
     export_tools.register(mcp)  # MIDI export: arrangement spec -> type-1 .mid on disk
     presets_tools.register(mcp)  # Preset suggester: read preset names from disk
     mix_doctor_tools.register(mcp)  # Mix Review: diagnose whole mix + gated adjustments
-    patterns_playlist_tools.register(mcp)  # Phase 3: Patterns & Playlist pack
     knowledgebase_tools.register(mcp)  # KB Tools
     workflow_context_tools.register(mcp)  # Workflow context: read-only fl_get_workflow_context
     prompt_defs.register(mcp)  # MCP Prompts: guided workflow templates
-    for name in sorted(_LEGACY_LOW_LEVEL_TOOLS):
-        mcp.local_provider.remove_tool(name)
     return mcp