Refactor CLI: dev umbrella, default main.py, smart server defaults, clearer init

src/mcp_agent/cli/__main__.py

@@ -25,35 +25,35 @@
 }
 
 KNOWN = {
-    "go",
-    "check",
-    "chat",
-    "dev",
-    "invoke",
-    "serve",
+    # Curated top-level commands
     "init",
     "quickstart",
     "config",
-    "keys",
-    "models",
-    "server",
-    "build",
-    "logs",
     "doctor",
-    "configure",
+    "deploy",
+    "login",
+    "whoami",
+    "logout",
     "cloud",
+    # Umbrella group
+    "dev",
 }
 
 
 def main():
     if len(sys.argv) > 1:
         first = sys.argv[1]
-        if first not in KNOWN:
+        # Back-compat: allow `mcp-agent go ...`
+        if first == "go":
+            sys.argv.insert(1, "dev")
+        elif first not in KNOWN:
             for i, arg in enumerate(sys.argv[1:], 1):
                 if arg in GO_OPTIONS or any(
                     arg.startswith(opt + "=") for opt in GO_OPTIONS
                 ):
-                    sys.argv.insert(i, "go")
+                    # Route bare chat-like invocations to dev go (legacy behavior)
+                    sys.argv.insert(i, "dev")
+                    sys.argv.insert(i + 1, "go")
                     break
     app()
 

src/mcp_agent/cli/commands/chat.py

@@ -16,6 +16,8 @@
     attach_stdio_servers,
     attach_url_servers,
     load_user_app,
+    detect_default_script,
+    select_servers_from_config,
 )
 from mcp_agent.cli.utils.url_parser import generate_server_configs, parse_server_urls
 from mcp_agent.workflows.factory import create_llm
@@ -99,14 +101,17 @@ def chat(
     npx: Optional[str] = typer.Option(None, "--npx"),
     uvx: Optional[str] = typer.Option(None, "--uvx"),
     stdio: Optional[str] = typer.Option(None, "--stdio"),
-    script: Optional[Path] = typer.Option(Path("agent.py"), "--script"),
+    script: Optional[Path] = typer.Option(None, "--script"),
     list_servers: bool = typer.Option(False, "--list-servers"),
     list_tools: bool = typer.Option(False, "--list-tools"),
     list_resources: bool = typer.Option(False, "--list-resources"),
     server: Optional[str] = typer.Option(
         None, "--server", help="Filter to a single server"
     ),
 ) -> None:
+    # Resolve script with auto-detection
+    script = detect_default_script(script)
+
     server_list = servers_csv.split(",") if servers_csv else None
 
     url_servers = None
@@ -140,12 +145,17 @@ def chat(
             else:
                 server_list.extend(list(stdio_servers.keys()))
 
+    # Smart defaults for servers
+    resolved_server_list = select_servers_from_config(
+        servers_csv, url_servers, stdio_servers
+    )
+
     # Listing mode (no generation)
     if list_servers or list_tools or list_resources:
         try:
 
             async def _list():
-                app_obj = load_user_app(script or Path("agent.py"))
+                app_obj = load_user_app(script)
                 await app_obj.initialize()
                 attach_url_servers(app_obj, url_servers)
                 attach_stdio_servers(app_obj, stdio_servers)
@@ -163,7 +173,7 @@ async def _list():
                     agent = Agent(
                         name="chat-lister",
                         instruction="You list tools and resources",
-                        server_names=target_servers,
+                        server_names=resolved_server_list or target_servers,
                         context=app_obj.context,
                     )
                     async with agent:
@@ -203,7 +213,7 @@ async def _list():
         ):
 
             async def _parallel_repl():
-                app_obj = load_user_app(script or Path("agent.py"))
+                app_obj = load_user_app(script)
                 await app_obj.initialize()
                 attach_url_servers(app_obj, url_servers)
                 attach_stdio_servers(app_obj, stdio_servers)
@@ -227,7 +237,7 @@ async def _parallel_repl():
                                 provider = prov_guess
                         llm = create_llm(
                             agent_name=m,
-                            server_names=server_list or [],
+                            server_names=resolved_server_list or [],
                             provider=(provider or "openai"),
                             model=m,
                             context=app_obj.context,
@@ -276,7 +286,9 @@ async def _parallel_repl():
                             ag = _Agent(
                                 name="chat-lister",
                                 instruction="list tools",
-                                server_names=[srv] if srv else (server_list or []),
+                                server_names=[srv]
+                                if srv
+                                else (resolved_server_list or []),
                                 context=app_obj.context,
                             )
                             async with ag:
@@ -294,7 +306,9 @@ async def _parallel_repl():
                             ag = _Agent(
                                 name="chat-lister",
                                 instruction="list resources",
-                                server_names=[srv] if srv else (server_list or []),
+                                server_names=[srv]
+                                if srv
+                                else (resolved_server_list or []),
                                 context=app_obj.context,
                             )
                             async with ag:
@@ -367,8 +381,8 @@ async def _gen(llm_instance):
             try:
                 out = asyncio.run(
                     _run_single_model(
-                        script=script or Path("agent.py"),
-                        servers=server_list,
+                        script=script,
+                        servers=resolved_server_list,
                         url_servers=url_servers,
                         stdio_servers=stdio_servers,
                         model=m,
@@ -394,7 +408,7 @@ async def _gen(llm_instance):
         ):
             # Interactive loop
             async def _repl():
-                app_obj = load_user_app(script or Path("agent.py"))
+                app_obj = load_user_app(script)
                 await app_obj.initialize()
                 attach_url_servers(app_obj, url_servers)
                 attach_stdio_servers(app_obj, stdio_servers)
@@ -416,7 +430,7 @@ async def _repl():
                         provider = model_id.split(":", 1)[0]
                     llm = create_llm(
                         agent_name=(name or "chat"),
-                        server_names=server_list or [],
+                        server_names=resolved_server_list or [],
                         provider=(provider or "openai"),
                         model=model_id,
                         context=app_obj.context,
@@ -476,7 +490,7 @@ async def _repl():
                                 # Recreate LLM with new model
                                 llm_local = create_llm(
                                     agent_name=(name or "chat"),
-                                    server_names=server_list or [],
+                                    server_names=resolved_server_list or [],
                                     provider=(prov or "openai"),
                                     model=model_id,
                                     context=app_obj.context,
@@ -502,7 +516,9 @@ async def _repl():
                             ag = Agent(
                                 name="chat-lister",
                                 instruction="list tools",
-                                server_names=[srv] if srv else (server_list or []),
+                                server_names=[srv]
+                                if srv
+                                else (resolved_server_list or []),
                                 context=app_obj.context,
                             )
                             async with ag:
@@ -521,7 +537,9 @@ async def _repl():
                             ag = Agent(
                                 name="chat-lister",
                                 instruction="list resources",
-                                server_names=[srv] if srv else (server_list or []),
+                                server_names=[srv]
+                                if srv
+                                else (resolved_server_list or []),
                                 context=app_obj.context,
                             )
                             async with ag:
@@ -698,8 +716,8 @@ async def _repl():
         else:
             out = asyncio.run(
                 _run_single_model(
-                    script=script or Path("agent.py"),
-                    servers=server_list,
+                    script=script,
+                    servers=resolved_server_list,
                     url_servers=url_servers,
                     stdio_servers=stdio_servers,
                     model=model,

src/mcp_agent/cli/commands/dev.py

@@ -15,14 +15,15 @@
 from rich.console import Console
 
 from mcp_agent.config import get_settings
+from mcp_agent.cli.core.utils import detect_default_script
 
 
 app = typer.Typer(help="Run app locally with diagnostics")
 console = Console()
 
 
 @app.callback(invoke_without_command=True)
-def dev(script: Path = typer.Option(Path("agent.py"), "--script")) -> None:
+def dev(script: Path = typer.Option(None, "--script")) -> None:
     """Run the user's app script with optional live reload and preflight checks."""
 
     def _preflight_ok() -> bool:
@@ -49,6 +50,9 @@ def _run_script() -> subprocess.Popen:
             stdin=None,  # Inherit stdin
         )
 
+    # Resolve script path with auto-detection (main.py preferred)
+    script = detect_default_script(script)
+
     # Simple preflight
     _ = _preflight_ok()
 

src/mcp_agent/cli/commands/doctor.py

@@ -412,7 +412,7 @@ def doctor() -> None:
             "• Add API key: [cyan]mcp-agent keys set <provider> <key>[/cyan]\n"
             "• Add server: [cyan]mcp-agent server add recipe filesystem[/cyan]\n"
             "• Start chat: [cyan]mcp-agent chat --model anthropic.haiku[/cyan]\n"
-            "• Run agent: [cyan]mcp-agent dev --script agent.py[/cyan]",
+            "• Run agent: [cyan]mcp-agent dev start --script main.py[/cyan]",
             title="Getting Started",
             border_style="dim",
         )

src/mcp_agent/cli/commands/go.py

@@ -18,6 +18,8 @@
     attach_stdio_servers,
     attach_url_servers,
     load_user_app,
+    detect_default_script,
+    select_servers_from_config,
 )
 from mcp_agent.cli.utils.url_parser import generate_server_configs, parse_server_urls
 from mcp_agent.workflows.factory import create_llm
@@ -268,8 +270,11 @@ def go(
     npx: Optional[str] = typer.Option(None, "--npx"),
     uvx: Optional[str] = typer.Option(None, "--uvx"),
     stdio: Optional[str] = typer.Option(None, "--stdio"),
-    script: Optional[Path] = typer.Option(Path("agent.py"), "--script"),
+    script: Optional[Path] = typer.Option(None, "--script"),
 ) -> None:
+    # Resolve script with auto-detection
+    script = detect_default_script(script)
+
     # Parse server names from config if provided
     server_list = servers.split(",") if servers else None
 
@@ -302,6 +307,11 @@ def go(
         else:
             server_list.extend(list(stdio_servers.keys()))
 
+    # Smart defaults from config if still unspecified
+    resolved_server_list = select_servers_from_config(
+        ",".join(server_list) if server_list else None, url_servers, stdio_servers
+    )
+
     # Multi-model support if comma-separated
     if model and "," in model:
         models = [m.strip() for m in model.split(",") if m.strip()]
@@ -311,7 +321,7 @@ def go(
                 asyncio.run(
                     _run_agent(
                         app_script=script,
-                        server_list=server_list,
+                        server_list=resolved_server_list,
                         model=m,
                         message=message,
                         prompt_file=prompt_file,
@@ -331,7 +341,7 @@ def go(
         asyncio.run(
             _run_agent(
                 app_script=script,
-                server_list=server_list,
+                server_list=resolved_server_list,
                 model=model,
                 message=message,
                 prompt_file=prompt_file,

src/mcp_agent/cli/commands/init.py

@@ -100,6 +100,7 @@ def init(
     console.print(f"Template: [cyan]{template}[/cyan] - {templates[template]}\n")
 
     files_created = []
+    entry_script_name: str | None = None
 
     # Always create config files
     config_path = dir / "mcp_agent.config.yaml"
@@ -122,15 +123,35 @@ def init(
 
     # Create template-specific files
     if template == "basic":
-        agent_path = dir / "agent.py"
+        # Determine entry script name and handle existing files
+        script_name = "main.py"
+        script_path = dir / script_name
         agent_content = _load_template("basic_agent.py")
-        if agent_content and _write(agent_path, agent_content, force):
-            files_created.append("agent.py")
-            # Make executable
-            try:
-                agent_path.chmod(agent_path.stat().st_mode | 0o111)
-            except Exception:
-                pass
+
+        if agent_content:
+            write_force_flag = force
+            if script_path.exists() and not force:
+                if Confirm.ask(f"{script_path} exists. Overwrite?", default=False):
+                    write_force_flag = True
+                else:
+                    # Ask for an alternate filename and ensure it ends with .py
+                    alt_name = Prompt.ask(
+                        "Enter a filename to save the agent", default="agent.py"
+                    )
+                    if not alt_name.endswith(".py"):
+                        alt_name += ".py"
+                    script_name = alt_name
+                    script_path = dir / script_name
+                    # keep write_force_flag as-is to allow overwrite prompt if needed
+
+            if _write(script_path, agent_content, write_force_flag):
+                files_created.append(script_name)
+                entry_script_name = script_name
+                # Make executable
+                try:
+                    script_path.chmod(script_path.stat().st_mode | 0o111)
+                except Exception:
+                    pass
 
     elif template == "server":
         server_path = dir / "server.py"
@@ -185,20 +206,29 @@ def init(
         console.print("2. Review and customize [cyan]mcp_agent.config.yaml[/cyan]")
 
         if template == "basic":
-            console.print("3. Run your agent: [cyan]python agent.py[/cyan]")
-            console.print("   Or use: [cyan]mcp-agent dev --script agent.py[/cyan]")
-            console.print("   Or chat: [cyan]mcp-agent chat[/cyan]")
+            run_file = entry_script_name or "main.py"
+            console.print(f"3. Run your agent: [cyan]uv run {run_file}[/cyan]")
+            console.print(
+                f"   Or use: [cyan]mcp-agent dev start --script {run_file}[/cyan]"
+            )
+            console.print(
+                f"   Or serve: [cyan]mcp-agent dev serve --script {run_file}[/cyan]"
+            )
+            console.print("   Or chat: [cyan]mcp-agent dev chat[/cyan]")
+            console.print(
+                "4. Edit config: [cyan]mcp-agent config edit[/cyan] (then rerun)"
+            )
         elif template == "server":
-            console.print("3. Run the server: [cyan]python server.py[/cyan]")
+            console.print("3. Run the server: [cyan]uv run server.py[/cyan]")
             console.print(
                 "   Or serve: [cyan]mcp-agent serve --script server.py[/cyan]"
             )
         elif template == "token":
-            console.print("3. Run the example: [cyan]python token_example.py[/cyan]")
+            console.print("3. Run the example: [cyan]uv run token_example.py[/cyan]")
             console.print("   Watch token usage in real-time!")
         elif template == "factory":
             console.print("3. Customize agents in [cyan]agents.yaml[/cyan]")
-            console.print("4. Run the factory: [cyan]python factory.py[/cyan]")
+            console.print("4. Run the factory: [cyan]uv run factory.py[/cyan]")
         elif template == "minimal":
             console.print("3. Create your agent script")
             console.print("   See examples: [cyan]mcp-agent quickstart[/cyan]")