Flatpak Documentation 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:

   git clone https://github.com/MVDW-Java/flatpak-doc-mcp.git
   cd flatpak-doc-mcp
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. The server includes the Flatpak documentation as a submodule. If you haven't already initialized it:

   git submodule update --init --recursive
   

Usage

Running the Server

The server can be run directly:

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:

{
  "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:

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:

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:

search_docs(query="flatpak build", max_results=5)

4. get_doc_structure

Get the structure of Flatpak documentation (table of contents).

Example:

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:

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 for the comprehensive documentation
• Model Context Protocol for the protocol specification
• The MCP community for tools and libraries

Support

For issues or questions:

1. Check the Flatpak documentation
2. Open an issue in the repository
3. Consult the MCP documentation for client integration issues