# Flatpak Documentation MCP Server

An MCP (Model Context Protocol) server that provides access to Flatpak documentation files (.rst and .html) through a standardized interface.

## Features

- **List Documentation**: Browse all available Flatpak documentation files
- **Get Documentation**: Read the content of specific documentation files
- **Search Documentation**: Search across all documentation files for specific terms
- **Documentation Structure**: Get the table of contents and structure of the documentation
- **Prompts**: Pre-defined prompts for common documentation queries

## Installation

1. Clone this repository:
   ```bash
   git clone https://github.com/MVDW-Java/flatpak-doc-mcp.git
   cd flatpak-doc-mcp
   ```

2. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```

3. The server includes the Flatpak documentation as a submodule. If you haven't already initialized it:
   ```bash
   git submodule update --init --recursive
   ```

## Usage

### Running the Server

The server can be run directly:

```bash
python app.py
```

### Integration with MCP Clients

To use this server with an MCP client (like Claude Desktop), add it to your client configuration:

**Example configuration for Claude Desktop:**

```json
{
  "mcpServers": {
    "flatpak-docs": {
      "command": "python",
      "args": ["/path/to/flatpak-doc-mcp/app.py"],
      "env": {
        "PYTHONPATH": "/path/to/flatpak-doc-mcp"
      }
    }
  }
}
```

## Available Tools

### 1. `list_docs`
List all available Flatpak documentation files.

**Parameters:**
- `filter` (optional): Filter to search for specific documentation (e.g., 'builder', 'command')

**Example:**
```javascript
list_docs(filter="builder")
```

### 2. `get_doc`
Get the content of a specific Flatpak documentation file.

**Parameters:**
- `filename` (required): Name of the documentation file (e.g., 'building.rst', 'flatpak-docs.html')
- `search_term` (optional): Search term to find within the document

**Example:**
```javascript
get_doc(filename="building.rst", search_term="sandbox")
```

### 3. `search_docs`
Search across all Flatpak documentation files.

**Parameters:**
- `query` (required): Search query to find in documentation content
- `max_results` (optional): Maximum number of results to return (default: 10)

**Example:**
```javascript
search_docs(query="flatpak build", max_results=5)
```

### 4. `get_doc_structure`
Get the structure of Flatpak documentation (table of contents).

**Example:**
```javascript
get_doc_structure()
```

## Available Prompts

### 1. `flatpak_overview`
Get an overview of Flatpak documentation.

### 2. `flatpak_topic`
Get documentation about a specific Flatpak topic.

**Parameters:**
- `topic` (required): Topic to get documentation about (e.g., 'building', 'sandbox', 'commands')

## Documentation Structure

The Flatpak documentation includes:

### Core Documentation (.rst files):
- `index.rst` - Main documentation index
- `introduction.rst` - Introduction to Flatpak
- `basic-concepts.rst` - Basic concepts and terminology
- `getting-started.rst` - Getting started guide
- `building.rst` - Building applications
- `flatpak-builder.rst` - Using flatpak-builder
- `publishing.rst` - Publishing applications
- `sandbox-permissions.rst` - Sandbox permissions
- `portals.rst` - Portals for sandboxed applications
- `debugging.rst` - Debugging applications

### Reference Documentation (.html files):
- `flatpak-docs.html` - Flatpak command reference
- `flatpak-builder-docs.html` - flatpak-builder command reference
- `libflatpak-docs.html` - libflatpak API reference

### Additional Topics:
- Desktop integration
- Dependencies and modules
- Hosting repositories
- Tips and tricks
- Under the hood details

## Development

### Project Structure
```
flatpak-doc-mcp/
├── app.py              # Main MCP server implementation
├── requirements.txt    # Python dependencies
├── README.md          # This file
└── flatpak-docs/      # Flatpak documentation submodule
    └── docs/          # Documentation files
        ├── *.rst      # ReStructuredText documentation
        ├── *.html     # HTML documentation
        └── ...
```

### Adding New Features

1. **New Tools**: Add new tool handlers in the `FlatpakDocServer.setup_handlers()` method
2. **New Prompts**: Add new prompt handlers in the same method
3. **Configuration**: Modify `DOCS_ROOT` and `SUPPORTED_EXTENSIONS` constants as needed

### Testing

Run the server and test with an MCP client or use the Python REPL:

```python
import asyncio
from app import FlatpakDocServer

async def test():
    server = FlatpakDocServer()
    # Test your handlers here

asyncio.run(test())
```

## License

This MCP server is provided under the same license as the Flatpak documentation it serves.

## Acknowledgments

- [Flatpak](https://flatpak.org/) for the comprehensive documentation
- [Model Context Protocol](https://modelcontextprotocol.io/) for the protocol specification
- The MCP community for tools and libraries

## Support

For issues or questions:
1. Check the [Flatpak documentation](https://docs.flatpak.org/)
2. Open an issue in the repository
3. Consult the MCP documentation for client integration issues