Metadata-Version: 2.5
Name: kde-docs-mcp
Version: 0.1.0
Summary: MCP server for KDE documentation (develop.kde.org)
Project-URL: Homepage, https://github.com/daydve/kde-docs-mcp
Project-URL: Documentation, https://develop.kde.org/docs/
Project-URL: Repository, https://github.com/daydve/kde-docs-mcp
Project-URL: Issues, https://github.com/daydve/kde-docs-mcp/issues
Author: daydve
License-Expression: MIT
License-File: LICENSE
Keywords: documentation,kde,kirigami,mcp,plasma,qt6
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.10
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 :: Documentation
Requires-Python: >=3.10
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: mcp>=0.9.0
Requires-Dist: requests-cache>=1.2.0
Requires-Dist: requests>=2.31.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# kde_docs_mcp

MCP server for KDE documentation (develop.kde.org). Provides access to the latest Plasma 6, Kirigami 6, Qt 6 and other KDE documentation.

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

🇷🇺 [Документация на русском](README_ru.md)

## Purpose

Allows an AI assistant to browse, search, and retrieve KDE documentation — essential when developing Plasma widgets, Kirigami apps, or working with KDE Frameworks.

## Installation

### From PyPI (future)

```bash
pip install kde-docs-mcp
```

### From source

```bash
git clone https://github.com/daydve/kde-docs-mcp.git
cd kde-docs-mcp
pip install -e .
```

### Development setup

```bash
make dev      # install with dev dependencies (ruff, pytest)
make test     # run tests
make lint     # run linter
```

## Usage

### MCP Client Configuration

Add to your MCP client configuration:

```json
{
  "mcpServers": {
    "kde_docs": {
      "command": "python3",
      "args": ["-m", "kde_docs_mcp"]
    }
  }
}
```

Or with a direct path:

```json
{
  "mcpServers": {
    "kde_docs": {
      "command": "python3",
      "args": ["/absolute/path/to/kde-docs-mcp/"]
    }
  }
}
```

### Command Line

```bash
python -m kde_docs_mcp
```

## Tools

### `list_docs`

Show the KDE documentation structure.

**Parameters:**
- `group` (optional) — group name to detail

**Examples:**
```
list_docs()                          → All groups and subsections
list_docs(group="Plasma Extensions") → Plasma widgets, themes, scripting, etc.
list_docs(group="Getting Started")   → Kirigami, Python, Rust, building guides
```

### `search_docs`

Search KDE documentation by keyword.

**Parameters:**
- `query` (required) — search term
- `deep` (default `false`) — search inside page content (slower but more thorough)
- `max_results` (default `15`) — result limit

**Examples:**
```
search_docs(query="ApplicationWindow")
search_docs(query="plasmoid", deep=true)
search_docs(query="Kirigami.Page", max_results=5)
```

### `fetch_doc`

Retrieve contents of a documentation page.

**Parameters:**
- `url` (required) — full page URL

**Examples:**
```
fetch_doc(url="https://develop.kde.org/docs/plasma/widget/")
fetch_doc(url="https://develop.kde.org/docs/plasma/widget/porting_kf6/")
```

### `validate_qml`

Check QML imports for Plasma 6 / Kirigami 6 / Qt 6 compatibility.

**Parameters:**
- `code` (required) — QML code snippet

**Examples:**
```
validate_qml(code="import QtQuick.Controls 2.5")
→ ⚠️ QtQuick.Controls 2.5 → use 3.0+ for Qt6

validate_qml(code="import QtQuick 6.0")
→ ✅ All imports compatible
```

## Caching

Requests are cached locally for 1 hour to avoid redundant network calls. Cache is stored in `.cache/` directory.

## License

MIT
