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

Related MCP server: openai-agents-sdk-mcp

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