claude-sdk-tutor 0.1.5__tar.gz → 0.1.6__tar.gz

claude_sdk_tutor-0.1.6/CLAUDE.md

@@ -0,0 +1,50 @@
+# Claude SDK Tutor
+
+A terminal-based chat interface for learning programming with Claude. Built with Textual and the Claude Agent SDK, it provides an interactive TUI where Claude acts as a programming tutor rather than simply writing code for you.
+
+## Features
+
+- **Tutor Mode**: Claude guides learning through explanations and hints instead of providing complete solutions
+- **Web Search**: Optional web lookup capability (toggle with `/togglewebsearch`)
+- **MCP Servers**: Connect external tools via Model Context Protocol (stdio, SSE, HTTP transports)
+- **Command History**: Navigate previous commands with up/down arrows (persisted across sessions)
+- **Query Interruption**: Cancel running queries with Escape or Ctrl+C
+
+## Setup
+
+```bash
+uv sync
+```
+
+## Run
+
+```bash
+uv run python app.py
+```
+
+## Slash Commands
+
+- `/help` - Show available commands
+- `/clear` - Clear conversation and reconnect
+- `/tutor` - Toggle tutor mode on/off
+- `/togglewebsearch` - Toggle web search capability
+- `/mcp` - Manage MCP servers (use `/mcp help` for subcommands)
+
+## Architecture
+
+```
+app.py              # Main Textual app with UI and command handling
+src/claude/
+  claude_agent.py   # Claude SDK client creation and streaming
+  widgets.py        # Custom HistoryInput widget with keybindings
+  history.py        # Persistent command history
+  mcp_config.py     # MCP server configuration storage
+  mcp_commands.py   # /mcp command parsing and handlers
+```
+
+## Tech Stack
+
+- Python 3.13+
+- Textual (TUI framework)
+- Claude Agent SDK
+- uv (package manager)

{claude_sdk_tutor-0.1.5 → claude_sdk_tutor-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-sdk-tutor
-Version: 0.1.5
+Version: 0.1.6
 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.5 → claude_sdk_tutor-0.1.6}/README.md

@@ -2,6 +2,15 @@
 
 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:
@@ -45,6 +54,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 |
@@ -53,6 +72,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.6/app.py

@@ -0,0 +1,359 @@
+import json
+
+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 claude.claude_agent import (
+    connect_client,
+    create_claude_client,
+    stream_helpful_claude,
+)
+from claude.history import CommandHistory
+from claude.mcp_commands import McpAsyncCommand, McpCommandHandler
+from claude.mcp_config import McpConfigManager
+from claude.widgets import HistoryInput
+
+
+class MyApp(App):
+    def __init__(self):
+        super().__init__()
+        self.tutor_mode = True
+        self.web_search_enabled = False
+        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
+
+    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(),
+        )
+
+    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 compose(self) -> ComposeResult:
+        with Vertical(id="main"):
+            yield Static("Welcome to claude SDK tutor!", id="header")
+            yield RichLog(markup=True, highlight=True)
+            yield LoadingIndicator(id="spinner")
+            yield HistoryInput(history=self.history)
+        yield Footer()
+
+    async def on_mount(self) -> None:
+        self.query_one("#spinner", LoadingIndicator).display = False
+        await connect_client(self.client)
+
+    def write_user_message(self, message: str) -> None:
+        log = self.query_one(RichLog)
+        log.write(Panel(RichMarkdown(message), title="You", border_style="dodger_blue1"))
+
+    def write_system_message(self, message: str) -> None:
+        log = self.query_one(RichLog)
+        log.write(Panel(RichMarkdown(message), title="Claude", border_style="red"))
+
+    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"))
+
+    def write_slash_message(self, message: str) -> None:
+        log = self.query_one(RichLog)
+        log.write(Panel(RichMarkdown(message), title="Slash", border_style="green"))
+
+    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
+        if command == "/tutor":
+            self.run_worker(self.toggle_tutor_mode())
+            return
+        if command == "/togglewebsearch":
+            self.run_worker(self.toggle_web_search())
+            return
+        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_running = True
+        self.run_worker(self.get_response(event.value))
+
+    async def clear_conversation(self) -> None:
+        self.query_one(RichLog).clear()
+        self.client = self._create_client()
+        await connect_client(self.client)
+        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 = self._create_client()
+        await connect_client(self.client)
+        status = "on" if self.tutor_mode else "off"
+        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 = self._create_client()
+        await connect_client(self.client)
+        status = "on" if self.web_search_enabled else "off"
+        self.write_slash_message(f"Web search {status}")
+
+    def show_help(self) -> None:
+        help_text = """**Available Commands**
+
+- `/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)
+- `/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", LoadingIndicator).display = True
+            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", LoadingIndicator).display = False
+
+    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):
+                if isinstance(message, AssistantMessage):
+                    for block in message.content:
+                        if hasattr(block, "text"):
+                            self.write_system_message(block.text)
+                        elif hasattr(block, "name"):
+                            self.write_tool_message(
+                                block.name, getattr(block, "input", {})
+                            )
+                elif isinstance(message, ResultMessage):
+                    pass  # Might want to add logging later
+        finally:
+            self.query_one("#spinner", LoadingIndicator).display = False
+            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", LoadingIndicator).display = False
+
+
+def main():
+    app = MyApp()
+    app.run()
+
+
+if __name__ == "__main__":
+    main()

{claude_sdk_tutor-0.1.5 → claude_sdk_tutor-0.1.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "claude-sdk-tutor"
-version = "0.1.5"
+version = "0.1.6"
 description = "Add your description here"
 readme = "README.md"
 requires-python = ">=3.13"

{claude_sdk_tutor-0.1.5 → claude_sdk_tutor-0.1.6}/src/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_sdk_tutor-0.1.6/src/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_sdk_tutor-0.1.6/src/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_sdk_tutor-0.1.5 → claude_sdk_tutor-0.1.6}/src/claude/widgets.py

@@ -10,6 +10,8 @@ class HistoryInput(Input):
     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 → claude_sdk_tutor-0.1.6}/uv.lock

@@ -206,7 +206,7 @@ wheels = [
 
 [[package]]
 name = "claude-sdk-tutor"
-version = "0.1.4"
+version = "0.1.5"
 source = { editable = "." }
 dependencies = [
     { name = "claude-agent-sdk" },

claude_sdk_tutor-0.1.5/CLAUDE.md

@@ -1,22 +0,0 @@
-# Personal Claude
-
-A TUI application built with Textual and the Claude Agent SDK.
-
-## Setup
-
-```bash
-uv sync
-```
-
-## Run
-
-```bash
-uv run python main.py
-```
-
-## Tech Stack
-
-- Python 3.13+
-- Textual (TUI framework)
-- Claude Agent SDK
-- uv (package manager)

claude_sdk_tutor-0.1.5/app.py

@@ -1,171 +0,0 @@
-import json
-
-from claude_agent_sdk import AssistantMessage, ResultMessage
-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 claude.claude_agent import (
-    connect_client,
-    create_claude_client,
-    stream_helpful_claude,
-)
-from claude.history import CommandHistory
-from claude.widgets import HistoryInput
-
-
-class MyApp(App):
-    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.history = CommandHistory()
-
-    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 compose(self) -> ComposeResult:
-        with Vertical(id="main"):
-            yield Static("Welcome to claude SDK tutor!", id="header")
-            yield RichLog(markup=True, highlight=True)
-            yield LoadingIndicator(id="spinner")
-            yield HistoryInput(history=self.history)
-        yield Footer()
-
-    async def on_mount(self) -> None:
-        self.query_one("#spinner", LoadingIndicator).display = False
-        await connect_client(self.client)
-
-    def write_user_message(self, message: str) -> None:
-        log = self.query_one(RichLog)
-        log.write(Panel(RichMarkdown(message), title="You", border_style="dodger_blue1"))
-
-    def write_system_message(self, message: str) -> None:
-        log = self.query_one(RichLog)
-        log.write(Panel(RichMarkdown(message), title="Claude", border_style="red"))
-
-    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"))
-
-    def write_slash_message(self, message: str) -> None:
-        log = self.query_one(RichLog)
-        log.write(Panel(RichMarkdown(message), title="Slash", border_style="green"))
-
-    def on_input_submitted(self, event: Input.Submitted) -> None:
-        command = event.value.strip()
-        self.query_one(HistoryInput).value = ""
-        if command:
-            self.history.add(command)
-        if command == "/clear":
-            self.run_worker(self.clear_conversation())
-            return
-        if command == "/tutor":
-            self.run_worker(self.toggle_tutor_mode())
-            return
-        if command == "/togglewebsearch":
-            self.run_worker(self.toggle_web_search())
-            return
-        if command == "/help":
-            self.show_help()
-            return
-        self.write_user_message(event.value)
-        self.query_one("#spinner", LoadingIndicator).display = 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
-        )
-        await connect_client(self.client)
-        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
-        )
-        await connect_client(self.client)
-        status = "on" if self.tutor_mode else "off"
-        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
-        )
-        await connect_client(self.client)
-        status = "on" if self.web_search_enabled else "off"
-        self.write_slash_message(f"Web search {status}")
-
-    def show_help(self) -> None:
-        help_text = """**Available Commands**
-
-- `/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)"""
-        self.write_slash_message(help_text)
-
-    async def get_response(self, text: str) -> None:
-        try:
-            async for message in stream_helpful_claude(self.client, text):
-                if isinstance(message, AssistantMessage):
-                    for block in message.content:
-                        if hasattr(block, "text"):
-                            self.write_system_message(block.text)
-                        elif hasattr(block, "name"):
-                            self.write_tool_message(
-                                block.name, getattr(block, "input", {})
-                            )
-                elif isinstance(message, ResultMessage):
-                    pass  # Might want to add logging later
-        finally:
-            self.query_one("#spinner", LoadingIndicator).display = False
-
-
-def main():
-    app = MyApp()
-    app.run()
-
-
-if __name__ == "__main__":
-    main()