feat: NICo REST MCP Support (Phase 1)

[kfelternv]

Add Model Context Protocol (MCP) server support to NICo so MCP-compatible agents can interact with the API.

Phase 1 -- read-only operations

Expose the read-only NICo REST surface as MCP tools.

[kfelternv]

QA Test Plan

Scope

Validate Phase 1 MCP support for NICo REST: a stateless, read-only MCP server that exposes REST GET operations as MCP tools, accepts REST connection details per tool call, and can optionally use startup defaults for single-target deployments.

Setup

Build the MCP server from the rest-api directory:

make nico-mcp

Start the server without REST API defaults. This verifies the server is not coupled to a specific REST API target at startup:

nico-mcp --listen :8080 --path /mcp

Tool Discovery and Read-Only Coverage

List the MCP tool catalog:

curl -sS http://localhost:8080/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | jq .

Save the tool names:

curl -sS http://localhost:8080/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | jq -r '.result.tools[].name' | sort

Compare the result against the OpenAPI spec:

• For each GET operation with an operationId, verify one MCP tool exists named nico_<snake_case(operationId)>.
• For each POST, PUT, PATCH, or DELETE operation, verify no corresponding MCP tool exists.
• Verify every returned tool name starts with nico_.
• Verify representative tools include read-only annotations where visible in the tool metadata.

Negative check for write operations:

• Pick several mutating REST operation IDs from the OpenAPI spec.
• Convert each to the expected MCP name using nico_<snake_case(operationId)>.
• Confirm those names are absent from tools/list.
• Attempt tools/call with one of those names and confirm MCP returns an unknown-tool error rather than reaching NICo REST.

Read Tool Calls

Call a representative list-style tool with all REST connection details supplied per call:

curl -sS http://localhost:8080/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "jsonrpc":"2.0",
    "id":2,
    "method":"tools/call",
    "params":{
      "name":"nico_get_all_site",
      "arguments":{
        "org":"<org>",
        "base_url":"<rest-api-base-url>",
        "api_name":"nico"
      }
    }
  }' | jq .

Expected result:

• HTTP status is 200.
• MCP response contains result.content.
• result.isError is absent or false.
• The content is the JSON payload returned by NICo REST.
• Pagination metadata, when returned by REST, is present in MCP result metadata.

Repeat with at least one get-style tool that requires a path parameter and verify the path parameter is substituted into the REST request correctly.

Configuration Precedence

Start the server with optional defaults:

nico-mcp \
  --listen :8080 \
  --path /mcp \
  --base-url <default-rest-api-base-url> \
  --org <default-org> \
  --api-name nico

Run these cases:

• Call a tool without org, base_url, or api_name arguments and verify startup defaults are used.
• Call a tool with org, base_url, and api_name arguments and verify those override startup defaults.
• Send an inbound Authorization: Bearer <token> header and verify it is forwarded to REST.
• Provide both an inbound Authorization header and a token tool argument, then verify the token argument wins for that call.
• Omit a required value such as org or base_url when no startup default provides it, then verify only that tool call returns a clear MCP error.
• After a failed call, run a valid call and verify the server remains usable.

Statelessness and Concurrency

Run concurrent tools/call requests with different combinations of org, base_url, api_name, and token values.

Expected result:

• Each REST request uses only the configuration resolved for that individual MCP call.
• Tokens do not leak between callers.
• A failure in one call does not affect later calls.
• Repeating the same calls in a different order produces the same results.

Protocol Behavior

Verify streamable HTTP behavior:

• tools/list and tools/call responses use Content-Type: application/json.
• Long-poll GET requests are rejected because the server is stateless.
• Malformed JSON-RPC requests return protocol errors.
• Invalid tool arguments fail schema validation before reaching NICo REST.
• Unknown arguments fail schema validation or are rejected clearly.

Packaging and Deployment

Build the container images:

make docker-build-local

Render the Helm chart:

helm template nico-mcp helm/rest/nico-mcp

Verify the rendered resources include:

• Deployment for nico-mcp.
• Service exposing the MCP HTTP port.
• Configurable listen/path/default connection settings.
• Expected labels, selectors, and image fields.

Deploy into a generic Kubernetes test cluster, then:

• Confirm the nico-mcp pod becomes ready.
• Port-forward or otherwise reach the MCP service.
• Run tools/list.
• Run a representative tools/call using per-call org, base_url, api_name, and token values.
• Redeploy after an image update and confirm the running workload serves the updated image.

Automated Checks

Run the focused MCP tests:

go test ./mcp/...

Run the repository’s normal REST/MCP formatting, linting, build, and test checks required for this change.

Acceptance Criteria

• nico-mcp starts successfully without REST API connection defaults.
• REST connection and authentication values can be provided per tool call.
• Optional startup defaults are used only when per-call values are absent.
• Configuration precedence is deterministic: tool arguments, then inbound auth header for token, then startup defaults.
• Only read-only REST operations are exposed as MCP tools.
• Tool calls are stateless and isolated across callers.
• Invalid requests fail clearly without breaking later requests.
• Container and Helm artifacts build, render, and deploy successfully.
• Relevant automated checks pass.

[kfelternv]

@AlexGridnev Ready for QA, see plan in comments