Build a small MCP server with validated tools

Implement handleMcpRequest for the ci-insights server so every fixture request gets the response the request contract defines, and predict the response channel for each fixture row before you run it. Then review the three proposals in the trust scenario: for each, name the risk, your decision, and the controls you would require. Finish with what a client built for the 2025-11-25 revision would see from this server.

Suppose the platform team at a fictional freight-booking company builds ci-insights, a small MCP server that lets engineers' coding assistants read CI results. Each developer's assistant launches it over stdio with a read-only CI token taken from the environment. The server exposes two read-only tools and implements only the 2026-07-28 revision. An assistant whose MCP client was built for the 2025-11-25 revision or earlier instead opens with an initialize request carrying protocolVersion, capabilities, and clientInfo in its params, and sends none of the per-request _meta fields.

Server configuration (JavaScript names):

{
  "supportedVersions": ["2026-07-28"],
  "cacheTtlMs": 300000,
  "cacheScope": "public"
}

cacheTtlMs is 300,000 milliseconds, or 5 minutes. The scope is public because every caller gets the same list.

Tool definitions (server.tools), in declared order:

[
  {
    "name": "get_build_status",
    "description": "Get the result and duration of one CI build. Read-only.",
    "inputSchema": {
      "type": "object",
      "properties": {
        "pipeline": { "type": "string", "enum": ["web", "api", "mobile"] },
        "build": { "type": "integer", "minimum": 1 }
      },
      "required": ["pipeline", "build"],
      "additionalProperties": false
    },
    "annotations": { "readOnlyHint": true, "openWorldHint": false }
  },
  {
    "name": "list_flaky_tests",
    "description": "List the flakiest tests of a CI pipeline, most failures first. Read-only.",
    "inputSchema": {
      "type": "object",
      "properties": {
        "pipeline": { "type": "string", "enum": ["web", "api", "mobile"] },
        "limit": { "type": "integer", "minimum": 1, "maximum": 20, "default": 3 }
      },
      "required": ["pipeline"],
      "additionalProperties": false
    },
    "annotations": { "readOnlyHint": true, "openWorldHint": false }
  }
]

Builds (server.builds, stored order):

Flaky tests (server.flakyTests, stored order, most failures first):

Python uses handle_mcp_request and snake_case server keys (supported_versions, cache_ttl_ms, cache_scope, flaky_tests); the practice problem has the full mapping.

handleMcpRequest(message, server) (Python handle_mcp_request) receives one already-parsed JSON value and returns one response object, or null (Python None) when nothing may be sent. Apply the checks in order; the first failure decides the response.

Validation reads only additionalProperties: false, required, and, per property, type (string or integer), enum, minimum, and maximum; other keywords, such as default, are ignored. Report only the first failure, in this order:

1. With additionalProperties: false, each argument key, in the order the arguments list them, that properties does not declare: Unexpected argument: <key>. Without it, extra keys are allowed (the JSON Schema default).
2. Each name in required, in order, that is missing: Missing required argument: <name>.
3. Each declared property, in properties order, that is present: type (Argument <name> must be a string or Argument <name> must be an integer), then enum (Argument <name> must be one of: <values joined by ", ">), then minimum (Argument <name> must be at least <minimum>), then maximum (Argument <name> must be at most <maximum>).

An integer, for arguments and ids alike, is a number with no fractional part, as in JSON Schema 2020-12: booleans and numeric strings are not integers.

Tool results:

• A tool result is { resultType: "complete", content: [{ type: "text", text }], structuredContent, isError }. Failures carry no structuredContent.
• get_build_status: find the build with the same pipeline and build. None: No build <build> found for pipeline <pipeline>. Found: structuredContent is a new object { pipeline, build, status, minutes }.
• list_flaky_tests: the pipeline's flaky tests in stored order, at most limit (3 when absent). structuredContent is { pipeline, tests: [{ test, failures }, ...] }.
• On success, text is the compact JSON of structuredContent, with no spaces and keys in the order shown.

The server/discover and tools/list result shapes, the response envelope, and the language-specific details are listed with the implementation exercise and in the practice problem.