feat: add OpenRAG MCP STDIO v0#729
Merged
Merged
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR introduces a new MCP (Model Context Protocol) server for OpenRAG that enables AI assistants like Claude Desktop and Cursor to interact with OpenRAG through chat, search, and document management tools. The implementation includes a modular tool registration system, comprehensive error handling, and configuration management via environment variables.
Key Changes:
- New
openrag-mcpPython package with MCP server implementation - Tool system for chat, search, and document management operations
- Configuration management with OpenRAG SDK integration
Reviewed changes
Copilot reviewed 12 out of 14 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| sdks/mcp/pyproject.toml | Package metadata and dependencies for the MCP server |
| sdks/mcp/README.md | Comprehensive documentation with setup instructions and usage examples |
| sdks/mcp/src/openrag_mcp/server.py | Main MCP server implementation with tool registration and dispatch |
| sdks/mcp/src/openrag_mcp/config.py | Configuration management and SDK client initialization |
| sdks/mcp/src/openrag_mcp/tools/registry.py | Tool registration and handler dispatch system |
| sdks/mcp/src/openrag_mcp/tools/chat.py | Chat tool with RAG-enhanced responses |
| sdks/mcp/src/openrag_mcp/tools/search.py | Semantic search tool with filtering support |
| sdks/mcp/src/openrag_mcp/tools/documents.py | Document ingestion and management tools |
| sdks/mcp/src/openrag_mcp/tools/init.py | Tool module initialization and registry exports |
| sdks/mcp/src/openrag_mcp/init.py | Package entry point |
| sdks/mcp/src/openrag_mcp/main.py | Module execution entry point |
| sdks/mcp/uv.lock | Dependency lock file for reproducible builds |
| pyproject.toml | Root project dependencies updated to include openrag-sdk |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Introduces mcp.md and sequence.md to document OpenRAG MCP usage, configuration, features, and protocol flows. These files provide setup instructions, integration examples, and detailed sequence diagrams for all supported MCP tools and error handling.
Introduce settings and models management to the MCP and backend API. - Add openrag_mcp tools: new settings tool (openrag_get_settings, openrag_update_settings, openrag_list_models) that uses direct HTTP to any OpenRAG backend and register it in tools.__init__. - Add public API endpoint /v1/models to list language/embedding models per provider (src/api/v1/models.py) and wire the route into main.py using the models_service. - Extend SDK: add ModelsClient to openrag_sdk.client and add ModelsResponse/ModelOption types; extend Settings/Knowledge models with system_prompt, table_structure, ocr, picture_descriptions. - Update MCP package version and lockfile (pyproject.toml and uv.lock) and adjust dependency markers/whl entries. - Improve sdks/mcp/README.md with instructions for running the MCP from source (build/run and Cursor config). These changes enable listing and updating provider/model settings from the MCP tools and expose a models listing API for the SDK and tooling.
Add .github/workflows/publish-mcp.yml to automate publishing the openrag-mcp SDK. The workflow triggers on tags matching mcp-v*, checks out the repo, runs in sdks/mcp with Python 3.12, installs build and twine, extracts the package version from the tag and updates pyproject.toml, builds the package, and uploads artifacts to PyPI using the PYPI_TOKEN secret.
feat: Add MCP settings/models tools and models API
Remove runtime registrations for document-related tools in sdks/mcp/src/openrag_mcp/tools/documents.py and replace them with a TODO. The register_tool calls for INGEST_FILE_TOOL, INGEST_URL_TOOL, GET_TASK_STATUS_TOOL, WAIT_FOR_TASK_TOOL, and DELETE_DOCUMENT_TOOL were commented out/removed to defer reintroducing these Document tools until OpenRAGMCP v2 with tests.
Rewrite and reorganize sdks/mcp README to clarify what the MCP server is and how to run it. Adds a short explanation of Model Context Protocol, updated Quick Start (use uvx openrag-mcp), environment variable guidance, and pinned-version example (uvx --from ...). Replaces and expands the tools list with available endpoints and notes that document management tools are implemented but not yet registered. Improves run-from-source instructions, Cursor and Claude Desktop configuration examples, troubleshooting, and use-case/benefits sections for developers.
Update project metadata: set openrag-mcp version to 0.1.0 and simplify its description, and bump openrag-sdk version to 0.1.3. Updated lock files to reflect the version changes.
edwinjosechittilappilly
changed the title
Collaborator
Author
|
Co-authored-by: Copilot <[email protected]>
2 tasks
lucaseduoli
approved these changes
Feb 13, 2026
lucaseduoli
left a comment
lucaseduoli
left a comment
Collaborator
There was a problem hiding this comment.
LGTM, would like Seb's review
phact
reviewed
Feb 13, 2026
Delete openrag-sdk from the dependencies in pyproject.toml and regenerate the lockfile (uv.lock) to reflect the updated dependency graph.
Document new OPENRAG_MCP_* environment variables and wire them into the MCP HTTP client. Added parsing helpers for float/int/bool, new Config properties (mcp_timeout, mcp_max_connections, mcp_max_keepalive_connections, mcp_max_retries, mcp_follow_redirects) with sensible defaults, and updated get_client() to use these values for httpx AsyncClient (timeout, connection limits, transport retries, follow_redirects). This enables runtime tuning of the MCP client's behavior via environment variables.
Replace the TODO comment about re-adding Document tools with a note that ingest tools are currently disabled in OpenRAGMCP. This clarifies the current state in the codebase without making functional changes.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request introduces the initial implementation of the OpenRAG MCP server package (
openrag-mcp), which exposes OpenRAG's Retrieval-Augmented Generation (RAG) capabilities via the Model Context Protocol (MCP). This enables seamless integration of OpenRAG with MCP-compatible AI assistants (e.g., Cursor, Claude Desktop) through a standardized interface. The PR includes the server code, tool registration, configuration management, documentation, packaging, and a GitHub Actions workflow for publishing to PyPI.The most important changes are:
OpenRAG MCP Server Implementation:
server.py, which sets up the MCP server, registers tools, and handles incoming requests via stdio. It uses the OpenRAG SDK to communicate with the OpenRAG backend.config.pyto load environment variables (e.g.,OPENRAG_API_KEY,OPENRAG_URL) and provide singleton access to the OpenRAG client and HTTP client.__init__.pyand__main__.pyfor running the server as a script or module. [1] [2]Tool Registration and Chat Tool:
tools/__init__.pyand implemented theopenrag_chattool intools/chat.py, allowing users to send chat messages to OpenRAG and receive RAG-enhanced responses, including source attribution and error handling. [1] [2]Packaging and Distribution:
pyproject.tomlfor the MCP server package, specifying dependencies (mcp,httpx,openrag-sdk), project metadata, and entry points for CLI execution.publish-mcp.yml) for automated publishing of the MCP package to PyPI when tags matchingmcp-v*are pushed.Documentation:
README.mdwith usage instructions, environment variable requirements, integration guides for Cursor and Claude Desktop, troubleshooting, and development workflow details.Dependency Updates:
openrag-sdkto the dependencies in the rootpyproject.tomlto ensure the SDK is available for the MCP server.