Metadata-Version: 2.4
Name: textual-docs-mcp
Version: 0.1.2
Summary: MCP server providing AI agents with Textual TUI library documentation, examples, and best practices
License: MIT
License-File: LICENSE
Keywords: ai,documentation,mcp,textual,tui
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: mcp>=1.9.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-frontmatter>=1.1.0
Requires-Dist: rank-bm25>=0.2.2
Provides-Extra: dev
Requires-Dist: black>=24.0.0; extra == 'dev'
Requires-Dist: mypy>=1.14.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.25.0; extra == 'dev'
Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.9.0; extra == 'dev'
Requires-Dist: vulture>=2.14; extra == 'dev'
Description-Content-Type: text/markdown

# textual-docs-mcp

[![PyPI Version](https://img.shields.io/pypi/v/textual-docs-mcp?color=blue)](https://pypi.org/project/textual-docs-mcp/)
[![Python Version](https://img.shields.io/pypi/pyversions/textual-docs-mcp)](https://pypi.org/project/textual-docs-mcp/)

An MCP server for [Textual](https://textual.textualize.io/) TUI framework documentation, code examples, widget references, and best practices.

## What You Get

This MCP server has:

- **Full-text BM25 search** across all Textual documentation, guides, and examples
- **Widget documentation** — complete reference for every built-in widget
- **Guide retrieval** — layout, events, reactivity, CSS, workers, screens, and more
- **Code examples** — real, runnable Python examples covering common Textual patterns
- **Topic catalogues** — browse all available guides and widgets

All documentation is bundled inside the package — no external API calls, no network requests, no rate limits.

## Installation

### pip (recommended)

```bash
pip install textual-docs-mcp
```

### From Source

```bash
git clone https://github.com/diaz3618/textual-docs-mcp.git
cd textual-docs-mcp
pip install -e ".[dev]"
```

### Docker

```bash
docker pull ghcr.io/diaz3618/textual-docs-mcp:latest
```

Or build locally:

```bash
docker build -t textual-docs-mcp .
```

## Usage

### Stdio Transport (MCP Clients)

```bash
textual-docs-mcp
# or
python -m textual_docs_mcp
```

### Docker

```bash
docker run -i textual-docs-mcp
```

### MCP Client Configuration

<details>
<summary><b>Claude Desktop</b></summary>

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "textual-docs": {
      "command": "uvx",
      "args": ["textual-docs-mcp"]
    }
  }
}
```

</details>

<details>
<summary><b>Claude Code</b></summary>

```bash
claude mcp add --scope user textual-docs -- uvx textual-docs-mcp
```

</details>

<details>
<summary><b>VS Code (GitHub Copilot)</b></summary>

Add to `.vscode/mcp.json`:

```json
{
  "servers": {
    "textual-docs": {
      "type": "stdio",
      "command": "uvx",
      "args": ["textual-docs-mcp"]
    }
  }
}
```

</details>

<details>
<summary><b>Cursor</b></summary>

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "textual-docs": {
      "command": "uvx",
      "args": ["textual-docs-mcp"]
    }
  }
}
```

</details>

<details>
<summary><b>Docker</b></summary>

```json
{
  "mcpServers": {
    "textual-docs": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/diaz3618/textual-docs-mcp:latest"]
    }
  }
}
```

</details>

**[More client configurations →](docs/installation.mdx)**

## Available Tools

| Tool | Description |
|------|-------------|
| `search_textual_docs_tool` | BM25 full-text search across all docs, guides, and examples |
| `get_guide_tool` | Fetch a specific Textual guide (layout, events, reactivity, ...) |
| `get_widget_docs_tool` | Fetch complete docs for a specific widget |
| `get_code_examples_tool` | Fetch runnable code examples for a topic |
| `list_guides_tool` | Catalogue of all available guides and how-to articles |
| `list_widgets_tool` | Catalogue of all available widget documentation |
| `get_textual_overview_tool` | High-level introduction to the Textual framework |

## Development

```bash
# Install with dev dependencies
make dev

# Run tests
make test

# Run all checks (lint, typecheck, deadcode)
make check

# Build Docker image
make docker-build

# Rebuild documentation bundle (requires Textual source)
TEXTUAL_REPO_PATH=/path/to/textual make bundle
```

See `make help` for all available targets.

## More Documentation

- **[Installation & Clients](docs/installation.mdx)** — Setup for multiple MCP clients
- **[Available Tools](docs/tools.mdx)** — Detailed tool reference
- **[Skills & Agents](docs/skills.mdx)** — Enhance your AI assistant
- **[Architecture](docs/resources/architecture.mdx)** — Module design, data flow, bundle format

## Plugins

Pre-configured plugins for popular AI coding assistants:

- **[Claude Code](plugins/claude/textual-docs-mcp/)** — MCP config, skills, agents
- **[Cursor](plugins/cursor/textual-docs-mcp/)** — MCP config, rules, skills

## License

[MIT](LICENSE)
