LCORE-1219: up to date OpenAPI specifiction after MCP patch was merged #1039
+311
−4
Conversation
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
Contributor
WalkthroughThe pull request updates API documentation to introduce a new MCP server authentication endpoint, adds tool execution result tracking to query responses with deprecation of the legacy rag_chunks structure, and introduces new supporting models (RAGChunk, ToolResultSummary) in the OpenAPI specification. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~22 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Fix all issues with AI agents
In `@docs/openapi.json`:
- Line 500: Update the OpenAPI operation summary string to use consistent "MCP"
capitalization: locate the summary field currently set to "Get Mcp Client Auth
Options" and change it to "Get MCP Client Auth Options" so it matches the rest
of the spec.
- Line 105: The description for the /info endpoint mentions returning status 500
for Llama Stack connectivity issues but the OpenAPI responses only document 503;
update the description string for the /info (InfoResponse) endpoint to refer to
status 503 (or alternatively add a 500 response entry) so the documented error
status matches the responses section—locate the description text for the /info
(or /v1/info) operation and replace "status 500" with "status 503" (or add a 500
response object if you prefer to keep 500).
In `@docs/openapi.md`:
- Around line 481-485: The markdown responses table rows are missing trailing
pipe characters which violates MD055; update the table header separator and each
row (e.g., the header line "| Status Code | Description | Component |", the
separator "|-------------|-------------|-----------|", and the response rows for
200 and 401 such as "| 200 | Successful response |
[MCPClientAuthOptionsResponse](`#mcpclientauthoptionsresponse`) |" and "| 401 |
Unauthorized | [UnauthorizedResponse](`#unauthorizedresponse`) |") to include the
closing pipe so every table line ends with a pipe.
🧹 Nitpick comments (3)
docs/openapi.json (1)
6949-7006: Consider tightening MCP auth schemas for consistency.If
serversis always present (even when empty), mark it required and disallow extra properties to match most other schemas.♻️ Suggested refactor
"MCPClientAuthOptionsResponse": { "properties": { "servers": { "items": { "$ref": "#/components/schemas/MCPServerAuthInfo" }, "type": "array", "title": "Servers", "description": "List of MCP servers that accept client-provided authorization" } }, + "required": [ + "servers" + ], + "additionalProperties": false, "type": "object", "title": "MCPClientAuthOptionsResponse", "description": "Response containing MCP servers that accept client-provided authorization.", "examples": [ { "servers": [ { "client_auth_headers": [ "Authorization" ], "name": "github" }, { "client_auth_headers": [ "Authorization", "X-API-Key" ], "name": "gitlab" } ] } ] }, "MCPServerAuthInfo": { "properties": { "name": { "type": "string", "title": "Name", "description": "MCP server name" }, "client_auth_headers": { "items": { "type": "string" }, "type": "array", "title": "Client Auth Headers", "description": "List of authentication header names for client-provided tokens" } }, + "additionalProperties": false, "type": "object", "required": [ "name", "client_auth_headers" ], "title": "MCPServerAuthInfo", "description": "Information about MCP server client authentication options." }docs/openapi.md (2)
454-466: Capitalize “MCP” consistently in the endpoint title.User-facing headings should match the acronym’s standard casing.
♻️ Suggested tweak
-> **Get Mcp Client Auth Options** +> **Get MCP Client Auth Options**
5111-5133: Link array fields to their item models for clarity.
rag_chunksandtool_resultsnow have dedicated models; referencing them here makes the schema easier to navigate.♻️ Suggested tweak
-| rag_chunks | array | Deprecated: List of RAG chunks used to generate the response. | +| rag_chunks | array | Deprecated: List of [RAGChunk](`#ragchunk`) used to generate the response. | ... -| tool_results | array | List of tool results | +| tool_results | array | List of [ToolResultSummary](`#toolresultsummary`) |
| ], | ||
| "summary": "Info Endpoint Handler", | ||
| "description": "Handle request to the /info endpoint.\n\nProcess GET requests to the /info endpoint, returning the\nservice name, version and Llama-stack version.\n\nReturns:\n InfoResponse: An object containing the service's name and version.", | ||
| "description": "Handle request to the /info endpoint.\n\nProcess GET requests to the /info endpoint, returning the\nservice name, version and Llama-stack version.\n\nRaises:\n HTTPException: with status 500 and a detail object\n containing `response` and `cause` when unable to connect to\n Llama Stack. It can also return status 401 or 403 for\n unauthorized access.\n\nReturns:\n InfoResponse: An object containing the service's name and version.", |
Contributor
There was a problem hiding this comment.
Align /v1/info error status with responses.
Line 105 mentions status 500 for Llama Stack connectivity issues, but the documented responses list 503 only. This mismatch can confuse clients.
✏️ Suggested fix
- HTTPException: with status 500 and a detail object
+ HTTPException: with status 503 and a detail object📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| "description": "Handle request to the /info endpoint.\n\nProcess GET requests to the /info endpoint, returning the\nservice name, version and Llama-stack version.\n\nRaises:\n HTTPException: with status 500 and a detail object\n containing `response` and `cause` when unable to connect to\n Llama Stack. It can also return status 401 or 403 for\n unauthorized access.\n\nReturns:\n InfoResponse: An object containing the service's name and version.", | |
| "description": "Handle request to the /info endpoint.\n\nProcess GET requests to the /info endpoint, returning the\nservice name, version and Llama-stack version.\n\nRaises:\n HTTPException: with status 503 and a detail object\n containing `response` and `cause` when unable to connect to\n Llama Stack. It can also return status 401 or 403 for\n unauthorized access.\n\nReturns:\n InfoResponse: An object containing the service's name and version.", |
🤖 Prompt for AI Agents
In `@docs/openapi.json` at line 105, The description for the /info endpoint
mentions returning status 500 for Llama Stack connectivity issues but the
OpenAPI responses only document 503; update the description string for the /info
(InfoResponse) endpoint to refer to status 503 (or alternatively add a 500
response entry) so the documented error status matches the responses
section—locate the description text for the /info (or /v1/info) operation and
replace "status 500" with "status 503" (or add a 500 response object if you
prefer to keep 500).
| "tags": [ | ||
| "mcp-auth" | ||
| ], | ||
| "summary": "Get Mcp Client Auth Options", |
Contributor
There was a problem hiding this comment.
Use consistent “MCP” capitalization in the summary.
The summary uses “Mcp” while the rest of the spec uses “MCP”.
✏️ Suggested fix
-"summary": "Get Mcp Client Auth Options",
+"summary": "Get MCP Client Auth Options",📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| "summary": "Get Mcp Client Auth Options", | |
| "summary": "Get MCP Client Auth Options", |
🤖 Prompt for AI Agents
In `@docs/openapi.json` at line 500, Update the OpenAPI operation summary string
to use consistent "MCP" capitalization: locate the summary field currently set
to "Get Mcp Client Auth Options" and change it to "Get MCP Client Auth Options"
so it matches the rest of the spec.
Comment on lines
+481
to
+485
| | Status Code | Description | Component | | ||
| |-------------|-------------|-----------| | ||
| | 200 | Successful response | [MCPClientAuthOptionsResponse](#mcpclientauthoptionsresponse) | | ||
| | 401 | Unauthorized | [UnauthorizedResponse](#unauthorizedresponse) | ||
|
|
Contributor
There was a problem hiding this comment.
Fix table pipe style to satisfy markdownlint MD055.
The responses table is missing trailing pipes, which breaks the configured table style.
✅ Example fix
-| Status Code | Description | Component |
-|-------------|-------------|-----------|
-| 200 | Successful response | [MCPClientAuthOptionsResponse](`#mcpclientauthoptionsresponse`) |
-| 401 | Unauthorized | [UnauthorizedResponse](`#unauthorizedresponse`)
+| Status Code | Description | Component |
+|-------------|-------------|-----------|
+| 200 | Successful response | [MCPClientAuthOptionsResponse](`#mcpclientauthoptionsresponse`) |
+| 401 | Unauthorized | [UnauthorizedResponse](`#unauthorizedresponse`) |📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| | Status Code | Description | Component | | |
| |-------------|-------------|-----------| | |
| | 200 | Successful response | [MCPClientAuthOptionsResponse](#mcpclientauthoptionsresponse) | | |
| | 401 | Unauthorized | [UnauthorizedResponse](#unauthorizedresponse) | |
| | Status Code | Description | Component | | |
| |-------------|-------------|-----------| | |
| | 200 | Successful response | [MCPClientAuthOptionsResponse](`#mcpclientauthoptionsresponse`) | | |
| | 401 | Unauthorized | [UnauthorizedResponse](`#unauthorizedresponse`) | |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
484-484: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
(MD055, table-pipe-style)
🤖 Prompt for AI Agents
In `@docs/openapi.md` around lines 481 - 485, The markdown responses table rows
are missing trailing pipe characters which violates MD055; update the table
header separator and each row (e.g., the header line "| Status Code |
Description | Component |", the separator
"|-------------|-------------|-----------|", and the response rows for 200 and
401 such as "| 200 | Successful response |
[MCPClientAuthOptionsResponse](`#mcpclientauthoptionsresponse`) |" and "| 401 |
Unauthorized | [UnauthorizedResponse](`#unauthorizedresponse`) |") to include the
closing pipe so every table line ends with a pipe.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
Description
LCORE-1219: up to date OpenAPI specifiction after MCP patch was merged
Type of change
Tools used to create PR
Related Tickets & Documents
Summary by CodeRabbit
Release Notes
New Features
Documentation
✏️ Tip: You can customize this high-level summary in your review settings.