galaxy-tool-refactor-mcp 0.2.0__tar.gz

galaxy_tool_refactor_mcp-0.2.0/.gitignore

@@ -0,0 +1,24 @@
+# Machine-local scratch, never committed: the cloned corpus (.local/corpus,
+# seeded from corpus_sources.json) and external source clones for inspection
+# (e.g. .local/galaxy-src = a clone of galaxyproject/galaxy used to verify
+# Galaxy-internal behaviour locally).
+# No trailing slash: `.local/` matches only a directory, so an accidental
+# symlink at this path was committable (it happened once; removed in this branch).
+.local
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+
+# Local-only draft of the GCC poster abstract.
+gcc2026-abstract.txt
+
+# Claude Code session scratch (the tracked .claude/ settings + skills stay; this
+# runtime lock for scheduled wakeups is machine-local).
+.claude/scheduled_tasks.lock
+.claude/worktrees/

galaxy_tool_refactor_mcp-0.2.0/CLAUDE.md

@@ -0,0 +1,75 @@
+# CLAUDE.md
+
+Guidance for Claude Code working in this repository.
+
+## Project
+
+`galaxy-tool-refactor-mcp` is the **MCP server** tier (tier 4) of the Galaxy tool
+refactoring framework — an agent-facing front-end over the registry facade, a
+sibling of the user-facing CLI.
+
+| Tier | Layer | Package |
+|---|---|---|
+| 0.5 | rule metadata | `galaxy-tool-refactor-rules` |
+| 1 | parsing & validation | `galaxy-tool-source` |
+| 2 | structure | `galaxy-tool-codemod` |
+| 3 | formatting | `galaxy-tool-fmt` |
+| 3.5 | advisory checks | `galaxy-tool-lint` |
+| 3.6 | rule registry / rulesets | `galaxy-tool-refactor-registry` |
+| 4 | app / CLI | `galaxy-tool-refactor-cli` |
+| 4 | **MCP server** | `galaxy-tool-refactor-mcp` *(this repo)* |
+
+It depends on the tier-3.6 facade (plus tier-1 for the `ToolXmlSyntaxError`
+boundary type, and tier-0.5 for the `Violation` type — a `TYPE_CHECKING`-only
+import in `service.py`, declared as a direct dep because it is imported directly)
+and `mcp` (FastMCP). The lower tiers do **not** depend on it.
+
+## Key invariants
+
+- **Thin adapter, split in two.** `service.py` is the protocol-agnostic core
+  (facade → JSON-able `dict`s, **no `mcp` import**, fully unit-tested);
+  `server.py` is the FastMCP binding (a handler per tool that delegates to
+  `service`). The split keeps the logic testable without a transport and the
+  protocol shell minimal. This is *why* the facade is library-first.
+- **Never writes to disk.** Agents supply XML content as a `str` and get content
+  back; `write_path` is never passed. The XML `str` is encoded to `bytes` before
+  the facade sees it, so it is parsed as content, never mistaken for a path.
+- **`server.py` is the error boundary.** Its handlers translate the facade's typed
+  `UnknownRuleset` / `UnknownRuleCode` and tier-1's `ToolXmlSyntaxError` into a
+  plain `ValueError` whose message FastMCP returns as a tool error (the MCP
+  analogue of the CLI's `click` boundary). `service.py` lets them propagate.
+- **FastMCP introspects handler signatures at runtime** (`eval_str=True`), so a
+  registered handler's annotations must be evaluable at import time — use builtin
+  types (`list[str] | None`), not `TYPE_CHECKING`-only names.
+- **Goal 1 only.** Agent-authored rules (`docs/vision.md` Goal 2) are out of
+  scope; the server exposes the fixed registry.
+
+## Coding standards
+
+Hand-written code follows **dignified-python** (vendored at the workspace root
+`.claude/skills/dignified-python/`): LBYL over try/except (exceptions only at the
+MCP error boundary in `server.py`, chained `from e`); keyword-only args after the
+first; absolute imports, no re-exports, no `__all__`; no import-time side effects.
+`optimized-python` is a secondary reference; dignified-python governs on conflict.
+New code lands tests-first.
+
+## Commands
+
+Run from the **workspace root** (`galaxy-tool-refactor/`):
+
+- `uv sync`
+- `uv run --package galaxy-tool-refactor-mcp pytest galaxy-tool-refactor-mcp/tests/`
+- `uv run ruff check galaxy-tool-refactor-mcp/src galaxy-tool-refactor-mcp/tests`
+- `uv run mypy --config-file galaxy-tool-refactor-mcp/pyproject.toml galaxy-tool-refactor-mcp/src`
+- `uv run galaxy-tool-refactor-mcp` — serve over stdio
+
+## Useful references
+
+- `galaxy-tool-refactor-registry/src/galaxy_tool_refactor_registry/facade.py` —
+  the `run` / `upgrade` / `detect` / `convert_help` / `tokenize_version` /
+  `list_rulesets` / `list_rules` entry points `service.py` wraps; `results.py` for the structured result shapes serialised.
+- `galaxy-tool-refactor-cli/src/galaxy_tool_refactor_cli/cli.py` — the sibling
+  front-end over the same facade.
+- `docs/decisions.md` D1–D3 — the design + the `convert_help_tool` /
+  `tokenize_version_tool` additions; `docs/vision.md` — the agent-authored-rules
+  future (Goal 2).

galaxy_tool_refactor_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: galaxy-tool-refactor-mcp
+Version: 0.2.0
+Summary: MCP server exposing the Galaxy tool refactoring facade to AI agents.
+Author: Richard Burhans
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: galaxy-tool-refactor-registry==0.2.0
+Requires-Dist: galaxy-tool-refactor-rules==0.2.0
+Requires-Dist: galaxy-tool-source==0.2.0
+Requires-Dist: mcp>=1.2
+Description-Content-Type: text/markdown
+
+# galaxy-tool-refactor-mcp
+
+An **MCP server** that exposes the Galaxy tool refactoring framework to AI coding
+agents. A tier-4 sibling of `galaxy-tool-refactor-cli`: both wrap the
+`galaxy-tool-refactor-registry` facade (tier 3.6) for a different audience — the
+CLI for humans at a terminal, this for agents over the Model Context Protocol.
+
+## Shape
+
+The facade is **library-first** (structured args in, structured results out, no
+disk writes unless asked, introspectable), so the server is a *thin adapter*:
+
+- **`service.py`** — protocol-agnostic. Pure functions that take XML as a `str`
+  (plus `rulesets` / `select` / `ignore`) and return JSON-able `dict`s by calling the
+  facade. No `mcp` import; fully unit-tested.
+- **`server.py`** — the FastMCP binding. A small handler per tool delegates to
+  `service`, and is the error boundary (facade `UnknownRuleset` / `UnknownRuleCode`
+  and tier-1 `ToolXmlSyntaxError` → a clean MCP tool error).
+
+## Tools
+
+| MCP tool | What it does |
+|---|---|
+| `format_tool` | Apply a ruleset's fixable rules then format; returns canonical XML + advisory notes. |
+| `upgrade_tool` | Profile-upgrade then format; returns upgraded XML, steps applied, the behavior-preserving verdict, and notes. |
+| `check_tool` | Report-only detect over the selected rules; returns the findings (each flagged fixable vs advisory). |
+| `list_rulesets` | The baked-in rulesets (name / codes / is_default / description). |
+| `list_rules` | The baked-in rules (code / summary / family / fixable / rulesets). |
+
+Agents supply content and receive content — the server **never writes to disk**.
+
+## Run
+
+```bash
+uv run galaxy-tool-refactor-mcp   # serves over stdio
+```
+
+Point an MCP client (e.g. a coding agent) at that command. `list_rulesets` /
+`list_rules` let the agent discover the available rulesets and rule codes at
+runtime instead of hardcoding them.
+
+See [`docs/decisions.md`](docs/decisions.md) D1 for the design, and
+[`docs/vision.md`](docs/vision.md) for the longer-horizon agent-authored-rules
+direction (Goal 2, still future).

galaxy_tool_refactor_mcp-0.2.0/README.md

@@ -0,0 +1,44 @@
+# galaxy-tool-refactor-mcp
+
+An **MCP server** that exposes the Galaxy tool refactoring framework to AI coding
+agents. A tier-4 sibling of `galaxy-tool-refactor-cli`: both wrap the
+`galaxy-tool-refactor-registry` facade (tier 3.6) for a different audience — the
+CLI for humans at a terminal, this for agents over the Model Context Protocol.
+
+## Shape
+
+The facade is **library-first** (structured args in, structured results out, no
+disk writes unless asked, introspectable), so the server is a *thin adapter*:
+
+- **`service.py`** — protocol-agnostic. Pure functions that take XML as a `str`
+  (plus `rulesets` / `select` / `ignore`) and return JSON-able `dict`s by calling the
+  facade. No `mcp` import; fully unit-tested.
+- **`server.py`** — the FastMCP binding. A small handler per tool delegates to
+  `service`, and is the error boundary (facade `UnknownRuleset` / `UnknownRuleCode`
+  and tier-1 `ToolXmlSyntaxError` → a clean MCP tool error).
+
+## Tools
+
+| MCP tool | What it does |
+|---|---|
+| `format_tool` | Apply a ruleset's fixable rules then format; returns canonical XML + advisory notes. |
+| `upgrade_tool` | Profile-upgrade then format; returns upgraded XML, steps applied, the behavior-preserving verdict, and notes. |
+| `check_tool` | Report-only detect over the selected rules; returns the findings (each flagged fixable vs advisory). |
+| `list_rulesets` | The baked-in rulesets (name / codes / is_default / description). |
+| `list_rules` | The baked-in rules (code / summary / family / fixable / rulesets). |
+
+Agents supply content and receive content — the server **never writes to disk**.
+
+## Run
+
+```bash
+uv run galaxy-tool-refactor-mcp   # serves over stdio
+```
+
+Point an MCP client (e.g. a coding agent) at that command. `list_rulesets` /
+`list_rules` let the agent discover the available rulesets and rule codes at
+runtime instead of hardcoding them.
+
+See [`docs/decisions.md`](docs/decisions.md) D1 for the design, and
+[`docs/vision.md`](docs/vision.md) for the longer-horizon agent-authored-rules
+direction (Goal 2, still future).

galaxy_tool_refactor_mcp-0.2.0/docs/decisions.md

@@ -0,0 +1,80 @@
+# Decisions — galaxy-tool-refactor-mcp
+
+Each entry records a decision once it lands: a date, the decision, and the
+rationale. Mirrors the conventions of the sibling packages' `docs/decisions.md`.
+
+## D1 (2026-06-03) — The MCP server: a thin FastMCP adapter over the facade (vision Goal 1)
+
+> **Renamed since (PR #146, registry D15):** presets became **rulesets** — the tool
+> is now `list_rulesets`, the argument `ruleset`, the typed error `UnknownRuleset`.
+> This entry keeps the original vocabulary as a historical record; the shipped
+> surface is `server.py` / `service.py`.
+
+### Decision
+
+`galaxy-tool-refactor-mcp` becomes a real tier-4 package — an MCP server exposing
+the registry facade to AI agents (Goal 1 of `docs/vision.md`). It is a sibling of
+the CLI: both wrap the tier-3.6 facade for a different audience. Five tools:
+`format_tool`, `upgrade_tool`, `check_tool`, `list_presets`, `list_rules`. Goal 2
+(agent-authored rules) stays out of scope.
+
+### Shape — split in two
+
+- **`service.py` (protocol-agnostic).** Pure functions taking XML as a `str`
+  (plus `preset` / `select` / `ignore`) and returning JSON-able `dict`s by calling
+  `facade.run` / `upgrade` / `detect` / `list_presets` / `list_rules` and
+  serialising the structured results. **No `mcp` import** — so the substance is
+  unit-testable without a transport. This realises the vision's "thin adapter":
+  the facade is library-first precisely so this layer is a mechanical mapping.
+- **`server.py` (FastMCP binding).** `build_server()` registers a small handler
+  per tool, each delegating to `service`. Factored out so tests introspect the
+  registered tools (`await server.list_tools()`) without starting a transport;
+  `main()` runs it over stdio.
+
+### Rationale / boundaries
+
+- **Never writes to disk.** Agents pass content and get content back —
+  `write_path` is never used. The XML `str` is `encode("utf-8")`d to `bytes`
+  before the facade, so it is always parsed as *content*, never a path.
+- **`server.py` is the error boundary** (the MCP analogue of the CLI's `click`
+  boundary): it maps the facade's typed `UnknownPreset` / `UnknownRuleCode` and
+  tier-1's `ToolXmlSyntaxError` to a plain `ValueError` whose message FastMCP
+  surfaces as a tool error, so a bad preset or malformed tool is a clean error
+  result, not a crashed server. `service.py` lets the typed errors propagate.
+- **Handler annotations are runtime-evaluable.** FastMCP builds each tool's input
+  schema via `inspect.signature(..., eval_str=True)`, so a registered handler's
+  annotations must resolve at import time. Handlers therefore use builtin
+  `list[str] | None`, not a `TYPE_CHECKING`-only `Sequence` (which raised
+  `InvalidSignature`). `service.py`, not introspected by FastMCP, keeps its
+  `Sequence` typing.
+- **Dependency.** `mcp>=1.2` (ships `py.typed`, so mypy-strict passes). Registered
+  in the workspace; the qa-gate (`scripts/qa_gate.sh`) now covers eight packages.
+
+### Reproduction
+
+```sh
+uv run --package galaxy-tool-refactor-mcp pytest galaxy-tool-refactor-mcp/tests/
+uv run galaxy-tool-refactor-mcp   # serve over stdio
+```
+
+## D2 (2026-06-10) — `convert_help_tool`: the opt-in conversion joins the surface
+
+The sixth tool, mirroring the CLI's `convert-help` (cli D12) over the facade's
+`convert_help` (registry D18): `convert_help_tool(xml) -> {converted, formatted,
+skip_reason}`. The conversion's gates live below this tier (profile >= 24.2 +
+render equivalence, codemod §38); the adapter only serialises the structured
+outcome — `converted=False` with the codemod's own `skip_reason` is a normal
+result, not an MCP error, so an agent can act on the reason (e.g. call
+`upgrade_tool` first, exactly what the profile-gate message says). No
+ruleset/select parameters: GTR092 is not selectable anywhere, by design.
+
+## D3 (2026-06-10) — `tokenize_version_tool`: the seventh tool
+
+The GTR094 sibling of D2, same shape: `tokenize_version_tool(xml) ->
+{tokenized, formatted, skip_reason}` over the facade's `tokenize_version`
+(registry D19). One MCP-specific boundary, stated rather than hidden: every
+MCP tool is **content-based** (agents supply XML strings; nothing touches
+disk), so a tool whose `<macros>` imports files fails closed — the
+expansion-equality gate cannot resolve imports without a source directory —
+and the skip reason says to use the path-based CLI `tokenize-version` instead.
+No ruleset/select parameters: GTR094, like GTR092, is not selectable anywhere.

galaxy_tool_refactor_mcp-0.2.0/docs/vision.md

@@ -0,0 +1,70 @@
+# Vision: `galaxy-tool-refactor` for AI agents (MCP server + agent-authored rules)
+
+**Status:** **Goal 1 (the MCP server) is shipped** — see `docs/decisions.md` D1;
+this section now describes what was built. **Goal 2 (agent-authored rules)
+remains forward-looking** — recorded so the facade does not foreclose it. The
+current locked decision — "adding rules is a developer task; no user-defined
+rules" — still governs; Goal 2 is the relaxation path if/when desired.
+
+## Goal 1 — `galaxy-tool-refactor` as a tool for agents (the MCP server) — SHIPPED
+
+The MCP server (this package) wraps the `galaxy-tool-refactor-registry`
+facade so coding agents can:
+
+- **Discover** what the tool can do: `list_rulesets()` → ruleset names +
+  descriptions, `list_rules()` → code / summary / family / fixable-vs-advisory /
+  which rulesets include each rule. These map directly onto MCP tool descriptions
+  and enum-valued arguments, so an agent learns the available rulesets/rules at
+  runtime instead of hardcoding them.
+- **Run** `format` / `upgrade` / `check` over content the agent supplies (raw
+  XML, not necessarily a path), with a chosen ruleset or explicit
+  `--select`/`--ignore` code set, and receive **structured results**
+  (`FormatResult` / `UpgradeResult` / `DetectResult`: formatted bytes, the
+  `Violation`s found, upgrade steps applied, advisory notes).
+
+This is *why* the facade is library-first and structured: the MCP server is a
+thin adapter (structured args in, structured results out), never a subprocess
+that scrapes CLI text. The facade already honors the needed shape — content-or-
+path input, structured results, disk writes only on explicit request, and
+introspection — so the server is mostly an MCP-protocol binding over it.
+
+The server is a **tier-4 sibling of the CLI**: both depend on the registry
+facade; orchestration stays in the facade so the CLI and the MCP server share one
+core and cannot drift.
+
+## Goal 2 — agents authoring their own codemod / fmt extensions
+
+Longer-horizon: let a coding agent write a new rule — a
+`CodemodCommand`/`Rule` subclass with its `detect`/`apply` + a `RuleMeta` — and
+have the framework discover and run it alongside the baked-in rules.
+
+The seam already exists: the codemod tier's **detect-primitive**
+`CodemodCommand` and the registry's **`RuleHandle`** adapter are the natural
+authoring/integration contract — an agent targets `detect()` (+ `apply()` for a
+fixable rule) and a `RuleMeta` code, and the registry wraps it into a `RuleHandle`
+exactly like a built-in.
+
+Open questions to resolve **later** (do not solve now; just avoid foreclosing):
+
+1. **Discovery.** Stay with the current hardcoded family registries
+   (`coded_codemods()` / `all_rules()` / `all_checks()`, developer-only) or grow
+   an entry-point/plugin mechanism so third-party rule packages register
+   themselves. The unified registry is the single place that mechanism would
+   plug into.
+2. **Authoring contract.** Pin down the minimum an agent must supply (tag
+   dispatch method names, `RuleMeta` fields, idempotence expectations) and
+   surface it as documentation / a template the MCP server can hand back.
+3. **QA gating.** How an agent-authored rule earns trust before it ships — the
+   corpus idempotence / post-validity sweeps (`scripts/corpus_check.py`) are the
+   existing gate; an authored rule would run the same `codemod`/`rules` sweep.
+4. **Trust / sandboxing.** Running an agent-authored `apply` thunk executes
+   third-party code. A plugin path needs a trust boundary (vetted packages,
+   opt-in, or a sandbox) — out of scope until the plugin mechanism is real.
+
+## Design constraints this places on the registry facade (honored today)
+
+- Library-first: no `click` / `sys.exit` / stdout-scraping in the call path.
+- Structured results and structured introspection (`list_rulesets`/`list_rules`).
+- Content-or-path input; never writes to disk unless a `write_path` is given.
+- The `RuleHandle` is the uniform, code-addressable unit an MCP tool or a plugin
+  loader can enumerate and invoke without knowing which tier a rule came from.

galaxy_tool_refactor_mcp-0.2.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "galaxy-tool-refactor-mcp"
+version = "0.2.0"
+description = "MCP server exposing the Galaxy tool refactoring facade to AI agents."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Richard Burhans" }]
+# A tier-4 sibling of the CLI: both wrap the registry facade (tier 3.6). The
+# server is a thin protocol adapter — `service.py` (facade -> JSON, no `mcp`
+# import) carries the logic; `server.py` binds it to FastMCP.
+dependencies = [
+    "galaxy-tool-refactor-rules==0.2.0",
+    "galaxy-tool-refactor-registry==0.2.0",
+    "galaxy-tool-source==0.2.0",
+    "mcp>=1.2",
+]
+
+[project.scripts]
+galaxy-tool-refactor-mcp = "galaxy_tool_refactor_mcp.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "ruff>=0.5",
+    "mypy>=1.10",
+]
+
+[tool.ruff]
+src = ["src"]
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "SIM", "PTH"]
+
+[tool.mypy]
+files = ["src"]
+strict = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.uv.sources]
+galaxy-tool-refactor-rules = { workspace = true }
+galaxy-tool-refactor-registry = { workspace = true }
+galaxy-tool-source = { workspace = true }

galaxy_tool_refactor_mcp-0.2.0/src/galaxy_tool_refactor_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""MCP server exposing the Galaxy tool refactoring facade to AI agents.
+
+``service`` is the protocol-agnostic adapter (facade → JSON-serialisable dicts);
+``server`` binds it to FastMCP. See ``docs/decisions.md`` D1.
+"""

galaxy_tool_refactor_mcp-0.2.0/src/galaxy_tool_refactor_mcp/server.py

@@ -0,0 +1,119 @@
+"""The FastMCP binding — a thin protocol shell over ``service``.
+
+Each MCP tool is a small handler with agent-facing named arguments that delegates
+to the protocol-agnostic ``service`` adapter. The handlers are the **error
+boundary** (the MCP analogue of the CLI's): they translate the facade's typed
+``UnknownRuleset`` / ``UnknownRuleCode`` and tier-1's ``ToolXmlSyntaxError`` into a
+plain ``ValueError`` whose message FastMCP returns as a tool error, so a malformed
+tool or an unknown ruleset is a clean error result rather than a crashed server.
+
+Run it with the ``galaxy-tool-refactor-mcp`` console script (stdio transport).
+``build_server()`` is factored out so tests can introspect the registered tools
+without starting a transport. See ``docs/decisions.md`` D1; agent-authored rules
+(vision Goal 2) are out of scope.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from galaxy_tool_refactor_registry.errors import UnknownRuleCode, UnknownRuleset
+from galaxy_tool_source.binding import ToolXmlSyntaxError
+from mcp.server.fastmcp import FastMCP
+
+from galaxy_tool_refactor_mcp import service
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from typing import TypeVar
+
+    T = TypeVar("T")
+
+_SERVER_NAME = "galaxy-tool-refactor"
+
+
+def _guarded(produce: Callable[[], T], /) -> T:
+    """Run *produce*, mapping the facade/parse errors to an agent-facing message."""
+    try:
+        return produce()
+    except (UnknownRuleset, UnknownRuleCode) as error:
+        raise ValueError(str(error)) from error
+    except ToolXmlSyntaxError as error:
+        raise ValueError(f"invalid tool XML: {error}") from error
+
+
+def _format_tool(
+    xml: str,
+    rulesets: list[str] | None = None,
+    select: list[str] | None = None,
+    ignore: list[str] | None = None,
+) -> dict[str, object]:
+    """Apply a ruleset's fixable rules then format; return canonical XML + notes."""
+    return _guarded(
+        lambda: service.format_tool(
+            xml, rulesets=rulesets or (), select=select or (), ignore=ignore or ()
+        )
+    )
+
+
+def _upgrade_tool(
+    xml: str,
+    select: list[str] | None = None,
+    ignore: list[str] | None = None,
+) -> dict[str, object]:
+    """Profile-upgrade then format; return upgraded XML, steps applied, and notes."""
+    return _guarded(
+        lambda: service.upgrade_tool(xml, select=select or (), ignore=ignore or ())
+    )
+
+
+def _check_tool(
+    xml: str,
+    rulesets: list[str] | None = None,
+    select: list[str] | None = None,
+    ignore: list[str] | None = None,
+) -> dict[str, object]:
+    """Report-only detect over the selected rules; never mutates the tool."""
+    return _guarded(
+        lambda: service.check_tool(
+            xml, rulesets=rulesets or (), select=select or (), ignore=ignore or ()
+        )
+    )
+
+
+def _convert_help_tool(xml: str) -> dict[str, object]:
+    """Convert an RST <help> to Markdown when provably render-equivalent (opt-in)."""
+    return _guarded(lambda: service.convert_help_tool(xml))
+
+
+def _tokenize_version_tool(xml: str) -> dict[str, object]:
+    """Factor a literal version into @TOOL_VERSION@ tokens when provable (opt-in)."""
+    return _guarded(lambda: service.tokenize_version_tool(xml))
+
+
+def _list_rulesets() -> list[dict[str, object]]:
+    """The baked-in rulesets (name / codes / is_default / description)."""
+    return service.list_rulesets()
+
+
+def _list_rules(include_upgrade: bool = False) -> list[dict[str, object]]:
+    """The baked-in rules as JSON — every RuleInfo field (incl. cite)."""
+    return service.list_rules(include_upgrade=include_upgrade)
+
+
+def build_server() -> FastMCP:
+    """Construct the FastMCP server with every tool registered (no transport)."""
+    server = FastMCP(_SERVER_NAME)
+    server.add_tool(_format_tool, name="format_tool")
+    server.add_tool(_upgrade_tool, name="upgrade_tool")
+    server.add_tool(_check_tool, name="check_tool")
+    server.add_tool(_convert_help_tool, name="convert_help_tool")
+    server.add_tool(_tokenize_version_tool, name="tokenize_version_tool")
+    server.add_tool(_list_rulesets, name="list_rulesets")
+    server.add_tool(_list_rules, name="list_rules")
+    return server
+
+
+def main() -> None:
+    """Console-script entry point: serve over stdio."""
+    build_server().run()

galaxy_tool_refactor_mcp-0.2.0/src/galaxy_tool_refactor_mcp/service.py

@@ -0,0 +1,199 @@
+"""The protocol-agnostic adapter: registry facade → JSON-serialisable ``dict``s.
+
+This is the substance of the MCP server, with **no ``mcp`` import** — it takes
+agent-friendly inputs (XML as a ``str``, ruleset names, code lists) and returns
+plain JSON-able structures by calling the tier-3.6 facade. ``server`` wraps these
+as MCP tools. Keeping the logic here means it is unit-testable without a transport
+and the FastMCP binding stays a thin shell (the vision's "thin adapter").
+
+XML content arrives as a ``str`` and is encoded to ``bytes`` before the facade
+sees it, so it is always parsed as *content*, never mistaken for a path. Nothing
+here writes to disk — agents supply content and get content back. Selection /
+parse errors propagate as the facade's typed ``UnknownRuleset`` /
+``UnknownRuleCode`` and tier-1's ``ToolXmlSyntaxError``; the *server* is the error
+boundary that turns them into MCP error responses (mirroring the CLI).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from galaxy_tool_refactor_registry import facade
+from galaxy_tool_refactor_registry.resolve import resolve_codes, resolve_upgrade_codes
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from galaxy_tool_refactor_registry.results import (
+        ConvertHelpResult,
+        DetectResult,
+        FormatResult,
+        RuleInfo,
+        RulesetInfo,
+        TokenizeVersionResult,
+        UpgradeResult,
+    )
+    from galaxy_tool_refactor_rules.violation import Violation
+
+
+def _violation_to_dict(violation: Violation, /) -> dict[str, object]:
+    """Serialise a Violation to a JSON-able dict for an agent.
+
+    ``code`` is the **precise rule code**, including a partition sub-rule's dotted
+    child code (``GTR020.1`` for the fix, ``GTR020.2`` for the advisory) — *not* the
+    parent display code. Agents get the exact sub-rule so they can distinguish the
+    fixable half from the advisory residual; the human CLI collapses both to the
+    parent (``GTR020``) via ``display_code``. Intentional asymmetry (registry D10).
+    """
+    return {
+        "code": violation.code,
+        "sourceline": violation.sourceline,
+        "xpath": violation.xpath,
+        "message": violation.message,
+    }
+
+
+def _format_result_to_dict(result: FormatResult, /) -> dict[str, object]:
+    return {
+        "formatted": result.formatted.decode("utf-8"),
+        "advisory": [_violation_to_dict(v) for v in result.advisory],
+        "notes": list(result.notes),
+    }
+
+
+def _upgrade_result_to_dict(result: UpgradeResult, /) -> dict[str, object]:
+    return {
+        "formatted": result.formatted.decode("utf-8"),
+        "steps_applied": list(result.steps_applied),
+        "missing_upgrade": result.missing_upgrade,
+        "behavior_preserving": result.behavior_preserving,
+        "advisory": [_violation_to_dict(v) for v in result.advisory],
+        "notes": list(result.notes),
+    }
+
+
+def _convert_help_result_to_dict(result: ConvertHelpResult, /) -> dict[str, object]:
+    return {
+        "converted": result.converted,
+        "formatted": result.formatted.decode("utf-8"),
+        "skip_reason": result.skip_reason,
+    }
+
+
+def _tokenize_version_result_to_dict(
+    result: TokenizeVersionResult, /
+) -> dict[str, object]:
+    return {
+        "tokenized": result.tokenized,
+        "formatted": result.formatted.decode("utf-8"),
+        "skip_reason": result.skip_reason,
+    }
+
+
+def _detect_result_to_dict(result: DetectResult, /) -> dict[str, object]:
+    return {
+        "violations": [
+            {**_violation_to_dict(v), "advisory": result.is_advisory(v)}
+            for v in result.violations
+        ],
+        "advisory_codes": sorted(result.advisory_codes),
+    }
+
+
+def _ruleset_info_to_dict(info: RulesetInfo, /) -> dict[str, object]:
+    return {
+        "name": info.name,
+        "codes": list(info.codes),
+        "is_default": info.is_default,
+        "description": info.description,
+    }
+
+
+def _rule_info_to_dict(info: RuleInfo, /) -> dict[str, object]:
+    return {
+        "code": info.code,
+        "summary": info.summary,
+        "family": info.family,
+        "fixable": info.fixable,
+        "rulesets": list(info.rulesets),
+        "planemo_linters": list(info.planemo_linters),
+        "since": info.since,
+        "cite": info.cite,
+    }
+
+
+def format_tool(
+    xml: str,
+    /,
+    *,
+    rulesets: Sequence[str] = (),
+    select: Sequence[str] = (),
+    ignore: Sequence[str] = (),
+) -> dict[str, object]:
+    """Apply a ruleset's fixable rules then format; return the canonical XML + notes."""
+    codes = resolve_codes(rulesets=rulesets, select=select, ignore=ignore)
+    return _format_result_to_dict(facade.run(xml.encode("utf-8"), codes=codes))
+
+
+def upgrade_tool(
+    xml: str,
+    /,
+    *,
+    select: Sequence[str] = (),
+    ignore: Sequence[str] = (),
+) -> dict[str, object]:
+    """Profile-upgrade then format; return the upgraded XML, steps, and notes."""
+    codes = resolve_upgrade_codes(select=select, ignore=ignore)
+    return _upgrade_result_to_dict(facade.upgrade(xml.encode("utf-8"), codes=codes))
+
+
+def check_tool(
+    xml: str,
+    /,
+    *,
+    rulesets: Sequence[str] = (),
+    select: Sequence[str] = (),
+    ignore: Sequence[str] = (),
+) -> dict[str, object]:
+    """Report-only detect over the selected rules; never mutates the tool."""
+    codes = resolve_codes(rulesets=rulesets, select=select, ignore=ignore)
+    return _detect_result_to_dict(facade.detect(xml.encode("utf-8"), codes=codes))
+
+
+def convert_help_tool(xml: str, /) -> dict[str, object]:
+    """Convert an RST ``<help>`` to Markdown when provable; else report why not.
+
+    The opt-in GTR092 conversion (registry D18): profile >= 24.2 (the XSD gate —
+    the skip reason says to run ``upgrade_tool`` first) + the tier-1
+    render-equivalence gate. ``converted=False`` is a normal outcome, not an
+    error; ``formatted`` then echoes the (serialised) unchanged tool.
+    """
+    return _convert_help_result_to_dict(facade.convert_help(xml.encode("utf-8")))
+
+
+def tokenize_version_tool(xml: str, /) -> dict[str, object]:
+    """Factor a literal version into @TOOL_VERSION@ tokens when provable (GTR094).
+
+    The opt-in tokenization (registry D19): fail-closed preconditions plus the
+    expansion-equality gate. ``tokenized=False`` is a normal outcome with the
+    codemod's own ``skip_reason``. Content-based like every MCP tool, so a tool
+    whose ``<macros>`` imports files fails closed (the gate cannot resolve
+    imports without a source directory) — the skip reason says so; use the CLI
+    ``tokenize-version`` (path-based) for those.
+    """
+    return _tokenize_version_result_to_dict(
+        facade.tokenize_version(xml.encode("utf-8"))
+    )
+
+
+def list_rulesets() -> list[dict[str, object]]:
+    """The baked-in rulesets (name / codes / is_default / description)."""
+    return [_ruleset_info_to_dict(info) for info in facade.list_rulesets()]
+
+
+def list_rules(*, include_upgrade: bool = False) -> list[dict[str, object]]:
+    """The baked-in rules as JSON — every RuleInfo field (incl. cite)."""
+    return [
+        _rule_info_to_dict(info)
+        for info in facade.list_rules(include_upgrade=include_upgrade)
+    ]

galaxy_tool_refactor_mcp-0.2.0/tests/test_server.py

@@ -0,0 +1,53 @@
+"""Tests for the FastMCP binding: tool registration + the error boundary."""
+
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+
+from galaxy_tool_refactor_mcp.server import (
+    _check_tool,
+    _format_tool,
+    build_server,
+)
+
+_TOOL = (
+    '<tool id="m" name="M" version="1.0.0" profile="24.0">'
+    "<command><![CDATA[echo x]]></command>"
+    '<inputs><param value="v" type="text" name="a"/></inputs>'
+    '<outputs><data name="o"/></outputs></tool>'
+)
+
+
+def test_build_server_registers_every_tool() -> None:
+    server = build_server()
+    tools = asyncio.run(server.list_tools())
+    assert {tool.name for tool in tools} == {
+        "format_tool",
+        "upgrade_tool",
+        "check_tool",
+        "convert_help_tool",
+        "tokenize_version_tool",
+        "list_rulesets",
+        "list_rules",
+    }
+
+
+def test_handler_maps_unknown_ruleset_to_plain_valueerror() -> None:
+    """The error boundary downgrades the typed UnknownRuleset to a plain message."""
+    with pytest.raises(ValueError) as exc_info:
+        _format_tool(_TOOL, rulesets=["does-not-exist"])
+    # Not the UnknownRuleset subclass — a clean message for the agent.
+    assert type(exc_info.value) is ValueError
+
+
+def test_handler_maps_malformed_xml_to_value_error() -> None:
+    with pytest.raises(ValueError, match="invalid tool XML"):
+        _format_tool("<tool><unclosed></tool>")
+
+
+def test_handler_success_path_returns_dict() -> None:
+    result = _check_tool(_TOOL)
+    assert isinstance(result, dict)
+    assert "violations" in result

galaxy_tool_refactor_mcp-0.2.0/tests/test_service.py

@@ -0,0 +1,156 @@
+"""Tests for the protocol-agnostic service adapter (facade → JSON dicts)."""
+
+from __future__ import annotations
+
+import pytest
+from galaxy_tool_refactor_registry.errors import UnknownRuleCode, UnknownRuleset
+from galaxy_tool_source.binding import ToolXmlSyntaxError
+from galaxy_tool_source.profiles import latest_profile
+
+from galaxy_tool_refactor_mcp import service
+
+# A tool with out-of-order <param> attributes (value, type, name) — GTR002
+# reorders them, so `format` changes it and `check` reports a fixable finding.
+_MESSY = (
+    '<tool id="m" name="M" version="1.0.0" profile="24.0">'
+    "<command><![CDATA[echo x]]></command>"
+    '<inputs><param value="v" type="text" name="a"/></inputs>'
+    '<outputs><data name="o"/></outputs></tool>'
+)
+# A 24.1 tool whose BAM format normalises on the 24.1 -> 24.2 bump.
+_UPGRADABLE = (
+    '<tool id="m" name="M" version="1.0.0" profile="24.1">'
+    "<command><![CDATA[echo x]]></command>"
+    '<inputs><param name="i" type="data" format="BAM"/></inputs>'
+    '<outputs><data name="o"/></outputs></tool>'
+)
+
+
+def test_format_tool_returns_canonical_xml() -> None:
+    result = service.format_tool(_MESSY)
+    formatted = result["formatted"]
+    assert isinstance(formatted, str)
+    # GTR002 reordered the param attributes to name, type, value.
+    param = formatted.partition("<param")[2]
+    assert param.index("name=") < param.index("type=") < param.index("value=")
+    assert isinstance(result["advisory"], list)
+    assert isinstance(result["notes"], list)
+
+
+def test_format_tool_unknown_ruleset_raises() -> None:
+    with pytest.raises(UnknownRuleset):
+        service.format_tool(_MESSY, rulesets=["does-not-exist"])
+
+
+def test_format_tool_unknown_select_code_raises() -> None:
+    with pytest.raises(UnknownRuleCode):
+        service.format_tool(_MESSY, select=["GTR999"])
+
+
+def test_check_tool_reports_violations() -> None:
+    result = service.check_tool(_MESSY)
+    violations = result["violations"]
+    assert isinstance(violations, list)
+    codes = {v["code"] for v in violations}  # type: ignore[index]
+    assert "GTR002" in codes  # the out-of-order param attributes
+    assert isinstance(result["advisory_codes"], list)
+
+
+def test_check_tool_strict_marks_advisory() -> None:
+    result = service.check_tool(_MESSY, rulesets=["strict"])
+    advisory_codes = result["advisory_codes"]
+    assert isinstance(advisory_codes, list)
+    # Strict adds the advisory checks; an advisory finding is marked advisory
+    # (a per-violation flag, not a code prefix).
+    advisory = [v for v in result["violations"] if v["advisory"]]  # type: ignore[index]
+    assert advisory
+
+
+def test_upgrade_tool_bumps_profile() -> None:
+    result = service.upgrade_tool(_UPGRADABLE)
+    formatted = result["formatted"]
+    assert isinstance(formatted, str)
+    assert f'profile="{latest_profile()}"' in formatted
+    assert "24.1" in result["steps_applied"]  # type: ignore[operator]
+    assert result["missing_upgrade"] is None
+    assert result["behavior_preserving"] in (True, False, None)
+
+
+def test_list_rulesets_includes_default() -> None:
+    rulesets = service.list_rulesets()
+    assert rulesets
+    names = {r["name"] for r in rulesets}
+    assert "default" in names
+    assert any(r["is_default"] for r in rulesets)
+
+
+def test_list_rules_has_codes_and_families() -> None:
+    rules = service.list_rules()
+    codes = {r["code"] for r in rules}
+    assert all(c.startswith("GTR") for c in codes)  # unified namespace
+    families = {r["family"] for r in rules}
+    assert {"codemod", "fmt", "check"} <= families
+
+
+def test_list_rules_include_upgrade_adds_more() -> None:
+    base = len(service.list_rules())
+    extended = len(service.list_rules(include_upgrade=True))
+    assert extended > base
+
+
+def test_malformed_xml_raises_syntax_error() -> None:
+    with pytest.raises(ToolXmlSyntaxError):
+        service.format_tool("<tool><unclosed></tool>")
+
+
+_CONVERTIBLE = (
+    '<tool id="m" name="M" version="1.0.0" profile="24.2">'
+    "<command><![CDATA[echo x]]></command>"
+    "<help>Title\n=====\n\nSome **bold** text.\n</help></tool>"
+)
+
+
+def test_convert_help_tool_converts() -> None:
+    result = service.convert_help_tool(_CONVERTIBLE)
+    assert result["converted"] is True
+    assert result["skip_reason"] is None
+    formatted = result["formatted"]
+    assert isinstance(formatted, str)
+    assert 'format="markdown"' in formatted
+    assert "# Title" in formatted
+
+
+def test_convert_help_tool_reports_profile_skip() -> None:
+    old = _CONVERTIBLE.replace(' profile="24.2"', "")
+    result = service.convert_help_tool(old)
+    assert result["converted"] is False
+    skip_reason = result["skip_reason"]
+    assert isinstance(skip_reason, str) and "upgrade" in skip_reason
+
+
+_TOKENIZABLE = (
+    '<tool id="m" name="M" version="1.20+galaxy0" profile="24.0">'
+    "<command><![CDATA[echo x]]></command>"
+    '<requirements><requirement type="package" version="1.20">samtools'
+    "</requirement></requirements>"
+    '<inputs><param name="i" type="text"/></inputs>'
+    '<outputs><data name="o"/></outputs></tool>'
+)
+
+
+def test_tokenize_version_tool_tokenizes() -> None:
+    result = service.tokenize_version_tool(_TOKENIZABLE)
+    assert result["tokenized"] is True
+    assert result["skip_reason"] is None
+    formatted = result["formatted"]
+    assert isinstance(formatted, str)
+    assert 'version="@TOOL_VERSION@+galaxy@VERSION_SUFFIX@"' in formatted
+    assert '<token name="@TOOL_VERSION@">1.20</token>' in formatted
+
+
+def test_tokenize_version_tool_reports_skip() -> None:
+    plain = _TOKENIZABLE.replace('version="1.20+galaxy0"', 'version="1.20"')
+    result = service.tokenize_version_tool(plain)
+    assert result["tokenized"] is False
+    skip_reason = result["skip_reason"]
+    assert isinstance(skip_reason, str) and "+galaxy" in skip_reason