Add CLI introspection flags to je_auto_control_mcp

--list-tools / --list-resources / --list-prompts emit the
default catalogue as JSON and exit, so CI checks and manual
debugging can inspect the server's surface without launching a
real MCP client. --read-only filters --list-tools to the
read-only subset (matches JE_AUTOCONTROL_MCP_READONLY runtime).
With no flags the entry point still launches the stdio server.

Author: JE-Chen

je_auto_control/utils/mcp_server/__main__.py

@@ -1,11 +1,76 @@
-"""``python -m je_auto_control.utils.mcp_server`` entry point."""
+"""``python -m je_auto_control.utils.mcp_server`` entry point.
+
+Without flags this starts the stdio MCP server. With one of the
+``--list-*`` flags it prints the requested catalogue to stdout and
+exits — useful for inspection in CI or manual debugging.
+"""
+import argparse
+import json
+import sys
+
+from je_auto_control.utils.mcp_server.prompts import default_prompt_provider
+from je_auto_control.utils.mcp_server.resources import (
+    default_resource_provider,
+)
 from je_auto_control.utils.mcp_server.server import start_mcp_stdio_server
+from je_auto_control.utils.mcp_server.tools import (
+    build_default_tool_registry,
+)
+
 
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="je_auto_control_mcp",
+        description="Run AutoControl's MCP server (stdio) or list its catalogue.",
+    )
+    parser.add_argument(
+        "--list-tools", action="store_true",
+        help="Print all tool descriptors as JSON and exit.",
+    )
+    parser.add_argument(
+        "--list-resources", action="store_true",
+        help="Print all resource descriptors as JSON and exit.",
+    )
+    parser.add_argument(
+        "--list-prompts", action="store_true",
+        help="Print all prompt descriptors as JSON and exit.",
+    )
+    parser.add_argument(
+        "--read-only", action="store_true",
+        help="Restrict tools to those marked readOnlyHint=true.",
+    )
+    return parser
 
-def main() -> None:
-    """Launch the stdio MCP server; blocks until stdin closes."""
+
+def main(argv: list = None) -> int:
+    """CLI entry point. Returns the process exit code."""
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    listing_modes = (args.list_tools, args.list_resources, args.list_prompts)
+    if any(listing_modes):
+        _print_listings(args)
+        return 0
     start_mcp_stdio_server()
+    return 0
+
+
+def _print_listings(args: argparse.Namespace) -> None:
+    if args.list_tools:
+        registry = build_default_tool_registry(read_only=args.read_only)
+        json.dump([tool.to_descriptor() for tool in registry],
+                   sys.stdout, ensure_ascii=False, indent=2)
+        sys.stdout.write("\n")
+    if args.list_resources:
+        provider = default_resource_provider()
+        json.dump([resource.to_descriptor() for resource in provider.list()],
+                   sys.stdout, ensure_ascii=False, indent=2)
+        sys.stdout.write("\n")
+    if args.list_prompts:
+        provider = default_prompt_provider()
+        json.dump([prompt.to_descriptor() for prompt in provider.list()],
+                   sys.stdout, ensure_ascii=False, indent=2)
+        sys.stdout.write("\n")
 
 
 if __name__ == "__main__":
-    main()
+    sys.exit(main())

test/unit_test/headless/test_mcp_cli.py

@@ -0,0 +1,62 @@
+"""Tests for the je_auto_control_mcp CLI introspection flags."""
+import io
+import json
+import sys
+
+import pytest
+
+from je_auto_control.utils.mcp_server.__main__ import main
+
+
+def _capture(monkeypatch, argv):
+    buffer = io.StringIO()
+    monkeypatch.setattr(sys, "stdout", buffer)
+    rc = main(argv)
+    return rc, buffer.getvalue()
+
+
+def test_list_tools_emits_json_and_exits(monkeypatch):
+    rc, output = _capture(monkeypatch, ["--list-tools"])
+    assert rc == 0
+    descriptors = json.loads(output)
+    assert isinstance(descriptors, list)
+    assert descriptors
+    assert all("name" in d and "inputSchema" in d for d in descriptors)
+
+
+def test_list_tools_with_read_only_drops_destructive(monkeypatch):
+    _, output = _capture(monkeypatch, ["--list-tools", "--read-only"])
+    descriptors = json.loads(output)
+    names = {d["name"] for d in descriptors}
+    assert "ac_click_mouse" not in names
+    assert "ac_get_mouse_position" in names
+
+
+def test_list_resources_emits_json(monkeypatch):
+    rc, output = _capture(monkeypatch, ["--list-resources"])
+    assert rc == 0
+    descriptors = json.loads(output)
+    assert isinstance(descriptors, list)
+    uris = {d["uri"] for d in descriptors}
+    assert "autocontrol://history" in uris
+    assert "autocontrol://commands" in uris
+
+
+def test_list_prompts_emits_json(monkeypatch):
+    rc, output = _capture(monkeypatch, ["--list-prompts"])
+    assert rc == 0
+    descriptors = json.loads(output)
+    assert isinstance(descriptors, list)
+    names = {d["name"] for d in descriptors}
+    assert {"automate_ui_task", "find_widget"}.issubset(names)
+
+
+def test_no_flags_starts_stdio_server(monkeypatch):
+    """With no flags, main() should dispatch to start_mcp_stdio_server."""
+    started = []
+    import je_auto_control.utils.mcp_server.__main__ as cli_mod
+    monkeypatch.setattr(cli_mod, "start_mcp_stdio_server",
+                        lambda: started.append(True))
+    rc = main([])
+    assert rc == 0
+    assert started == [True]