fix(api): align users MCP tool description

[pozylon]

Summary

• Replaces and supersedes Mcp optimization #720 after reconciling it with the SDK-v2 MCP architecture now on master.
• Corrects the users_management MCP description so every advertised action exists in its schema.
• Adds an integration regression check that derives supported actions from the published schema and rejects the stale SET_ROLES, SET_PASSWORD, and GET_CART claims.
• Intentionally adds no MCP client/session/resource cache: the benchmarked saving did not meet the agreed materiality gate.

Benchmark decision

The uncommitted benchmark exercised the real authenticated, stateless MCP endpoint and both production chat adapters with a mock model. It ran on base commit 841b058a5b8aa28022ee434d284308279f097dc1, Node v25.9.0, npm 11.12.1, Apple M4 (10 logical CPUs, 32 GiB), with AI SDK 7.0.83, @ai-sdk/mcp 2.0.39, MCP server 2.0.0, Express 5.2.1, and Fastify 5.12.1.

Method: three rounds per workload, 25 warm-ups and 200 measured operations per round, plus concurrency-10 runs. The prototype cached only static ListToolsResult metadata and still created and closed a newly authenticated client for every request.

Sequential measurement	p50 (ms)	p95 (ms)	p99 (ms)
Current MCP setup	4.872	6.901	11.156
Metadata-only prototype	1.592	2.806	3.694
Express /chat/tools	5.228	9.124	11.606
Fastify /chat/tools	5.520	8.380	10.440
Express request to model start	5.438	8.194	10.740
Fastify request to model start	5.070	7.224	10.395

Concurrency-10 measurement	p50 (ms)	p95 (ms)	p99 (ms)
Express /chat/tools	48.881	80.956	93.285
Fastify /chat/tools	45.336	53.209	56.190
Express chat response	52.933	62.811	76.726
Fastify chat response	51.284	72.899	84.282

First measured setup calls across the three rounds were 35.376/6.364/5.174 ms for current behavior and 6.146/4.596/6.124 ms for the cold prototype. There were zero benchmark errors and zero net active handles.

Gate result: fail. The prototype saved 4.095 ms at p95 (59.339%), below the required absolute saving of 20 ms. Keeping request-scoped clients and fresh resource context is therefore preferable to adding shared cache state.

Validation

• npm exec eslint -- packages/api/src/mcp/tools/users/index.ts tests/mcp.test.js
• npm run build --workspace @unchainedshop/api
• npm test --workspace @unchainedshop/api — 95 passed
• focused tests/mcp.test.js integration run — 11 passed