claude-sdk-tutor 0.1.5__py3-none-any.whl → 0.1.7__py3-none-any.whl

app.py

@@ -1,11 +1,18 @@
 import json
 
-from claude_agent_sdk import AssistantMessage, ResultMessage
+from claude_agent_sdk import (
+    AssistantMessage,
+    ClaudeAgentOptions,
+    ResultMessage,
+    SystemMessage,
+    query,
+)
 from rich.markdown import Markdown as RichMarkdown
 from rich.panel import Panel
 from textual.app import App, ComposeResult
 from textual.containers import Vertical
-from textual.widgets import Static, Footer, Input, RichLog, LoadingIndicator
+from rich.box import ROUNDED
+from textual.widgets import Static, Footer, Input, RichLog
 
 from claude.claude_agent import (
     connect_client,
@@ -13,85 +20,123 @@ from claude.claude_agent import (
     stream_helpful_claude,
 )
 from claude.history import CommandHistory
-from claude.widgets import HistoryInput
+from claude.mcp_commands import McpAsyncCommand, McpCommandHandler
+from claude.mcp_config import McpConfigManager
+from claude.widgets import ASCIISpinner, HistoryInput, StatusBar
+
+
+# Message border colors (vivid)
+USER_COLOR = "#00aaff"      # Vivid cyan-blue
+CLAUDE_COLOR = "#ff3333"    # Vivid red
+TOOL_COLOR = "#cccccc"      # Bright grey
+SYSTEM_COLOR = "#33ff66"    # Vivid green
+
+HEADER_TEXT = "Claude SDK Tutor"
 
 
 class MyApp(App):
+    CSS_PATH = "phosphor.tcss"
+
     def __init__(self):
         super().__init__()
         self.tutor_mode = True
         self.web_search_enabled = False
-        self.client = create_claude_client(
-            tutor_mode=self.tutor_mode, web_search=self.web_search_enabled
-        )
+        self.mcp_config = McpConfigManager()
+        self.mcp_handler = McpCommandHandler(self.mcp_config)
+        self.mcp_add_state: dict | None = None  # For interactive /mcp add wizard
+        self.client = self._create_client()
         self.history = CommandHistory()
+        self._query_running: bool = False  # Track if a query is active
 
-    CSS = """
-    #main {
-        height: 100%;
-    }
-    Input {
-        height: auto;
-        margin-top: 1;
-        margin-left: 3;
-        margin-right: 3;
-        margin-bottom: 1;
-    }
-    #header {
-        content-align: center middle;
-        width: 100%;
-        margin-top: 1;
-        margin-bottom: 1;
-        height: auto;
-    }
-    RichLog {
-        background: $boost;
-        margin-left: 3;
-        margin-right: 3;
-        height: 1fr;
-    }
-    LoadingIndicator {
-        height: auto;
-        margin-left: 3;
-        margin-right: 3;
-    }
-    """
+    def _create_client(self):
+        """Create a new Claude client with current settings."""
+        return create_claude_client(
+            tutor_mode=self.tutor_mode,
+            web_search=self.web_search_enabled,
+            mcp_servers=self.mcp_config.get_enabled_servers_for_sdk(),
+        )
 
     def compose(self) -> ComposeResult:
         with Vertical(id="main"):
-            yield Static("Welcome to claude SDK tutor!", id="header")
+            yield Static(HEADER_TEXT, id="header")
+            yield StatusBar(id="status-bar")
             yield RichLog(markup=True, highlight=True)
-            yield LoadingIndicator(id="spinner")
-            yield HistoryInput(history=self.history)
+            yield ASCIISpinner(id="spinner")
+            yield HistoryInput(
+                history=self.history,
+                placeholder="Type a message or /help for commands...",
+            )
         yield Footer()
 
     async def on_mount(self) -> None:
-        self.query_one("#spinner", LoadingIndicator).display = False
+        self.query_one("#spinner", ASCIISpinner).display = False
+        self._update_status_bar()
         await connect_client(self.client)
 
+    def _update_status_bar(self) -> None:
+        """Update the status bar with current mode states."""
+        status_bar = self.query_one("#status-bar", StatusBar)
+        status_bar.tutor_on = self.tutor_mode
+        status_bar.web_on = self.web_search_enabled
+        status_bar.mcp_count = len(self.mcp_config.get_enabled_servers_for_sdk())
+
     def write_user_message(self, message: str) -> None:
         log = self.query_one(RichLog)
-        log.write(Panel(RichMarkdown(message), title="You", border_style="dodger_blue1"))
+        log.write(Panel(
+            RichMarkdown(message),
+            title="You",
+            border_style=USER_COLOR,
+            box=ROUNDED,
+            padding=(1, 2),
+        ))
 
     def write_system_message(self, message: str) -> None:
         log = self.query_one(RichLog)
-        log.write(Panel(RichMarkdown(message), title="Claude", border_style="red"))
+        log.write(Panel(
+            RichMarkdown(message),
+            title="Claude",
+            border_style=CLAUDE_COLOR,
+            box=ROUNDED,
+            padding=(1, 2),
+        ))
 
     def write_tool_message(self, name: str, input: dict) -> None:
         log = self.query_one(RichLog)
         input_str = json.dumps(input, indent=2)
         content = f"**{name}**\n```json\n{input_str}\n```"
-        log.write(Panel(RichMarkdown(content), title="Tool", border_style="grey50"))
+        log.write(Panel(
+            RichMarkdown(content),
+            title="Tool",
+            border_style=TOOL_COLOR,
+            box=ROUNDED,
+            padding=(1, 2),
+        ))
 
     def write_slash_message(self, message: str) -> None:
         log = self.query_one(RichLog)
-        log.write(Panel(RichMarkdown(message), title="Slash", border_style="green"))
+        log.write(Panel(
+            RichMarkdown(message),
+            title="System",
+            border_style=SYSTEM_COLOR,
+            box=ROUNDED,
+            padding=(1, 2),
+        ))
 
     def on_input_submitted(self, event: Input.Submitted) -> None:
         command = event.value.strip()
         self.query_one(HistoryInput).value = ""
         if command:
             self.history.add(command)
+
+        # Handle interactive MCP add wizard
+        if self.mcp_add_state is not None:
+            if command.lower() == "/cancel":
+                self.mcp_add_state = None
+                self.write_slash_message("Cancelled MCP server setup.")
+                return
+            self._handle_mcp_add_step(command)
+            return
+
         if command == "/clear":
             self.run_worker(self.clear_conversation())
             return
@@ -104,36 +149,37 @@ class MyApp(App):
         if command == "/help":
             self.show_help()
             return
+        if command.lower().startswith("/mcp"):
+            self._handle_mcp_command(command)
+            return
         self.write_user_message(event.value)
-        self.query_one("#spinner", LoadingIndicator).display = True
+        self.query_one("#spinner", ASCIISpinner).start("Processing query...")
+        self._query_running = True
         self.run_worker(self.get_response(event.value))
 
     async def clear_conversation(self) -> None:
         self.query_one(RichLog).clear()
-        self.client = create_claude_client(
-            tutor_mode=self.tutor_mode, web_search=self.web_search_enabled
-        )
+        self.client = self._create_client()
         await connect_client(self.client)
+        self._update_status_bar()
         self.write_slash_message("Context cleared")
 
     async def toggle_tutor_mode(self) -> None:
         self.tutor_mode = not self.tutor_mode
         self.query_one(RichLog).clear()
-        self.client = create_claude_client(
-            tutor_mode=self.tutor_mode, web_search=self.web_search_enabled
-        )
+        self.client = self._create_client()
         await connect_client(self.client)
-        status = "on" if self.tutor_mode else "off"
+        self._update_status_bar()
+        status = "enabled" if self.tutor_mode else "disabled"
         self.write_slash_message(f"Tutor mode {status}")
 
     async def toggle_web_search(self) -> None:
         self.web_search_enabled = not self.web_search_enabled
         self.query_one(RichLog).clear()
-        self.client = create_claude_client(
-            tutor_mode=self.tutor_mode, web_search=self.web_search_enabled
-        )
+        self.client = self._create_client()
         await connect_client(self.client)
-        status = "on" if self.web_search_enabled else "off"
+        self._update_status_bar()
+        status = "enabled" if self.web_search_enabled else "disabled"
         self.write_slash_message(f"Web search {status}")
 
     def show_help(self) -> None:
@@ -142,9 +188,154 @@ class MyApp(App):
 - `/help` - Show this help message
 - `/clear` - Clear conversation history and start fresh
 - `/tutor` - Toggle tutor mode on/off (guides learning vs gives code)
-- `/togglewebsearch` - Toggle web search on/off (allows online lookups)"""
+- `/togglewebsearch` - Toggle web search on/off (allows online lookups)
+- `/mcp` - Manage MCP servers (use `/mcp help` for details)"""
         self.write_slash_message(help_text)
 
+    def _handle_mcp_command(self, command: str) -> None:
+        """Handle /mcp commands."""
+        result = self.mcp_handler.handle_command(command)
+        if result is None:
+            # Start interactive add wizard
+            self.mcp_add_state = {"step": 0, "name": "", "type": "", "data": {}}
+            self.write_slash_message(
+                "**Add MCP Server**\n\nEnter server name (or `/cancel` to abort):"
+            )
+        elif isinstance(result, McpAsyncCommand):
+            # Async command needs connection testing
+            self.query_one("#spinner", ASCIISpinner).start("Testing MCP connections...")
+            self.run_worker(self._test_mcp_connections(result))
+        else:
+            self.write_slash_message(result)
+
+    async def _test_mcp_connections(self, cmd: McpAsyncCommand) -> None:
+        """Test MCP server connections and display results."""
+        try:
+            mcp_servers = self.mcp_config.get_enabled_servers_for_sdk()
+            if not mcp_servers:
+                if cmd.command == "test":
+                    self.write_slash_message(
+                        "**MCP Test**\n\nNo enabled servers to test."
+                    )
+                else:
+                    self.write_slash_message(
+                        self.mcp_handler.handle_list(cmd.args, connection_status=None)
+                    )
+                return
+
+            # Build allowed tools for the test
+            allowed_tools = [f"mcp__{name}__*" for name in mcp_servers]
+
+            options = ClaudeAgentOptions(
+                mcp_servers=mcp_servers,
+                allowed_tools=allowed_tools,
+                max_turns=1,
+            )
+
+            connection_status: dict[str, str] = {}
+
+            # Run a minimal query just to get the init message with MCP status
+            async for message in query(prompt="test", options=options):
+                if isinstance(message, SystemMessage) and message.subtype == "init":
+                    mcp_info = message.data.get("mcp_servers", [])
+                    for server in mcp_info:
+                        name = server.get("name", "unknown")
+                        status = server.get("status", "unknown")
+                        connection_status[name] = status
+                    break
+
+            # Display results based on command
+            if cmd.command == "test":
+                self.write_slash_message(
+                    self.mcp_handler.handle_test(cmd.args, connection_status)
+                )
+            else:  # list
+                self.write_slash_message(
+                    self.mcp_handler.handle_list(cmd.args, connection_status)
+                )
+        except Exception as e:
+            self.write_slash_message(f"**Error** testing MCP connections: {e}")
+        finally:
+            self.query_one("#spinner", ASCIISpinner).stop()
+
+    def _handle_mcp_add_step(self, user_input: str) -> None:
+        """Handle a step in the interactive MCP add wizard."""
+        state = self.mcp_add_state
+        if state is None:
+            return
+
+        step = state["step"]
+
+        if step == 0:
+            # Got server name
+            name = user_input.strip()
+            if not name:
+                self.write_slash_message("**Error**: Name cannot be empty. Try again:")
+                return
+            if self.mcp_config.get_server(name):
+                self.write_slash_message(
+                    f"**Error**: Server `{name}` already exists. Enter a different name:"
+                )
+                return
+            state["name"] = name
+            state["step"] = 1
+            self.write_slash_message(
+                "Select server type:\n- `stdio` - Local process\n- `sse` - Server-Sent Events\n- `http` - HTTP endpoint"
+            )
+
+        elif step == 1:
+            # Got server type
+            server_type = user_input.strip().lower()
+            if server_type not in ("stdio", "sse", "http"):
+                self.write_slash_message(
+                    f"**Error**: Invalid type `{server_type}`. Enter `stdio`, `sse`, or `http`:"
+                )
+                return
+            state["type"] = server_type
+            state["step"] = 2
+            if server_type == "stdio":
+                self.write_slash_message("Enter command to run (e.g., `npx`):")
+            else:
+                self.write_slash_message("Enter server URL:")
+
+        elif step == 2:
+            # Got command or URL
+            value = user_input.strip()
+            if not value:
+                self.write_slash_message("**Error**: Value cannot be empty. Try again:")
+                return
+
+            if state["type"] == "stdio":
+                state["data"]["command"] = value
+                state["step"] = 3
+                self.write_slash_message(
+                    "Enter arguments (space-separated, or leave empty):"
+                )
+            else:
+                # SSE or HTTP - URL provided, we're done
+                config = {"type": state["type"], "url": value}
+                self.mcp_config.add_server(state["name"], config)
+                self.write_slash_message(
+                    f"**Added** server `{state['name']}` ({state['type']})\n\n"
+                    "Use `/clear` to reconnect with new MCP servers."
+                )
+                self.mcp_add_state = None
+
+        elif step == 3:
+            # Got args for stdio command
+            args = user_input.strip().split() if user_input.strip() else []
+            config = {
+                "type": "stdio",
+                "command": state["data"]["command"],
+                "args": args,
+            }
+            self.mcp_config.add_server(state["name"], config)
+            self.write_slash_message(
+                f"**Added** server `{state['name']}` (stdio)\n\n"
+                "Use `/clear` to reconnect with new MCP servers."
+            )
+            self.mcp_add_state = None
+
     async def get_response(self, text: str) -> None:
         try:
             async for message in stream_helpful_claude(self.client, text):
@@ -159,7 +350,24 @@ class MyApp(App):
                 elif isinstance(message, ResultMessage):
                     pass  # Might want to add logging later
         finally:
-            self.query_one("#spinner", LoadingIndicator).display = False
+            self.query_one("#spinner", ASCIISpinner).stop()
+            self._query_running = False
+
+    def action_cancel_query(self) -> None:
+        """Interrupt the current running query using SDK interrupt."""
+        if self._query_running:
+            self.run_worker(self._interrupt_query())
+
+    async def _interrupt_query(self) -> None:
+        """Send interrupt signal to the Claude SDK client."""
+        try:
+            await self.client.interrupt()
+            self.write_slash_message("Query interrupted.")
+        except Exception:
+            pass  # Ignore errors if not connected or no active query
+        finally:
+            self._query_running = False
+            self.query_one("#spinner", ASCIISpinner).stop()
 
 
 def main():

claude/claude_agent.py

@@ -13,12 +13,18 @@ Never write complete solutions for them. Instead, help them develop the skills t
 
 
 def create_claude_client(
-    tutor_mode: bool = True, web_search: bool = False
+    tutor_mode: bool = True,
+    web_search: bool = False,
+    mcp_servers: dict | None = None,
 ) -> ClaudeSDKClient:
     tools = ["Read", "Glob", "Grep"]
     if web_search:
         tools.extend(["WebSearch", "WebFetch"])
-    options = ClaudeAgentOptions(allowed_tools=tools)
+    if mcp_servers:
+        # Allow all tools from each configured MCP server
+        for server_name in mcp_servers:
+            tools.append(f"mcp__{server_name}__*")
+    options = ClaudeAgentOptions(allowed_tools=tools, mcp_servers=mcp_servers or {})
     if tutor_mode:
         options.system_prompt = TUTOR_SYSTEM_PROMPT
     return ClaudeSDKClient(options=options)

claude/mcp_commands.py

@@ -0,0 +1,256 @@
+"""MCP command handling for slash commands."""
+
+from dataclasses import dataclass
+
+from .mcp_config import McpConfigManager, McpServerEntry
+
+
+@dataclass
+class McpAsyncCommand:
+    """Indicates an async command that needs special handling."""
+
+    command: str
+    args: list[str]
+
+
+class McpCommandHandler:
+    """Handles /mcp slash commands."""
+
+    def __init__(self, config_manager: McpConfigManager):
+        self.config = config_manager
+
+    def parse_command(self, command: str) -> tuple[str, list[str]]:
+        """Parse /mcp command into subcommand and args.
+
+        Example: "/mcp add myserver" -> ("add", ["myserver"])
+        """
+        parts = command.strip().split()
+        # Remove /mcp prefix if present
+        if parts and parts[0].lower() == "/mcp":
+            parts = parts[1:]
+
+        if not parts:
+            return "help", []
+
+        subcommand = parts[0].lower()
+        args = parts[1:]
+        return subcommand, args
+
+    def handle_command(self, command: str) -> str | None | McpAsyncCommand:
+        """Handle a /mcp command.
+
+        Returns:
+            str: Markdown response to display
+            None: Trigger interactive mode
+            McpAsyncCommand: Command needs async handling
+        """
+        subcommand, args = self.parse_command(command)
+
+        # Commands that need async handling (connection testing)
+        if subcommand in ("test", "list"):
+            return McpAsyncCommand(command=subcommand, args=args)
+
+        handlers = {
+            "add": self.handle_add,
+            "remove": self.handle_remove,
+            "enable": self.handle_enable,
+            "disable": self.handle_disable,
+            "status": self.handle_status,
+            "help": self.handle_help,
+        }
+
+        handler = handlers.get(subcommand, self.handle_help)
+        return handler(args)
+
+    def handle_list(
+        self, _args: list[str], connection_status: dict[str, str] | None = None
+    ) -> str:
+        """List all configured MCP servers with optional connection status."""
+        servers = self.config.list_servers()
+
+        if not servers:
+            return "**MCP Servers**\n\nNo servers configured. Use `/mcp add` to add one."
+
+        lines = ["**MCP Servers**\n"]
+        lines.append("| Name | Type | Enabled | Connection | Target |")
+        lines.append("|------|------|---------|------------|--------|")
+
+        for server in servers:
+            server_type = server.config.get("type", "stdio")
+            enabled = "yes" if server.enabled else "no"
+            target = self._get_target_display(server)
+
+            if connection_status and server.name in connection_status:
+                conn = connection_status[server.name]
+            elif not server.enabled:
+                conn = "—"
+            else:
+                conn = "unknown"
+
+            lines.append(
+                f"| {server.name} | {server_type} | {enabled} | {conn} | {target} |"
+            )
+
+        return "\n".join(lines)
+
+    def handle_test(
+        self, args: list[str], connection_status: dict[str, str]
+    ) -> str:
+        """Format test results for MCP server connections."""
+        if not connection_status:
+            return "**MCP Test**\n\nNo enabled servers to test."
+
+        # Filter to specific server if provided
+        if args:
+            name = args[0]
+            if name not in connection_status:
+                server = self.config.get_server(name)
+                if not server:
+                    return f"**Error**: Server `{name}` not found."
+                if not server.enabled:
+                    return f"**Error**: Server `{name}` is disabled."
+                return f"**Error**: Server `{name}` was not tested."
+            connection_status = {name: connection_status[name]}
+
+        lines = ["**MCP Connection Test**\n"]
+
+        connected = 0
+        failed = 0
+        for name, status in connection_status.items():
+            if status == "connected":
+                lines.append(f"- `{name}`: **connected**")
+                connected += 1
+            else:
+                lines.append(f"- `{name}`: **{status}**")
+                failed += 1
+
+        lines.append(f"\n**Summary**: {connected} connected, {failed} failed")
+        return "\n".join(lines)
+
+    def _get_target_display(self, server: McpServerEntry) -> str:
+        """Get display string for server target."""
+        config = server.config
+        server_type = config.get("type", "")
+
+        if server_type == "stdio":
+            cmd = config.get("command", "")
+            args = config.get("args", [])
+            if args:
+                return f"{cmd} {' '.join(args[:2])}{'...' if len(args) > 2 else ''}"
+            return cmd
+        elif server_type in ("sse", "http"):
+            return config.get("url", "")
+        return "—"
+
+    def handle_add(self, args: list[str]) -> str | None:
+        """Handle /mcp add command.
+
+        If args provided: /mcp add <name> <type> <command/url> [args...]
+        If no args: return None to trigger interactive mode
+        """
+        if not args:
+            return None  # Trigger interactive mode
+
+        if len(args) < 3:
+            return "**Error**: Usage: `/mcp add <name> <type> <command|url> [args...]`"
+
+        name = args[0]
+        server_type = args[1].lower()
+
+        if server_type not in ("stdio", "sse", "http"):
+            return f"**Error**: Invalid type `{server_type}`. Must be stdio, sse, or http."
+
+        if self.config.get_server(name):
+            return f"**Error**: Server `{name}` already exists."
+
+        if server_type == "stdio":
+            command = args[2]
+            cmd_args = args[3:] if len(args) > 3 else []
+            config = {"type": "stdio", "command": command, "args": cmd_args}
+        else:
+            url = args[2]
+            config = {"type": server_type, "url": url}
+
+        self.config.add_server(name, config)
+        return f"**Added** server `{name}` ({server_type})"
+
+    def handle_remove(self, args: list[str]) -> str:
+        """Handle /mcp remove <name> command."""
+        if not args:
+            return "**Error**: Usage: `/mcp remove <name>`"
+
+        name = args[0]
+        if self.config.remove_server(name):
+            return f"**Removed** server `{name}`"
+        return f"**Error**: Server `{name}` not found."
+
+    def handle_enable(self, args: list[str]) -> str:
+        """Handle /mcp enable <name> command."""
+        if not args:
+            return "**Error**: Usage: `/mcp enable <name>`"
+
+        name = args[0]
+        if self.config.enable_server(name):
+            return f"**Enabled** server `{name}`"
+        return f"**Error**: Server `{name}` not found."
+
+    def handle_disable(self, args: list[str]) -> str:
+        """Handle /mcp disable <name> command."""
+        if not args:
+            return "**Error**: Usage: `/mcp disable <name>`"
+
+        name = args[0]
+        if self.config.disable_server(name):
+            return f"**Disabled** server `{name}`"
+        return f"**Error**: Server `{name}` not found."
+
+    def handle_status(self, args: list[str]) -> str:
+        """Handle /mcp status [name] command."""
+        if not args:
+            # Show summary status
+            servers = self.config.list_servers()
+            enabled = sum(1 for s in servers if s.enabled)
+            return f"**MCP Status**: {enabled}/{len(servers)} servers enabled"
+
+        name = args[0]
+        server = self.config.get_server(name)
+        if not server:
+            return f"**Error**: Server `{name}` not found."
+
+        lines = [f"**Server: {name}**\n"]
+        lines.append(f"- **Type**: {server.config.get('type', 'unknown')}")
+        lines.append(f"- **Status**: {'enabled' if server.enabled else 'disabled'}")
+
+        server_type = server.config.get("type", "")
+        if server_type == "stdio":
+            cmd = server.config.get("command", "")
+            args_list = server.config.get("args", [])
+            full_cmd = f"{cmd} {' '.join(args_list)}".strip()
+            lines.append(f"- **Command**: `{full_cmd}`")
+            env = server.config.get("env", {})
+            if env:
+                lines.append(f"- **Env vars**: {', '.join(env.keys())}")
+        else:
+            url = server.config.get("url", "")
+            lines.append(f"- **URL**: {url}")
+
+        return "\n".join(lines)
+
+    def handle_help(self, _args: list[str]) -> str:
+        """Show help for /mcp commands."""
+        return """**MCP Server Commands**
+
+- `/mcp list` - List all configured servers with connection status
+- `/mcp test [name]` - Test MCP server connections
+- `/mcp add` - Add a new server (interactive)
+- `/mcp add <name> <type> <cmd|url> [args]` - Add server directly
+- `/mcp remove <name>` - Remove a server
+- `/mcp enable <name>` - Enable a server
+- `/mcp disable <name>` - Disable a server
+- `/mcp status [name]` - Show server config details
+- `/mcp help` - Show this help
+
+**Server Types**
+- `stdio` - Local process (command + args)
+- `sse` - Server-Sent Events endpoint (URL)
+- `http` - HTTP endpoint (URL)"""

claude/mcp_config.py

@@ -0,0 +1,140 @@
+"""MCP Server configuration management."""
+
+import json
+import os
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class McpServerEntry:
+    """An MCP server configuration entry."""
+
+    name: str
+    enabled: bool
+    config: dict[str, Any]
+
+
+@dataclass
+class McpConfig:
+    """Full MCP configuration."""
+
+    version: int = 1
+    servers: dict[str, dict[str, Any]] = field(default_factory=dict)
+
+
+class McpConfigManager:
+    """Manages MCP server configurations with persistent storage."""
+
+    CONFIG_DIR = Path.home() / ".local" / "share" / "claude-sdk-tutor"
+    CONFIG_FILE = CONFIG_DIR / "mcp_servers.json"
+
+    def __init__(self):
+        self._config: McpConfig = McpConfig()
+        self._load()
+
+    def _load(self) -> None:
+        """Load configuration from disk."""
+        if self.CONFIG_FILE.exists():
+            try:
+                with open(self.CONFIG_FILE) as f:
+                    data = json.load(f)
+                self._config = McpConfig(
+                    version=data.get("version", 1),
+                    servers=data.get("servers", {}),
+                )
+            except (json.JSONDecodeError, OSError):
+                self._config = McpConfig()
+        else:
+            self._config = McpConfig()
+
+    def _save(self) -> None:
+        """Save configuration to disk."""
+        self.CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+        with open(self.CONFIG_FILE, "w") as f:
+            json.dump(
+                {"version": self._config.version, "servers": self._config.servers},
+                f,
+                indent=2,
+            )
+
+    def list_servers(self) -> list[McpServerEntry]:
+        """List all configured servers."""
+        entries = []
+        for name, data in self._config.servers.items():
+            entries.append(
+                McpServerEntry(
+                    name=name,
+                    enabled=data.get("enabled", True),
+                    config=data.get("config", {}),
+                )
+            )
+        return entries
+
+    def get_server(self, name: str) -> McpServerEntry | None:
+        """Get a specific server by name."""
+        if name not in self._config.servers:
+            return None
+        data = self._config.servers[name]
+        return McpServerEntry(
+            name=name,
+            enabled=data.get("enabled", True),
+            config=data.get("config", {}),
+        )
+
+    def add_server(self, name: str, config: dict[str, Any]) -> None:
+        """Add a new server configuration."""
+        self._config.servers[name] = {"enabled": True, "config": config}
+        self._save()
+
+    def remove_server(self, name: str) -> bool:
+        """Remove a server configuration. Returns True if removed."""
+        if name in self._config.servers:
+            del self._config.servers[name]
+            self._save()
+            return True
+        return False
+
+    def enable_server(self, name: str) -> bool:
+        """Enable a server. Returns True if server exists."""
+        if name in self._config.servers:
+            self._config.servers[name]["enabled"] = True
+            self._save()
+            return True
+        return False
+
+    def disable_server(self, name: str) -> bool:
+        """Disable a server. Returns True if server exists."""
+        if name in self._config.servers:
+            self._config.servers[name]["enabled"] = False
+            self._save()
+            return True
+        return False
+
+    def _expand_env_vars(self, value: Any) -> Any:
+        """Recursively expand environment variables in config values."""
+        if isinstance(value, str):
+            # Match ${VAR_NAME} pattern
+            pattern = r"\$\{([^}]+)\}"
+            matches = re.findall(pattern, value)
+            result = value
+            for var_name in matches:
+                env_value = os.environ.get(var_name, "")
+                result = result.replace(f"${{{var_name}}}", env_value)
+            return result
+        elif isinstance(value, dict):
+            return {k: self._expand_env_vars(v) for k, v in value.items()}
+        elif isinstance(value, list):
+            return [self._expand_env_vars(item) for item in value]
+        return value
+
+    def get_enabled_servers_for_sdk(self) -> dict[str, dict[str, Any]]:
+        """Get enabled servers in SDK-compatible format with env vars expanded."""
+        result = {}
+        for name, data in self._config.servers.items():
+            if data.get("enabled", True):
+                config = data.get("config", {})
+                result[name] = self._expand_env_vars(config)
+        return result

claude/widgets.py

@@ -1,15 +1,75 @@
 from textual.binding import Binding
-from textual.widgets import Input
+from textual.reactive import reactive
+from textual.widgets import Input, Static
 
 from claude.history import CommandHistory
 
 
+class StatusBar(Static):
+    """Reactive status bar showing tutor/web/mcp states."""
+
+    tutor_on: reactive[bool] = reactive(True)
+    web_on: reactive[bool] = reactive(False)
+    mcp_count: reactive[int] = reactive(0)
+
+    def render(self) -> str:
+        tutor = "on" if self.tutor_on else "off"
+        web = "on" if self.web_on else "off"
+        mcp = f"{self.mcp_count} server{'s' if self.mcp_count != 1 else ''}"
+        return f"tutor: {tutor}  ·  web: {web}  ·  mcp: {mcp}"
+
+
+class ASCIISpinner(Static):
+    """Minimal spinner that cycles through frames with a label."""
+
+    SPINNER_FRAMES = ["·  ", "·· ", "···", " ··", "  ·", "   "]
+
+    _frame: reactive[int] = reactive(0)
+    _label: reactive[str] = reactive("")
+    _running: reactive[bool] = reactive(False)
+
+    def __init__(self, label: str = "Processing...", **kwargs):
+        super().__init__(**kwargs)
+        self._label = label
+        self._timer = None
+
+    def render(self) -> str:
+        if not self._running:
+            return ""
+        frame = self.SPINNER_FRAMES[self._frame % len(self.SPINNER_FRAMES)]
+        return f"{frame} {self._label}"
+
+    def start(self, label: str = "Processing query...") -> None:
+        """Start the spinner animation."""
+        self._label = label
+        self._running = True
+        self._frame = 0
+        self.display = True
+        if self._timer is None:
+            self._timer = self.set_interval(0.1, self._advance_frame)
+
+    def stop(self) -> None:
+        """Stop the spinner animation."""
+        self._running = False
+        self.display = False
+        if self._timer is not None:
+            self._timer.stop()
+            self._timer = None
+
+    def _advance_frame(self) -> None:
+        """Advance to the next spinner frame."""
+        if self._running:
+            self._frame = (self._frame + 1) % len(self.SPINNER_FRAMES)
+
+
 class HistoryInput(Input):
     """Input widget with command history navigation."""
 
     BINDINGS = [
         Binding("up", "history_previous", "Previous command", show=False),
         Binding("down", "history_next", "Next command", show=False),
+        Binding("escape", "app.cancel_query", "Cancel", show=False),
+        Binding("ctrl+c", "app.cancel_query", "Cancel", show=False),
     ]
 
     def __init__(self, history: CommandHistory, **kwargs):

{claude_sdk_tutor-0.1.5.dist-info → claude_sdk_tutor-0.1.7.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-sdk-tutor
-Version: 0.1.5
+Version: 0.1.7
 Summary: Add your description here
 License-File: LICENSE
 Requires-Python: >=3.13
@@ -15,6 +15,15 @@ Description-Content-Type: text/markdown
 
 A terminal-based programming tutor powered by Claude. Built with Textual and the Claude Agent SDK.
 
+## Features
+
+- **Tutor Mode** - Claude guides your learning instead of writing code for you
+- **Web Search** - Optional online lookup capability
+- **MCP Servers** - Extend Claude with external tools via Model Context Protocol
+- **Command History** - Navigate previous commands with up/down arrows (persisted across sessions)
+- **Query Interruption** - Cancel long-running queries with Escape or Ctrl+C
+- **File Access** - Claude can read files in your codebase to provide contextual help
+
 ## Overview
 
 Claude Tutor is a TUI (Terminal User Interface) application designed to help you learn programming concepts. Unlike a typical coding assistant, Claude Tutor focuses on teaching rather than writing code for you. It will:
@@ -58,6 +67,16 @@ Type your programming questions in the input field and press Enter to send. Clau
 - **Grey** - Tool usage (when Claude reads files in your codebase)
 - **Green** - Slash command feedback
 
+### Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| `Enter` | Send message |
+| `Up` / `Down` | Navigate command history |
+| `Escape` or `Ctrl+C` | Cancel running query |
+
+Command history is automatically saved between sessions.
+
 ## Slash Commands
 
 | Command | Description |
@@ -66,6 +85,45 @@ Type your programming questions in the input field and press Enter to send. Clau
 | `/clear` | Clears the conversation history and starts fresh. Your settings are preserved. |
 | `/tutor` | Toggles tutor mode on/off. When on (default), Claude acts as a teacher. When off, Claude responds normally without the tutoring constraints. |
 | `/togglewebsearch` | Toggles web search on/off. When on, Claude can use WebSearch and WebFetch tools to look up information online. Disabled by default. |
+| `/mcp` | Manage MCP servers. Use `/mcp help` for detailed subcommands. |
+
+## MCP Server Support
+
+Claude Tutor supports [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) servers, allowing you to extend Claude's capabilities with external tools.
+
+### MCP Commands
+
+| Command | Description |
+|---------|-------------|
+| `/mcp list` | List all configured servers with connection status |
+| `/mcp test [name]` | Test MCP server connections |
+| `/mcp add` | Add a new server (interactive wizard) |
+| `/mcp add <name> <type> <cmd\|url> [args]` | Add server directly |
+| `/mcp remove <name>` | Remove a server |
+| `/mcp enable <name>` | Enable a disabled server |
+| `/mcp disable <name>` | Disable a server without removing it |
+| `/mcp status [name]` | Show server configuration details |
+
+### Server Types
+
+- **stdio** - Local process that communicates via stdin/stdout (e.g., `npx` packages)
+- **sse** - Server-Sent Events endpoint
+- **http** - HTTP endpoint
+
+### Example: Adding an MCP Server
+
+```
+/mcp add filesystem stdio npx -y @anthropic/mcp-filesystem
+```
+
+Or use the interactive wizard:
+```
+/mcp add
+```
+
+After adding or modifying servers, use `/clear` to reconnect with the updated configuration.
+
+MCP server configurations are persisted to `~/.local/share/claude-sdk-tutor/mcp_servers.json`.
 
 ## Tech Stack
 

claude_sdk_tutor-0.1.7.dist-info/RECORD

@@ -0,0 +1,12 @@
+app.py,sha256=iTxl7N0Y8ED1zB0LUSc3jodpiRLjjVR6TWvKHdKOa7s,14203
+claude/__init__.py,sha256=rGXaYQtfDG3XywfxU_vHUR5afA_ArxLxzprR04pSnZM,128
+claude/claude_agent.py,sha256=L-Q1qE1f50UvQ-bckpimHySF5Wek2F1kK9ZfCdwuXdg,1546
+claude/history.py,sha256=-JpVhha552jZkyxuaLbbL2GluQXvFzGmhS6mtB63940,2273
+claude/mcp_commands.py,sha256=O3jKPCkk5l2JuB8aBoZbxE5w1yOX6cHECAVAGX7tKK8,9051
+claude/mcp_config.py,sha256=Ot-S8YweTog80C2MBDjtOdpfwjneaqQmLoTINVdOaxY,4637
+claude/widgets.py,sha256=fIpoV0UMtIcR5W315wxe2Cz6KLxJovWJQQn1acnRXoU,2960
+claude_sdk_tutor-0.1.7.dist-info/METADATA,sha256=JnzBT4rW2BzMCkL8L_wWzGF3vTkHpZGw-NpUBcjwVxE,4519
+claude_sdk_tutor-0.1.7.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+claude_sdk_tutor-0.1.7.dist-info/entry_points.txt,sha256=vI78kiiqb59KzHEa8UsnkvCbmCs0IMLXOuO2qiho4U4,46
+claude_sdk_tutor-0.1.7.dist-info/licenses/LICENSE,sha256=KzxybQVVAEGBifrjNj5OGwQ_rsbzCIGPm0xrTL6-VZs,1067
+claude_sdk_tutor-0.1.7.dist-info/RECORD,,

claude_sdk_tutor-0.1.5.dist-info/RECORD

@@ -1,10 +0,0 @@
-app.py,sha256=rZvIJ18RaJSR1PLe6lN-4GrAthzB_lYOi5o549N71DA,5883
-claude/__init__.py,sha256=rGXaYQtfDG3XywfxU_vHUR5afA_ArxLxzprR04pSnZM,128
-claude/claude_agent.py,sha256=-xs3CNr5p2AosKy6UJvf6nTQLdJd8GG7qtS4jd6K_ts,1304
-claude/history.py,sha256=-JpVhha552jZkyxuaLbbL2GluQXvFzGmhS6mtB63940,2273
-claude/widgets.py,sha256=yYhoxhiEhYK1PjTKNB3YYbCIvEl1SrjhhGFknGNcADM,902
-claude_sdk_tutor-0.1.5.dist-info/METADATA,sha256=bbocPf-vW0ZI00XJaSCBmaCozQ5j0_NCaJ2UzTT7Cw8,2480
-claude_sdk_tutor-0.1.5.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-claude_sdk_tutor-0.1.5.dist-info/entry_points.txt,sha256=vI78kiiqb59KzHEa8UsnkvCbmCs0IMLXOuO2qiho4U4,46
-claude_sdk_tutor-0.1.5.dist-info/licenses/LICENSE,sha256=KzxybQVVAEGBifrjNj5OGwQ_rsbzCIGPm0xrTL6-VZs,1067
-claude_sdk_tutor-0.1.5.dist-info/RECORD,,