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

claude_sdk_tutor-0.1.7/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.7}/PKG-INFO

@@ -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.5 → claude_sdk_tutor-0.1.7}/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.7/app.py

@@ -0,0 +1,379 @@
+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 rich.box import ROUNDED
+from textual.widgets import Static, Footer, Input, RichLog
+
+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 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.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(),
+        )
+
+    def compose(self) -> ComposeResult:
+        with Vertical(id="main"):
+            yield Static(HEADER_TEXT, id="header")
+            yield StatusBar(id="status-bar")
+            yield RichLog(markup=True, highlight=True)
+            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", 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=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=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=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="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
+        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", 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 = 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 = self._create_client()
+        await connect_client(self.client)
+        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 = self._create_client()
+        await connect_client(self.client)
+        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:
+        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", 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):
+                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", 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():
+    app = MyApp()
+    app.run()
+
+
+if __name__ == "__main__":
+    main()