Add MCP server endpoint for AI agent doc access - #2727
Open
joebutler2 wants to merge 9 commits into
Open
Conversation
Adds POST /mcp implementing the Model Context Protocol (JSON-RPC 2.0, non-streaming HTTP) so AI coding agents can query a self-hosted DevDocs instance directly instead of scraping the browser UI. Three tools, all reading from the same public/docs tree the server already uses to serve doc content: - devdocs_list_docsets — the configured doc sets (from settings.docs) - devdocs_search — entries in one doc set matching a query (index.json) - devdocs_get_page — one entry's content as plain text, HTML stripped with Nokogiri (already a dependency) (db.json) Relates to freeCodeCamp#2420.
joebutler2
marked this pull request as ready for review
September 7, 2026 22:34
mo74m3ed
reviewed
Sep 7, 2026
joebutler2
force-pushed
the
feature/mcp-server
branch
from
September 9, 2026 14:48
6312f7c to
ebe24b6
Compare
- Add pagination support (offset/limit) to reduce response size - Return condensed format (slug, name, version only) instead of full metadata - Add query parameter for filtering by slug or name (case-insensitive) - Include pagination metadata (offset, limit, total, returned) in responses - Add comprehensive unit tests for all new features (7 new test cases) All 11 MCP tests passing with 45 assertions. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
joebutler2
force-pushed
the
feature/mcp-server
branch
from
September 9, 2026 14:50
ebe24b6 to
37090e8
Compare
There was a problem hiding this comment.
🟡 Changes recommended
Protocol interoperability, production storage, input security, and error-handling issues must be resolved.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
Adds an MCP endpoint so coding agents can query current DevDocs content, addressing #2420.
Changes:
- Adds JSON-RPC initialization and tool discovery.
- Adds docset listing, search, and page retrieval tools.
- Adds MCP tests, fixtures, and local configuration exclusion.
File summaries
| File | Description |
|---|---|
.gitignore |
Excludes local MCP configuration. |
lib/app.rb |
Exposes the /mcp endpoint. |
lib/mcp/server.rb |
Implements MCP request handling and tools. |
test/mcp_test.rb |
Tests MCP operations. |
test/files/docs/mcp_fixture/index.json |
Provides search fixtures. |
test/files/docs/mcp_fixture/db.json |
Provides page-content fixtures. |
Review details
Suppressed comments (2)
lib/mcp/server.rb:126
- The hosted deployment provisions only
meta.jsonlocally (lib/tasks/docs.thor:263-266), notindex.json, so every hosteddevdocs_searchcall raisesENOENT. Use the configured documentation origin/storage backend or provision indexes during deployment.
index_path = File.join(app_settings.docs_path, slug, 'index.json')
index = JSON.parse(File.read(index_path))
lib/mcp/server.rb:126
- The public request's
slugcan contain.., allowing this join to escapedocs_pathand inspect an unrelatedindex.json. Validate the slug againstapp_settings.docsand enforce containment within the expanded documentation root.
def self.search_docset(app_settings, slug, query)
index_path = File.join(app_settings.docs_path, slug, 'index.json')
index = JSON.parse(File.read(index_path))
- Files reviewed: 5/6 changed files
- Comments generated: 9
- Review effort level: Balanced
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| case request['method'] | ||
| when 'initialize' | ||
| respond(request, { | ||
| 'protocolVersion' => '2024-11-05', |
Comment on lines
+118
to
+119
| db_path = File.join(app_settings.docs_path, slug, 'db.json') | ||
| db = JSON.parse(File.read(db_path)) |
Comment on lines
+117
to
+119
| def self.get_page(app_settings, slug, path) | ||
| db_path = File.join(app_settings.docs_path, slug, 'db.json') | ||
| db = JSON.parse(File.read(db_path)) |
Comment on lines
+283
to
+284
| payload = JSON.parse(request.body.read) | ||
| Mcp::Server.handle(payload, settings).to_json |
Comment on lines
+69
to
+71
| def self.call_tool(request, app_settings) | ||
| params = request['params'] | ||
| case params['name'] |
Comment on lines
+71
to
+81
| case params['name'] | ||
| when 'devdocs_list_docsets' | ||
| result = list_docsets(app_settings, params['arguments'] || {}) | ||
| as_text_result(request, result) | ||
| when 'devdocs_search' | ||
| entries = search_docset(app_settings, params['arguments']['slug'], params['arguments']['query']) | ||
| as_text_result(request, entries) | ||
| when 'devdocs_get_page' | ||
| text = get_page(app_settings, params['arguments']['slug'], params['arguments']['path']) | ||
| respond(request, { 'content' => [{ 'type' => 'text', 'text' => text }] }) | ||
| end |
Comment on lines
+119
to
+120
| db = JSON.parse(File.read(db_path)) | ||
| html = db[path] |
Comment on lines
+120
to
+121
| html = db[path] | ||
| Nokogiri::HTML::DocumentFragment.parse(html).text.squeeze(' ').strip |
Comment on lines
+127
to
+130
| query_lower = query.downcase | ||
| index['entries'].select do |entry| | ||
| entry['name'].downcase.include?(query_lower) || entry['path'].downcase.include?(query_lower) | ||
| end |
- Validate docset slugs against configured docs to prevent path traversal attacks - Handle missing index.json and db.json files gracefully in production - Return descriptive JSON-RPC errors when files are unavailable - Add tests for path traversal protection and missing file handling - Add mcp_fixture to test docs manifest for proper test coverage This addresses GitHub review concerns about: 1. Security: Path traversal vulnerability (slug with ..) 2. Production: Missing index.json and db.json in hosted deployments Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
- Add error boundary in /mcp endpoint to catch JSON parse errors (-32700) - Return JSON-RPC error instead of HTML 500 for parse failures - Handle unknown tool names with -32602 error instead of returning nil - Add generic error handler in Mcp::Server.handle for unexpected exceptions - Fixes issues where malformed requests would return HTML error pages Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
- Validate all arguments against tool inputSchema before dispatch - Check required fields are present - Validate field types (string, integer, number) - Enforce min/max constraints on numeric values - Return -32602 (invalid request) for validation failures - Add comprehensive tests for missing/invalid arguments and type mismatches Fixes comment about params being dereferenced without validation. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
- Replace simple Node#text concatenation with proper block element handling - Add line breaks before/after block elements (p, div, h1-h6, ul, ol, li, blockquote, pre, br) - Preserve meaningful whitespace while removing excess blank lines - Prevents adjacent block elements from concatenating without separation Fixes issue where <h1>Title</h1><p>Body</p> would become TitleBody. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
- Add offset and limit parameters to search (same as list_docsets) - Validate that query is non-empty to prevent matching everything - Return paginated results with metadata (offset, limit, total, returned) - Prevents large result sets from exceeding agent context limits - Add tests for pagination and empty query validation Fixes issue where large docsets could generate oversized responses. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
- Add DB_CACHE to cache parsed db.json files in memory - Load database once per docset and reuse across requests - Prevents reparsing multi-megabyte files on every page lookup - Reduces memory allocations and CPU overhead on concurrent calls - Cache key includes docs_path to handle test/production separation Fixes performance issue with repeated full-database parsing. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
- Verify malformed JSON returns -32700 parse error - Ensure /mcp endpoint returns JSON-RPC error instead of HTML 500 Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
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.
In keeping competitive with other API Doc services (like Dash), let's add MCP support so agents can interact with our Docs as well.
This adds
POST /mcpimplementing the Model Context Protocol (JSON-RPC 2.0, non-streaming HTTP) so AI coding agents can query a self-hosted DevDocs instance directly instead of scraping the browser UI.Three tools, all reading from the same public/docs tree the server already uses to serve doc content:
Relates to #2420.