fix(mcp): reject mcp_server timeout_ms = 0

[moonming]

McpServer.timeout_ms accepts 0, which maps to a zero-duration per-operation deadline: every upstream op then times out instantly and the server is silently dropped from tools/list (graceful, logged, no crash).

Fix

Guard it at the schema layer with #[schemars(range(min = 1))] on the timeout_ms field — the same mechanism as the existing length(min = 1) guards on display_name/url — so validate_mcp_server enforces it on both the Admin write-path (mcp_servers_handlers) and the etcd loader (validate_and_parse). Regenerated mcp_server.schema.json (minimum 0 → 1) and added validation tests (zero rejected, positive accepted, omitted still valid).

Behavior change (called out for review): a stored mcp_server with timeout_ms = 0 is now rejected by the loader — but build_snapshot is infallible, so a rejected resource is skipped individually (bumps schema_rejected) without aborting the snapshot or taking down healthy resources, exactly as an empty display_name already is. 0 was never a usable value (instant timeout), so this rejects a previously-silently-broken config rather than a working one.

Scope note

This PR originally also carried the mcp_servers Admin OpenAPI reference (#663). That was implemented independently and merged first as #675 (a different mechanism — variant titles baked into the generated schema via title_single_value_enum_variants). This branch was rebased onto that work and now carries only the timeout_ms validation; the regenerated schema correctly combines #675's variant titles with this PR's minimum: 1.

Verification

cargo test -p aisix-core (incl. 3 new validation tests) + -p aisix-admin (19 openapi tests) green; cargo fmt --all -- --check and cargo clippy --workspace --all-targets -- -D warnings clean; dump-schema produces zero drift.

Closes #666.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds OpenAPI documentation for /admin/v1/mcp_servers CRUD routes and registers McpServer/McpServerEntry component schemas in the hand-written OpenAPI. Simultaneously tightens McpServer.timeout_ms validation by raising the minimum from 0 to 1 in both the Rust model and JSON schema, with accompanying unit tests.

Changes

MCP Server OpenAPI docs and timeout_ms validation

Layer / File(s)	Summary
timeout_ms minimum constraint crates/aisix-core/src/models/mcp_server.rs, schemas/resources/mcp_server.schema.json	Adds #[schemars(range(min = 1))] to McpServer.timeout_ms and raises the JSON schema minimum from 0.0 to 1.0.
timeout_ms schema tests crates/aisix-core/src/models/schema.rs	Three unit tests assert that timeout_ms is optional, accepts positive values, and rejects zero.
OpenAPI MCP server paths and component schemas crates/aisix-admin/src/openapi.rs	Adds path definitions for /admin/v1/mcp_servers (GET, POST) and /admin/v1/mcp_servers/{id} (GET, PUT, DELETE), inserts McpServerEntry component schema, embeds mcp_server.schema.json into RESOURCE_SCHEMAS, and adds ReDoc oneOf labels for McpAuthType and McpTransport.
OpenAPI coverage test updates crates/aisix-admin/src/openapi.rs	Updates three test assertions to require the new MCP server paths and McpServer/McpServerEntry schemas in the generated output.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• api7/aisix#664: Introduced the /admin/v1/mcp_servers CRUD handlers, store, and McpServer model that this PR documents in the OpenAPI and adds timeout_ms validation for.

🚥 Pre-merge checks | ✅ 4 | ❌ 2

❌ Failed checks (2 inconclusive)

Check name	Status	Explanation	Resolution
E2e Test Quality Review	❓ Inconclusive	Repository clone failed, so this custom check could not run with code access.	Retry the review run. If this persists, inspect pre-merge custom-check logs for infrastructure or agent runtime failures.
Security Check	❓ Inconclusive	Repository clone failed, so this custom check could not run with code access.	Retry the review run. If this persists, inspect pre-merge custom-check logs for infrastructure or agent runtime failures.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The PR matches #666 and #663 by enforcing timeout_ms >= 1, updating schema/tests, and adding the MCP server OpenAPI paths and schemas.
Out of Scope Changes check	✅ Passed	The changes stay within the linked goals and do not introduce unrelated behavior beyond validation, schema regeneration, and OpenAPI docs.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately captures the timeout_ms validation fix, which is a major part of the PR.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/mcp-servers-admin

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@crates/aisix-admin/src/openapi.rs`:
- Around line 2458-2461: Declare the new “MCP Servers” tag in the top-level
OpenAPI document tags list so the operations using that tag have a shared root
definition. Update the document root in openapi.rs where the global tags are
assembled, and ensure the tag entry for "MCP Servers" is added alongside the
existing tag definitions used by the MCP server endpoints referenced by the
MCP-related handlers.
- Around line 4049-4050: The 413-response coverage in
openapi_documents_admin_json_body_limit_rejections is missing the new MCP write
routes, so extend the existing admin JSON body limit rejection expectations to
include both POST and PUT for /admin/v1/mcp_servers and
/admin/v1/mcp_servers/{id}. Update the route coverage in the openapi.rs
test/data associated with openapi_documents_admin_json_body_limit_rejections so
these MCP write paths are asserted alongside the other admin write endpoints.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: d920c55e-770a-4efe-8aa7-fbb5ab3739c7

📥 Commits

Reviewing files that changed from the base of the PR and between c86776d and 9d58216.

📒 Files selected for processing (4)

• crates/aisix-admin/src/openapi.rs
• crates/aisix-core/src/models/mcp_server.rs
• crates/aisix-core/src/models/schema.rs
• schemas/resources/mcp_server.schema.json