refactor(api): migrate console mcp-server responses to BaseModel (#35219)

Co-authored-by: ai-hpc <ai-hpc@users.noreply.github.com>

api/controllers/console/app/mcp_server.py

@@ -18,12 +18,6 @@ from models.enums import AppMCPServerStatus
 from models.model import AppMCPServer
 
 
-def _to_timestamp(value: datetime | int | None) -> int | None:
-    if isinstance(value, datetime):
-        return int(value.timestamp())
-    return value
-
-
 class MCPServerCreatePayload(BaseModel):
     description: str | None = Field(default=None, description="Server description")
     parameters: dict[str, Any] = Field(..., description="Server parameters configuration")
@@ -36,19 +30,25 @@ class MCPServerUpdatePayload(BaseModel):
     status: str | None = Field(default=None, description="Server status")
 
 
+def _to_timestamp(value: datetime | int | None) -> int | None:
+    if isinstance(value, datetime):
+        return int(value.timestamp())
+    return value
+
+
 class AppMCPServerResponse(ResponseModel):
     id: str
     name: str
     server_code: str
     description: str
-    status: str
+    status: AppMCPServerStatus
     parameters: dict[str, Any] | list[Any] | str
     created_at: int | None = None
     updated_at: int | None = None
 
     @field_validator("parameters", mode="before")
     @classmethod
-    def _parse_json_string(cls, value: Any) -> Any:
+    def _normalize_parameters(cls, value: Any) -> Any:
         if isinstance(value, str):
             try:
                 return json.loads(value)
@@ -70,7 +70,9 @@ class AppMCPServerController(Resource):
     @console_ns.doc("get_app_mcp_server")
     @console_ns.doc(description="Get MCP server configuration for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.response(200, "Server configuration", console_ns.models[AppMCPServerResponse.__name__])
+    @console_ns.response(
+        200, "MCP server configuration retrieved successfully", console_ns.models[AppMCPServerResponse.__name__]
+    )
     @login_required
     @account_initialization_required
     @setup_required
@@ -85,7 +87,9 @@ class AppMCPServerController(Resource):
     @console_ns.doc(description="Create MCP server configuration for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
     @console_ns.expect(console_ns.models[MCPServerCreatePayload.__name__])
-    @console_ns.response(200, "Server created", console_ns.models[AppMCPServerResponse.__name__])
+    @console_ns.response(
+        201, "MCP server configuration created successfully", console_ns.models[AppMCPServerResponse.__name__]
+    )
     @console_ns.response(403, "Insufficient permissions")
     @account_initialization_required
     @get_app_model
@@ -111,13 +115,15 @@ class AppMCPServerController(Resource):
         )
         db.session.add(server)
         db.session.commit()
-        return AppMCPServerResponse.model_validate(server, from_attributes=True).model_dump(mode="json")
+        return AppMCPServerResponse.model_validate(server, from_attributes=True).model_dump(mode="json"), 201
 
     @console_ns.doc("update_app_mcp_server")
     @console_ns.doc(description="Update MCP server configuration for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
     @console_ns.expect(console_ns.models[MCPServerUpdatePayload.__name__])
-    @console_ns.response(200, "Server updated", console_ns.models[AppMCPServerResponse.__name__])
+    @console_ns.response(
+        200, "MCP server configuration updated successfully", console_ns.models[AppMCPServerResponse.__name__]
+    )
     @console_ns.response(403, "Insufficient permissions")
     @console_ns.response(404, "Server not found")
     @get_app_model
@@ -154,7 +160,7 @@ class AppMCPServerRefreshController(Resource):
     @console_ns.doc("refresh_app_mcp_server")
     @console_ns.doc(description="Refresh MCP server configuration and regenerate server code")
     @console_ns.doc(params={"server_id": "Server ID"})
-    @console_ns.response(200, "Server refreshed", console_ns.models[AppMCPServerResponse.__name__])
+    @console_ns.response(200, "MCP server refreshed successfully", console_ns.models[AppMCPServerResponse.__name__])
     @console_ns.response(403, "Insufficient permissions")
     @console_ns.response(404, "Server not found")
     @setup_required

api/tests/unit_tests/controllers/console/app/test_mcp_server_response.py

@@ -1,6 +1,25 @@
 import datetime
+from types import SimpleNamespace
+from unittest.mock import PropertyMock, patch
 
-from controllers.console.app.mcp_server import AppMCPServerResponse
+from flask import Flask
+
+from controllers.console import console_ns
+from controllers.console.app.mcp_server import AppMCPServerController, AppMCPServerResponse
+
+
+def unwrap(func):
+    while hasattr(func, "__wrapped__"):
+        func = func.__wrapped__
+    return func
+
+
+class _ValidatedResponse:
+    def __init__(self, payload):
+        self._payload = payload
+
+    def model_dump(self, mode="json"):
+        return self._payload
 
 
 class TestAppMCPServerResponse:
@@ -40,6 +59,18 @@ class TestAppMCPServerResponse:
         resp = AppMCPServerResponse.model_validate(data)
         assert resp.parameters == {"already": "parsed"}
 
+    def test_parameters_json_array_parsed(self):
+        data = {
+            "id": "s1",
+            "name": "test",
+            "server_code": "code",
+            "description": "desc",
+            "status": "active",
+            "parameters": '["a", "b"]',
+        }
+        resp = AppMCPServerResponse.model_validate(data)
+        assert resp.parameters == ["a", "b"]
+
     def test_timestamps_normalized(self):
         dt = datetime.datetime(2024, 1, 1, 0, 0, 0, tzinfo=datetime.UTC)
         data = {
@@ -68,3 +99,40 @@ class TestAppMCPServerResponse:
         resp = AppMCPServerResponse.model_validate(data)
         assert resp.created_at is None
         assert resp.updated_at is None
+
+
+class TestAppMCPServerController:
+    def test_get_returns_empty_dict_when_server_missing(self):
+        api = AppMCPServerController()
+        method = unwrap(api.get)
+
+        with patch("controllers.console.app.mcp_server.db.session.scalar", return_value=None):
+            response = method(api, app_model=SimpleNamespace(id="app-1"))
+
+        assert response == {}
+
+    def test_post_returns_201(self):
+        api = AppMCPServerController()
+        method = unwrap(api.post)
+        payload = {"parameters": {"timeout": 30}}
+        app = Flask(__name__)
+        app.config["TESTING"] = True
+
+        with (
+            app.test_request_context("/", json=payload),
+            patch.object(type(console_ns), "payload", new_callable=PropertyMock, return_value=payload),
+            patch("controllers.console.app.mcp_server.current_account_with_tenant", return_value=(None, "tenant-1")),
+            patch("controllers.console.app.mcp_server.db.session.add"),
+            patch("controllers.console.app.mcp_server.db.session.commit"),
+            patch("controllers.console.app.mcp_server.AppMCPServer.generate_server_code", return_value="server-code"),
+            patch(
+                "controllers.console.app.mcp_server.AppMCPServerResponse.model_validate",
+                return_value=_ValidatedResponse({"id": "server-1"}),
+            ),
+        ):
+            response, status_code = method(
+                api, app_model=SimpleNamespace(id="app-1", name="Demo App", description="App description")
+            )
+
+        assert response == {"id": "server-1"}
+        assert status_code == 201