test(mcp): add expert-mcp token helper and raw/normalize equivalence options

Author: andypalmi

test/lib/mcpToolEquivalence.js

@@ -1,9 +1,31 @@
 const should = require('should')
 
+// Mints the token the first-party Expert uses in production (see
+// forge/ee/lib/expert/index.js getOrCreateMcpPlatformToken): a nameless
+// user:expert-mcp token scoped to ff-expert:platform. Being nameless,
+// request.session.scope survives (a named token would have its scope deleted
+// - the #7446 temp hack), so every route the tool reaches is checked against
+// IMPLICIT_TOKEN_SCOPES['user:expert-mcp']. That is the exact path the Expert
+// takes, so an equivalence test using this token also proves the tool's
+// backing scope is in the allow-list. Test-only helper.
+const EXPERT_MCP_PLATFORM_SCOPE = 'ff-expert:platform'
+const EXPERT_MCP_PLATFORM_OWNER_TYPE = 'user:expert-mcp'
+
+async function createExpertMcpToken (app, user = app.user) {
+    const { token } = await app.db.controllers.AccessToken.createTokenForUser(
+        user,
+        null,
+        [EXPERT_MCP_PLATFORM_SCOPE],
+        undefined,
+        EXPERT_MCP_PLATFORM_OWNER_TYPE
+    )
+    return token
+}
+
 // Asserts that an MCP tool produces the same result as calling its backing
 // route directly. The tool handler builds its own {method, url} from the args;
 // the test independently states the route it is expected to hit. Both are made
-// with the same PAT-bearing inject, so:
+// with the same expert-mcp-token-bearing inject, so:
 //   - a wrong url/method/path-param in the tool hits a different route and the
 //     status/body diverge -> the test fails (this is what proves correctness),
 //   - the endpoint's response shape is never written down here, it is whatever
@@ -19,15 +41,31 @@ const should = require('should')
 // returns the { statusCode, body } the tool is expected to produce from that
 // same live route response - still drift-proof, since it references the live
 // response rather than a hard-coded shape.
-async function expectToolMatchesRoute (inject, tool, args, { method, url, payload, transform } = {}) {
+//
+// Some routes (e.g. CSV exports) don't return JSON, so `.json()` would throw.
+// Pass `raw: true` to compare the response bodies as plain strings instead.
+//
+// Some routes proxy live/randomised data (e.g. a point-in-time resource usage
+// snapshot) that is regenerated on every call, so two independent calls never
+// produce byte-identical bodies. Pass `normalize(body) => body` to reduce both
+// the tool's and the route's body to the parts that should be stable (shape,
+// counts, keys) before comparing - still derived from the live response on
+// both sides, just tolerant of fields that are expected to vary per call.
+async function expectToolMatchesRoute (inject, tool, args, { method, url, payload, transform, raw, normalize } = {}) {
     const viaTool = await tool.handler(args, { inject })
     const routeResponse = await inject({ method, url, payload })
     const expected = transform
         ? transform(routeResponse)
-        : { statusCode: routeResponse.statusCode, body: routeResponse.json() }
+        : { statusCode: routeResponse.statusCode, body: raw ? routeResponse.body : routeResponse.json() }
     viaTool.statusCode.should.equal(expected.statusCode)
-    should(viaTool.json()).eql(expected.body)
+    let actualBody = raw ? viaTool.body : viaTool.json()
+    let expectedBody = expected.body
+    if (normalize) {
+        actualBody = normalize(actualBody)
+        expectedBody = normalize(expectedBody)
+    }
+    should(actualBody).eql(expectedBody)
     return { viaTool, routeResponse }
 }
 
-module.exports = { expectToolMatchesRoute }
+module.exports = { expectToolMatchesRoute, createExpertMcpToken }