Sphinx Docs MCP Server

The Sphinx Docs MCP Server enables interaction with documentation from any repository utilizing Sphinx via an MCP standard input/output server. This innovative solution provides several capabilities, enhancing the accessibility of documentation for developers and users alike.

Key Features

• Clone and Update Repositories: Supports both public and private GitHub repositories, allowing for seamless integration and access to the latest documentation.
• Documentation Building: Automatically constructs plain-text documentation using Sphinx's capabilities.
• Document Indexing: Indexes the documentation into an SQLite Full-Text Search (FTS5) system, providing efficient search capabilities.
• OpenAI Embeddings: Optionally integrates OpenAI embeddings into the SQLite vector store to enhance search functionality.
• Advanced MCP Tools: Utilize tools for searching documents and retrieving source files with ease:
  • search_docs(query): Executes an FTS5 search or hybrid search combining FTS5 with vector rank and Reciprocal Rank Fusion (RRF).
  • read_doc_page(filepath): Accesses a complete documentation page returned from the search results.
  • read_source_code(module_path): Retrieves a source file from the designated repository.

MCP Resources

Users can access essential resources provided by the service:

• mcp://sphinx-docs
• mcp://sphinx-docs/index
• mcp://sphinx-docs/status
• mcp://sphinx-docs/config

The resource namespace can be modified through the MCP_RESOURCE_NAMESPACE setting in the .env file.

Prerequisites

To utilize this project, ensure the following prerequisites are met:

• Python version 3.11 or higher
• Git installed on your system
• Build tools as required by the specific documentation of your target repository (e.g., make, pandoc, LaTeX)
• For hybrid search mode, an OpenAI API key (OPENAI_API_KEY) is required.

Search Modes

The server supports two main search modes:

1. FTS5: This default mode employs SQLite FTS5 for searching documentation without requiring OpenAI credentials.
2. Hybrid: This mode utilizes OpenAI embeddings for enhanced search capabilities. It integrates FTS, vector ranking, and RRF while requiring an OpenAI API key and configurations for embedding dimensions and metric settings.

Flexible Configuration Options

Users can easily configure the server by adjusting the values in the .env file:

• Set REPO_URL for the repository clone URL.
• Specify REPO_INSTALL_COMMAND and DOCS_BUILD_COMMAND to manage dependencies and documentation builds respectively.
• Configure optional settings for enhanced control over the search and build processes.

Practical Docker Workflow

This project also supports a Docker workflow for those preferring containerized environments:

cp .env.example .env  
# Edit .env as needed  
docker compose build  
docker compose run --rm --no-deps -T sphinx-mcp

IDE MCP Configuration

Specific configurations for various IDEs are provided to facilitate smooth development environments, whether using Docker or local Python setups.

Troubleshooting

For any issues, detailed troubleshooting steps are provided to ensure successful setup and operation, addressing common errors that users may encounter.