textual-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MCP server that lets AI agents launch, interact with, and inspect Textual TUI applications headlessly via the Model Context Protocol. Uses Textual's built-in Pilot testing API to drive apps without a terminal.

Commands

# Install (editable, with dev deps)
pip install -e ".[dev]"

# Run all tests (pytest-asyncio with auto mode, stops on first failure via -x)
pytest

# Run a single test file
pytest tests/test_session.py -v

# Run a single test
pytest tests/test_session.py::test_launch_and_stop -v

# Run the MCP server standalone
textual-mcp

Architecture

Entry point: src/textual_mcp/server.py — FastMCP server with module-level tool registration. Tools are grouped into four categories registered via _register_* functions:

• Lifecycle (textual_launch, textual_stop) — inner-function closures over SessionManager
• Interaction (textual_press, textual_click, textual_type_text, textual_hover) — module-level async functions registered by reference
• Observation (textual_snapshot, textual_screenshot, textual_query, textual_get_screen_stack) — module-level async functions, read-only
• Assertion/Wait (textual_wait_for, textual_check_errors) — inner-function closures over SessionManager

Session lifecycle: AppSession wraps App.run_test() async context manager to get a persistent Pilot handle. The app_context() context manager sets Textual's ContextVars (active_app, active_message_pump) required for pilot operations like click and hover that need app context in the current task.

Serialization: WidgetTreeSerializer walks the DOM producing indented text with [ref=N] markers on focusable widgets. WidgetStateExtractor uses a lazily-initialized ordered isinstance registry — ordering matters because some widgets inherit from others (e.g., Label before Static, Checkbox before Static).