@reproapp/mcp 0.0.8 → 0.0.10

package/README.md

@@ -1,12 +1,12 @@
-# @reproapp/mcp
+# Repro MCP Server
 
-Repro MCP server for AI-assisted debugging and privacy policy workflows.
+Add Repro tools to an AI agent that supports MCP. Once connected, the agent can
+inspect Repro sessions, requests, traces, database changes, and privacy policies
+without you copying data out of Repro manually.
 
-`@reproapp/mcp` runs over stdio for local AI clients and forwards MCP tool calls to Repro services. It can also run as an HTTP MCP server in a container when `PORT` is set or `REPRO_MCP_TRANSPORT=http`.
+## Add To Your AI Agent
 
-## AI Client Setup
-
-Default hosted Repro setup:
+Use the default hosted Repro setup:
 
 ```json
 {
@@ -19,181 +19,38 @@ Default hosted Repro setup:
 }
 ```
 
-Custom Repro deployment:
-
-```json
-{
-  "mcpServers": {
-    "repro": {
-      "command": "npx",
-      "args": ["-y", "@reproapp/mcp@latest"],
-      "env": {
-        "REPRO_AI_BASE_URL": "https://your-repro-ai-url/",
-        "REPRO_API_BASE_URL": "https://your-repro-api-url/api/",
-        "REPRO_WEB_BASE_URL": "https://your-repro-web-url/"
-      }
-    }
-  }
-}
-```
-
 The installed binary is `repro-mcp`.
 
-## Agent Rules
-
-When a user asks about Repro sessions, requests, traces, privacy policies, or app configuration, the AI client must use the Repro MCP tools only. It must not write local scripts, call Repro HTTP APIs directly, read cached Repro auth files, or patch policy JSON outside the MCP tool surface.
-
-Privacy policy updates are intentionally handle-based:
-
-- Use `inspect_privacy_policy` or `list_privacy_policy_blockers` first.
-- For one policy statement, pass the exact `statementSid` to `update_privacy_policy`.
-- For all currently listed blockers, pass the returned `blockerSetId` to `update_privacy_policy`.
-- Broad natural-language updates such as "make all blockers keep exact" are read-only/dry-run unless they include a `blockerSetId` or exact statement ids.
-- `KEEP_EXACT` on sensitive or raw-text review statements requires `force=true` and a human reason.
-
-## Configuration
-
-Built-in defaults:
-
-- `REPRO_AI_BASE_URL=https://repro-ai-u8lhw.ondigitalocean.app`
-- `REPRO_API_BASE_URL=https://repro-api-d7288.ondigitalocean.app/api`
-- `REPRO_WEB_BASE_URL=https://getrepro.io`
-
-Optional:
-
-- `REPRO_MCP_TRANSPORT` (`stdio` or `http`; default `http` when `PORT` is set, otherwise `stdio`)
-- `REPRO_MCP_HTTP_HOST`
-- `REPRO_MCP_HTTP_PORT`
-- `REPRO_MCP_HTTP_PATH`
-- `REPRO_MCP_CORS_ORIGIN`
-- `REPRO_API_BASE_URL`
-- `REPRO_API_PUBLIC_BASE_URL`
-- `REPRO_WEB_BASE_URL`
-- `REPRO_AI_TOKEN`
-- `REPRO_API_TOKEN`
-- `REPRO_DEFAULT_TENANT_ID`
-- `REPRO_APP_ID`
-- `REPRO_REQUEST_TIMEOUT_MS`
-- `REPRO_INVESTIGATE_TIMEOUT_MS`
-- `REPRO_MCP_ENV_FILE`
-- `REPRO_MCP_AUTH_FILE`
-- `REPRO_MCP_AUTH_TIMEOUT_MS`
-- `REPRO_MCP_AUTO_AUTH`
-- `REPRO_MCP_AUTH_MODE` (`wait` or `prompt`; default `prompt` for HTTP and `wait` for stdio)
-- `REPRO_MCP_OPEN_BROWSER`
-- `REPRO_MCP_DEBUG_LOG`
-- `REPRO_MCP_LAUNCH_LOG`
-- `REPRO_PATH_MAPPINGS`
-
-Hosted HTTP example:
-
-```bash
-export REPRO_MCP_HTTP_HOST="0.0.0.0"
-export REPRO_MCP_HTTP_PORT="8080"
-export REPRO_MCP_HTTP_PATH="/mcp"
-export REPRO_AI_BASE_URL="http://repro-ai:4011/"
-export REPRO_API_BASE_URL="http://api:4010/api/"
-export REPRO_API_PUBLIC_BASE_URL="https://api.example.com/api/"
-export REPRO_WEB_BASE_URL="https://app.example.com/"
-export REPRO_DEFAULT_TENANT_ID="TENANT_123"
-export REPRO_INVESTIGATE_TIMEOUT_MS="90000"
-export REPRO_MCP_AUTO_AUTH="true"
-export REPRO_MCP_AUTH_MODE="prompt"
-export REPRO_MCP_OPEN_BROWSER="false"
-export REPRO_PATH_MAPPINGS='[
-  {
-    "remotePrefix": "/srv/repro-demo",
-    "localPrefix": "/Users/alice/work/repro-demo"
-  }
-]'
-```
-
-`run-repro-mcp.sh` loads `repro-mcp/.env`, then `repro-mcp/.env.local`, then the file pointed to by `REPRO_MCP_ENV_FILE` when provided. Environment variables already set by the process take precedence in `src/index.js`; for DigitalOcean App Platform, prefer setting values in the app's environment configuration instead of committing an env file.
-
-`REPRO_API_BASE_URL` is used for privacy policy inspection/update tools and browser authentication. `REPRO_WEB_BASE_URL` is used for Privacy Studio links.
-
-For hosted MCP, point `REPRO_API_BASE_URL` at the private/internal API address used by the MCP container. Set `REPRO_API_PUBLIC_BASE_URL` to the public API origin users can open in a browser. The MCP server sends that public origin to the API when it creates browser-auth sessions, so the returned authorize URL is browser-accessible even when MCP talks to the API over VPC.
-
-`REPRO_PATH_MAPPINGS` is optional. Use it only when telemetry contains deployed code paths that should map to a checkout available inside the MCP runtime. For a hosted container without a mounted checkout, keep it as `[]`.
-
-For local development, copy `.env.local.example` to `.env.local`. It contains the old localhost defaults:
-
-- `REPRO_AI_BASE_URL=http://127.0.0.1:4011`
-- `REPRO_API_BASE_URL=http://127.0.0.1:4010/api`
-- `REPRO_WEB_BASE_URL=http://127.0.0.1:3000`
-- local `REPRO_PATH_MAPPINGS` for the demo checkout
-
-If `REPRO_AI_TOKEN` and `REPRO_API_TOKEN` are not set, `repro-mcp` starts a browser login flow against `REPRO_API_BASE_URL`, caches the resulting app-user bearer token, and reuses it on future requests. Stdio uses `REPRO_MCP_AUTH_MODE=wait`: it prints the authorize URL and waits for approval. HTTP uses `REPRO_MCP_AUTH_MODE=prompt`: the first protected MCP request returns a JSON-RPC error with `error.data.authorizeUrl`; open that URL, approve access, then retry the same MCP request.
-
-For the cached app-user token to work with `repro-ai`, configure `repro-ai` with the same `APP_USER_JWT_SECRET` as `repro-api`. Static `REPRO_AI_TOKEN` / `REPRO_API_TOKEN` values are optional overrides, not the normal hosted browser-auth path.
+## Use It
 
-`investigate` can legitimately take longer than the lower-level telemetry tools because it may retrieve scope context and run planner/answerer model calls. `REPRO_REQUEST_TIMEOUT_MS` controls the base timeout for all backend calls; `REPRO_INVESTIGATE_TIMEOUT_MS` overrides it just for `investigate` and defaults to at least 90 seconds.
+After adding the MCP server, ask your AI agent Repro-specific questions:
 
-## DigitalOcean
+```text
+Investigate why session SESSION_123 failed checkout.
 
-Container build:
+Show the request, trace, and DB evidence for this bug report.
 
-```bash
-docker build -t repro-mcp ./repro-mcp
-```
+Inspect privacy policy blockers for APP_123, serviceName orders-api, in dev.
 
-Minimum production environment:
-
-```bash
-REPRO_MCP_HTTP_HOST=0.0.0.0
-PORT=8080
-REPRO_MCP_HTTP_PATH=/mcp
-REPRO_AI_BASE_URL=http://repro-ai:4011/
-REPRO_API_BASE_URL=http://api:4010/api/
-REPRO_API_PUBLIC_BASE_URL=https://your-public-api-host/api/
-REPRO_WEB_BASE_URL=https://your-repro-web-host/
-REPRO_MCP_AUTO_AUTH=true
-REPRO_MCP_AUTH_MODE=prompt
-REPRO_MCP_OPEN_BROWSER=false
-REPRO_PATH_MAPPINGS=[]
+Update these privacy blockers using blockerSetId BLOCKERS_123, then explain what still needs review.
 ```
 
-DigitalOcean service requirements:
-
-- `repro-mcp` runs as a Web Service from `repro-mcp/Dockerfile` on port `8080`.
-- `repro-mcp` reaches `repro-api` and `repro-ai` through VPC/internal routing.
-- `REPRO_API_PUBLIC_BASE_URL` points to the public API URL used only for the browser authorize page.
-- `repro-api` and `repro-ai` share the same `APP_USER_JWT_SECRET`, so the browser-auth app-user JWT can authorize both services.
-
-HTTP endpoints:
-
-- `GET /health` and `GET /healthz`: health checks
-- `POST /mcp`: JSON-RPC MCP requests
-- `GET /mcp`: event-stream placeholder for clients that open a stream
+If authentication is required, the agent will provide an authorization URL.
+Open it, approve access, then retry the same request.
 
-The same tool handler backs stdio and HTTP transports.
+## Privacy Policy Safety
 
-## Run
+Privacy policy updates are handle-based:
 
-```bash
-npm start
-```
-
-`npm start` runs the HTTP server. Local stdio MCP clients should use:
+- Pass `serviceName` when an app has separate runtime policies per backend service.
+- Inspect first with `inspect_privacy_policy` or `list_privacy_policy_blockers`.
+- Update one statement with its exact `statementSid`.
+- Update a listed blocker set with the exact `blockerSetId`.
+- Broad requests such as "make all blockers keep exact" are read-only unless they include exact ids.
+- Sensitive `KEEP_EXACT` decisions require an explicit human reason.
 
-```bash
-npm run start:stdio
-```
+## Agent Rules
 
-## Tools
-
-- `investigate`
-- `resolve_scope`
-- `list_actions`
-- `list_requests`
-- `get_request`
-- `get_captured_value`
-- `get_requests_relative_to_anchor`
-- `get_db_changes`
-- `get_trace`
-- `get_action_path`
-- `get_function_candidates`
-- `inspect_privacy_policy`
-- `list_privacy_policy_blockers`
-- `update_privacy_policy`
-- `approve_privacy_policy`
+For Repro-scoped questions about sessions, requests, traces, privacy policies,
+apps, or configuration, use the Repro MCP tools. Do not call Repro HTTP APIs
+directly or edit policy JSON outside Repro.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reproapp/mcp",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "description": "Repro MCP server for AI-assisted debugging and privacy policy workflows",
   "license": "MIT",
   "type": "commonjs",

package/src/index.js

@@ -16,6 +16,8 @@ const SERVER_INSTRUCTIONS = [
   'For Repro-scoped questions about sessions, requests, traces, privacy policies, apps, or configuration, use the Repro MCP tools only.',
   'Do not create local scripts, read cached Repro auth files, or call Repro HTTP APIs directly for Repro data or policy workflows.',
   'For privacy policy writes, inspect first and then use exact statementSid(s) or blockerSetId. Broad natural-language policy update queries are read-only.',
+  'For factual debugging questions, use exact evidence tools first and answer from their structured output. Use investigate only after exact evidence is gathered, or when the user explicitly asks for synthesis/root cause.',
+  'Never answer that captured client data is absent because code appears to omit it. Verify with request, DB, trace, function-call, and message payload tools, then say exactly what Repro captured or did not capture.',
 ].join(' ');
 const DEFAULT_REPRO_AI_BASE_URL = 'https://repro-ai-u8lhw.ondigitalocean.app';
 const DEFAULT_REPRO_API_BASE_URL = 'https://repro-api-d7288.ondigitalocean.app/api';
@@ -36,6 +38,7 @@ const LOCAL_TOOL_DEFINITIONS = [
       properties: {
         tenantId: { type: 'string' },
         appId: { type: 'string' },
+        serviceName: { type: 'string' },
         sessionId: { type: 'string' },
         environment: { type: 'string' },
         state: { type: 'string', enum: ['active', 'pending', 'approved'] },
@@ -54,6 +57,7 @@ const LOCAL_TOOL_DEFINITIONS = [
       properties: {
         tenantId: { type: 'string' },
         appId: { type: 'string' },
+        serviceName: { type: 'string' },
         appIds: {
           type: 'array',
           items: { type: 'string' },
@@ -77,6 +81,7 @@ const LOCAL_TOOL_DEFINITIONS = [
       properties: {
         tenantId: { type: 'string' },
         appId: { type: 'string' },
+        serviceName: { type: 'string' },
         environment: { type: 'string' },
         state: { type: 'string', enum: ['active', 'pending', 'approved'] },
         query: { type: 'string' },
@@ -99,6 +104,7 @@ const LOCAL_TOOL_DEFINITIONS = [
       properties: {
         tenantId: { type: 'string' },
         appId: { type: 'string' },
+        serviceName: { type: 'string' },
         environment: { type: 'string' },
         state: { type: 'string', enum: ['active', 'pending', 'approved'] },
         query: { type: 'string' },
@@ -117,6 +123,7 @@ const LOCAL_TOOL_DEFINITIONS = [
       properties: {
         tenantId: { type: 'string' },
         appId: { type: 'string' },
+        serviceName: { type: 'string' },
         environment: { type: 'string' },
         state: { type: 'string', enum: ['active', 'pending', 'approved'] },
         query: { type: 'string' },
@@ -168,6 +175,7 @@ const LOCAL_TOOL_DEFINITIONS = [
       properties: {
         tenantId: { type: 'string' },
         appId: { type: 'string' },
+        serviceName: { type: 'string' },
         environment: { type: 'string' },
         openUi: { type: 'boolean' },
       },
@@ -193,6 +201,35 @@ const LOCAL_TOOL_DEFINITIONS = [
   },
 ];
 
+const TOOL_DESCRIPTION_OVERRIDES = {
+  investigate:
+    'Synthesize a root-cause hypothesis from Repro evidence after exact telemetry tools have been checked. Do not use this as the first or only tool for factual inventory questions about requests, DB changes, traces, function args/returns, emails, Kafka/RabbitMQ/messages, or payload contents; call the exact evidence tool first and cite that output.',
+  list_requests:
+    'Exact evidence tool: list captured HTTP and backend transport requests in scope. Use this before investigate whenever the user asks what request happened, which endpoint ran, request timing/status, or which request RID anchors later DB/trace/message evidence.',
+  get_request:
+    'Exact evidence tool: fetch one captured request by RID, including request/response bodies and captured value refs when present. Use this before answering factual questions about a specific request payload, response, endpoint, or transport message wrapper.',
+  list_session_evidence:
+    'Generic exact evidence tool: list every supported kind of captured session evidence without client-specific assumptions. Use this first for factual inventory questions about emails, messages, requests, DB changes, traces, actions, payloads, or whether data exists.',
+  get_session_evidence:
+    'Generic exact evidence tool: fetch the full structured data for one item returned by list_session_evidence. Use this before claiming captured fields are absent or omitted.',
+  get_requests_relative_to_anchor:
+    'Exact evidence tool: list captured requests before or after an action/request/DB anchor. Use for ordering questions and localizing the request sequence around a UI action or backend event.',
+  get_db_changes:
+    'Exact evidence tool: fetch captured DB/Redis changes. Use this before answering what collections, documents, fields, queries, mutations, or result metadata changed. Set includeQueryDetails when the user needs query/update/body details.',
+  get_trace:
+    'Exact evidence tool: fetch captured trace batches for a request RID. Use this before answering which functions ran, trace timing, thrown errors, or trace event details for a request.',
+  get_action_path:
+    'Exact evidence tool: fetch the correlated action path with requests, DB changes, and emails/messages when available. Use this to connect a UI action to backend evidence before giving a narrative answer.',
+  get_function_candidates:
+    'Exact evidence tool: find likely captured functions for an action/request/function search. Use this before get_function_calls when the exact function anchor is unclear.',
+  get_function_calls:
+    'Exact evidence tool: fetch concrete captured function calls, arguments, return values, errors, and value refs. Use this before answering what function handled something or what args/returns were captured.',
+  get_kafka_messages:
+    'Exact evidence tool: fetch captured Kafka publish/consume payloads. Use this for messaging questions and payload contents; for exact single-message lookups, the MCP server expands captured large values automatically.',
+  get_captured_value:
+    'Exact evidence tool: fetch the full masked value behind a captured valueId. Use this whenever another tool reports a captured value reference or large_value_available before claiming the payload is unavailable.',
+};
+
 function loadConfig(env = process.env) {
   const baseUrl = normalizeBaseUrl(env.REPRO_AI_BASE_URL || DEFAULT_REPRO_AI_BASE_URL);
   const apiBaseUrl = normalizeOptionalBaseUrl(env.REPRO_API_BASE_URL, DEFAULT_REPRO_API_BASE_URL);
@@ -1141,11 +1178,20 @@ async function handleRpcMessage(message, config, client, getTools) {
 function publicToolDefinition(tool) {
   return {
     name: tool.name,
-    description: tool.description,
+    description: publicToolDescription(tool),
     inputSchema: tool.inputSchema,
   };
 }
 
+function publicToolDescription(tool) {
+  const base = typeof tool?.description === 'string' ? tool.description.trim() : '';
+  const override = TOOL_DESCRIPTION_OVERRIDES[tool?.name];
+  if (!override) {
+    return base;
+  }
+  return base ? `${override} ${base}` : override;
+}
+
 function normalizeToolCatalog(catalog) {
   if (!catalog || typeof catalog !== 'object' || !Array.isArray(catalog.tools)) {
     throw new Error('repro-ai returned an invalid tool catalog');
@@ -1226,7 +1272,7 @@ function inputWithExactCapturedPayloads(name, input) {
 }
 
 async function expandLinkedCapturedPayloads(name, response, client, originalInput = {}) {
-  if (name !== 'get_kafka_messages') {
+  if (name === 'get_captured_value') {
     return response;
   }
 
@@ -1235,20 +1281,41 @@ async function expandLinkedCapturedPayloads(name, response, client, originalInpu
 
   while (true) {
     const links = collectCapturedPayloadLinks(root)
-      .filter((entry) => !visited.has(capturedPayloadLinkKey(entry.link)));
-    if (!links.length) {
+      .filter((entry) => !visited.has(capturedPayloadExpansionKey(entry)));
+    const valueRefs = collectCapturedValueRefs(root)
+      .filter((entry) => !visited.has(capturedPayloadExpansionKey(entry)));
+    const expansions = [...links, ...valueRefs];
+    if (!expansions.length) {
       return root;
     }
 
-    for (const { link } of links) {
-      const key = capturedPayloadLinkKey(link);
+    for (const expansion of expansions) {
+      const key = capturedPayloadExpansionKey(expansion);
       visited.add(key);
 
-      const toolName = typeof link.tool === 'string' ? link.tool : '';
-      if (toolName !== 'get_kafka_messages') {
-        throw new Error(`Cannot expand captured payload through unsupported MCP tool: ${toolName || 'unknown'}`);
+      if (expansion.kind === 'value-capture') {
+        const valueId = expansion.capture?.valueId;
+        if (typeof valueId !== 'string' || !valueId.trim()) {
+          continue;
+        }
+        const expanded = await client.executeTool('get_captured_value', {
+          ...originalInput,
+          valueId: valueId.trim(),
+        });
+        const value = expanded?.data?.capturedValue?.value ?? expanded?.capturedValue?.value;
+        if (typeof value === 'undefined') {
+          throw new Error(`Repro MCP could not expand captured value ${valueId}`);
+        }
+        expansion.holder[expansion.targetKey] = value;
+        const availabilityKey = `${expansion.targetKey}Availability`;
+        if (typeof expansion.holder[availabilityKey] === 'string') {
+          expansion.holder[availabilityKey] = 'captured';
+        }
+        continue;
       }
 
+      const { link } = expansion;
+      const toolName = typeof link.tool === 'string' ? link.tool : '';
       const linkArgs = link.arguments && typeof link.arguments === 'object' && !Array.isArray(link.arguments)
         ? link.arguments
         : {};
@@ -1299,8 +1366,72 @@ function collectCapturedPayloadLinks(value, out = []) {
   return out;
 }
 
-function capturedPayloadLinkKey(link) {
+function collectCapturedValueRefs(value, out = []) {
+  if (!value || typeof value !== 'object') {
+    return out;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      collectCapturedValueRefs(item, out);
+    }
+    return out;
+  }
+
+  for (const [key, nested] of Object.entries(value)) {
+    if (
+      key.endsWith('ValueCapture') &&
+      nested &&
+      typeof nested === 'object' &&
+      !Array.isArray(nested) &&
+      nested.status === 'stored' &&
+      typeof nested.valueId === 'string' &&
+      nested.valueId.trim()
+    ) {
+      const targetKey = valueCaptureTargetKey(key);
+      if (targetKey && shouldExpandValueCaptureTarget(value[targetKey])) {
+        out.push({
+          kind: 'value-capture',
+          holder: value,
+          captureKey: key,
+          targetKey,
+          capture: nested,
+        });
+      }
+    }
+    collectCapturedValueRefs(nested, out);
+  }
+  return out;
+}
+
+function shouldExpandValueCaptureTarget(value) {
+  if (typeof value === 'undefined' || value === null) return true;
+  return Boolean(
+    value &&
+      typeof value === 'object' &&
+      !Array.isArray(value) &&
+      value.__kind === 'omitted'
+  );
+}
+
+function valueCaptureTargetKey(key) {
+  if (key === 'responseBodyValueCapture') return 'responseBody';
+  if (key === 'respBodyValueCapture') return 'respBody';
+  if (!key.endsWith('ValueCapture')) return null;
+  const base = key.slice(0, -'ValueCapture'.length);
+  return base || null;
+}
+
+function capturedPayloadExpansionKey(expansion) {
+  if (expansion?.kind === 'value-capture') {
+    return JSON.stringify({
+      kind: 'value-capture',
+      valueId: expansion.capture?.valueId ?? null,
+      targetKey: expansion.targetKey ?? null,
+    });
+  }
+  const link = expansion?.link;
   return JSON.stringify({
+    kind: 'mcp-link',
     tool: link?.tool ?? null,
     path: link?.path ?? null,
     arguments: link?.arguments ?? null,
@@ -1470,10 +1601,11 @@ async function resolveScope(input, config, client) {
   const appId = optionalNonEmptyString(input.appId) || config.defaultAppId;
   const sessionId = optionalNonEmptyString(input.sessionId);
   if (appId && !sessionId) {
+    const serviceName = optionalNonEmptyString(input.serviceName);
     const requestedEnvironment = optionalNonEmptyString(input.environment);
     const state = normalizePolicyState(input.state);
     const query = optionalNonEmptyString(input.query) || '';
-    const privacyConfig = await client.requestApi(`v1/apps/${encodeURIComponent(appId)}/privacy`, {
+    const privacyConfig = await client.requestApi(buildPrivacyApiPath(appId, serviceName), {
       method: 'GET',
       headers: input.tenantId ? { 'x-tenant-id': input.tenantId } : undefined,
     });
@@ -1485,6 +1617,7 @@ async function resolveScope(input, config, client) {
       selection?.environmentId ?? requestedEnvironment,
       query,
       input.openUi === true,
+      serviceName,
     );
     if (ui.openRequested) {
       try {
@@ -1499,6 +1632,7 @@ async function resolveScope(input, config, client) {
       status: selection ? 'ok' : 'not_found',
       kind: 'app_privacy_scope',
       appId,
+      serviceName: serviceName ?? null,
       tenantId: optionalNonEmptyString(input.tenantId) || config.defaultTenantId || null,
       environment: selection?.environmentId ?? requestedEnvironment ?? null,
       state: selection?.state ?? state,
@@ -1559,6 +1693,7 @@ async function checkPrivacyCoverage(input, config, client) {
   const appIds = normalizeCoverageAppIds(input, config);
   const state = normalizePolicyState(input.state);
   const requestedEnvironment = optionalNonEmptyString(input.environment);
+  const serviceName = optionalNonEmptyString(input.serviceName);
   const topic = normalizeCoverageTopic(input);
   const query = queryForCoverageTopic(topic);
   const includeTechnical = input.includeTechnical === true;
@@ -1566,7 +1701,7 @@ async function checkPrivacyCoverage(input, config, client) {
 
   for (const appId of appIds) {
     try {
-      const privacyConfig = await client.requestApi(`v1/apps/${encodeURIComponent(appId)}/privacy`, {
+      const privacyConfig = await client.requestApi(buildPrivacyApiPath(appId, serviceName), {
         method: 'GET',
         headers: input.tenantId ? { 'x-tenant-id': input.tenantId } : undefined,
       });
@@ -1578,7 +1713,7 @@ async function checkPrivacyCoverage(input, config, client) {
           environment: requestedEnvironment ?? null,
           state,
           summary: 'No pending or approved privacy policy was found for this app/environment.',
-          ui: buildPrivacyStudioUi(config, appId, requestedEnvironment, query, false),
+          ui: buildPrivacyStudioUi(config, appId, requestedEnvironment, query, false, serviceName),
           matches: [],
           needsReviewReasons: ['No policy found.'],
         });
@@ -1598,13 +1733,20 @@ async function checkPrivacyCoverage(input, config, client) {
         ? assessPolicyBlockerCoverage(matchedStatements, contradictions)
         : assessCoverage(matchedStatements, contradictions);
       const evidence = buildCoverageEvidence(matchedStatements, contradictions, { includeTechnical });
-      const ui = buildPrivacyStudioUi(config, appId, selection.environmentId, query, input.openUi === true);
+      const ui = buildPrivacyStudioUi(
+        config,
+        appId,
+        selection.environmentId,
+        query,
+        input.openUi === true,
+        serviceName,
+      );
       const policyBlockers = buildPolicyBlockerSummaries(
         blockerQuery ? matchedStatements : matchedStatements.filter(isReviewBlockerStatement),
         config,
         appId,
         selection.environmentId,
-        { includeTechnical },
+        { includeTechnical, serviceName },
       );
       if (ui.openRequested) {
         try {
@@ -1618,6 +1760,7 @@ async function checkPrivacyCoverage(input, config, client) {
 
       results.push({
           appId,
+          serviceName: serviceName ?? null,
           environment: selection.environmentId,
           state: selection.state,
           inspectedPolicy: {
@@ -1647,7 +1790,7 @@ async function checkPrivacyCoverage(input, config, client) {
         environment: requestedEnvironment ?? null,
         state,
         summary: error instanceof Error ? error.message : String(error),
-        ui: buildPrivacyStudioUi(config, appId, requestedEnvironment, query, false),
+        ui: buildPrivacyStudioUi(config, appId, requestedEnvironment, query, false, serviceName),
         matches: [],
         needsReviewReasons: ['Could not inspect policy because the API request failed.'],
       });
@@ -1666,6 +1809,7 @@ async function checkPrivacyCoverage(input, config, client) {
     inspected: {
       requestedEnvironment: requestedEnvironment ?? null,
       requestedState: state,
+      serviceName: serviceName ?? null,
       appCount: appIds.length,
     },
     summary: summarizeCoverageResults({ safe, needsReview, notCovered, errors }),
@@ -1989,9 +2133,10 @@ async function inspectPrivacyPolicy(input, config, client) {
     throw rpcError(-32603, 'This MCP client cannot fetch app privacy policies');
   }
 
+  const serviceName = optionalNonEmptyString(input.serviceName);
   const requestedEnvironment = optionalNonEmptyString(input.environment);
   const state = normalizePolicyState(input.state);
-  const privacyConfig = await client.requestApi(`v1/apps/${encodeURIComponent(appId)}/privacy`, {
+  const privacyConfig = await client.requestApi(buildPrivacyApiPath(appId, serviceName), {
     method: 'GET',
     headers: input.tenantId ? { 'x-tenant-id': input.tenantId } : undefined,
   });
@@ -2000,10 +2145,18 @@ async function inspectPrivacyPolicy(input, config, client) {
     return {
       status: 'not_found',
       appId,
+      serviceName: serviceName ?? null,
       environment: requestedEnvironment ?? null,
       state,
       message: 'No pending or approved privacy policy exists for the requested app/environment.',
-      ui: buildPrivacyStudioUi(config, appId, requestedEnvironment, policyInspectionQuery(input), input.openUi === true),
+      ui: buildPrivacyStudioUi(
+        config,
+        appId,
+        requestedEnvironment,
+        policyInspectionQuery(input),
+        input.openUi === true,
+        serviceName,
+      ),
     };
   }
 
@@ -2015,7 +2168,14 @@ async function inspectPrivacyPolicy(input, config, client) {
   const matchedLeaves = new Set(matches.flatMap((match) => statementTargetLeaves(match.statement)));
   const contradictions = findSameLeafPolicyContradictions(statements, matchedLeaves);
   const uiQuery = query || contradictions[0]?.leaf || '';
-  const ui = buildPrivacyStudioUi(config, appId, selection.environmentId, uiQuery, input.openUi === true);
+  const ui = buildPrivacyStudioUi(
+    config,
+    appId,
+    selection.environmentId,
+    uiQuery,
+    input.openUi === true,
+    serviceName,
+  );
   const blockerStatements = blockerQuery
     ? matches.map((match) => match.statement).filter(isReviewBlockerStatement)
     : matches.map((match) => match.statement).filter(isReviewBlockerStatement);
@@ -2024,12 +2184,13 @@ async function inspectPrivacyPolicy(input, config, client) {
     config,
     appId,
     selection.environmentId,
-    { includeTechnical },
+    { includeTechnical, serviceName },
   );
   const blockerSet = policyBlockers.length
     ? rememberPrivacyBlockerSet({
         tenantId: optionalNonEmptyString(input.tenantId) || config.defaultTenantId || null,
         appId,
+        serviceName,
         environment: selection.environmentId,
         state: selection.state,
         query,
@@ -2049,6 +2210,7 @@ async function inspectPrivacyPolicy(input, config, client) {
   return {
     status: 'ok',
     appId,
+    serviceName: serviceName ?? null,
     environment: selection.environmentId,
     state: selection.state,
     generatedAt: selection.record?.policy?.generatedAt ?? selection.record?.generatedAt ?? null,
@@ -2080,12 +2242,13 @@ async function updatePrivacyPolicy(input, config, client) {
     throw rpcError(-32603, 'This MCP client cannot fetch or update app privacy policies');
   }
 
+  const serviceName = optionalNonEmptyString(input.serviceName);
   const requestedEnvironment = optionalNonEmptyString(input.environment);
   const state = normalizePolicyState(input.state);
   const decision = normalizePolicyUpdateDecision(input.decision);
   const apply = input.apply === true;
   const approve = input.approve === true;
-  const privacyConfig = await client.requestApi(`v1/apps/${encodeURIComponent(appId)}/privacy`, {
+  const privacyConfig = await client.requestApi(buildPrivacyApiPath(appId, serviceName), {
     method: 'GET',
     headers: input.tenantId ? { 'x-tenant-id': input.tenantId } : undefined,
   });
@@ -2094,10 +2257,18 @@ async function updatePrivacyPolicy(input, config, client) {
     return {
       status: 'not_found',
       appId,
+      serviceName: serviceName ?? null,
       environment: requestedEnvironment ?? null,
       state,
       summary: 'No pending or approved privacy policy exists for the requested app/environment.',
-      ui: buildPrivacyStudioUi(config, appId, requestedEnvironment, policyInspectionQuery(input), input.openUi === true),
+      ui: buildPrivacyStudioUi(
+        config,
+        appId,
+        requestedEnvironment,
+        policyInspectionQuery(input),
+        input.openUi === true,
+        serviceName,
+      ),
     };
   }
 
@@ -2106,6 +2277,7 @@ async function updatePrivacyPolicy(input, config, client) {
   const blockerSetSelection = resolvePrivacyBlockerSetSelection(input, {
     tenantId: optionalNonEmptyString(input.tenantId) || config.defaultTenantId || null,
     appId,
+    serviceName,
     environment: selection.environmentId,
     state: selection.state,
   });
@@ -2114,10 +2286,18 @@ async function updatePrivacyPolicy(input, config, client) {
       status: 'blocked',
       code: blockerSetSelection.error.code,
       appId,
+      serviceName: serviceName ?? null,
       environment: selection.environmentId,
       state: selection.state,
       summary: blockerSetSelection.error.message,
-      ui: buildPrivacyStudioUi(config, appId, selection.environmentId, query, input.openUi === true),
+      ui: buildPrivacyStudioUi(
+        config,
+        appId,
+        selection.environmentId,
+        query,
+        input.openUi === true,
+        serviceName,
+      ),
       nextStep: 'Run inspect_privacy_policy or list_privacy_policy_blockers again, then pass the returned blockerSetId.',
     };
   }
@@ -2132,10 +2312,18 @@ async function updatePrivacyPolicy(input, config, client) {
     return {
       status: 'not_found',
       appId,
+      serviceName: serviceName ?? null,
       environment: selection.environmentId,
       state: selection.state,
       summary: 'No matching policy statements were found for the requested update.',
-      ui: buildPrivacyStudioUi(config, appId, selection.environmentId, query, input.openUi === true),
+      ui: buildPrivacyStudioUi(
+        config,
+        appId,
+        selection.environmentId,
+        query,
+        input.openUi === true,
+        serviceName,
+      ),
       matches: rankPolicyStatementMatches(statements, input, query).slice(0, 8).map((match) => formatPolicyMatch(match.statement, match.score, { includeTechnical: true })),
     };
   }
@@ -2144,10 +2332,18 @@ async function updatePrivacyPolicy(input, config, client) {
       status: 'blocked',
       code: 'STALE_BLOCKER_SET',
       appId,
+      serviceName: serviceName ?? null,
       environment: selection.environmentId,
       state: selection.state,
       summary: `The blockerSetId references ${blockerSetSelection.statementSids.length} statement(s), but only ${selectedStatements.length} still exist in the current policy.`,
-      ui: buildPrivacyStudioUi(config, appId, selection.environmentId, query, input.openUi === true),
+      ui: buildPrivacyStudioUi(
+        config,
+        appId,
+        selection.environmentId,
+        query,
+        input.openUi === true,
+        serviceName,
+      ),
       matches: selectedStatements.map((statement) => formatPolicyMatch(statement, 0, { includeTechnical: true })),
       nextStep: 'Run inspect_privacy_policy or list_privacy_policy_blockers again, then retry with the new blockerSetId.',
     };
@@ -2164,10 +2360,18 @@ async function updatePrivacyPolicy(input, config, client) {
       status: 'blocked',
       code: safety.code,
       appId,
+      serviceName: serviceName ?? null,
       environment: selection.environmentId,
       state: selection.state,
       summary: safety.summary,
-      ui: buildPrivacyStudioUi(config, appId, selection.environmentId, query, input.openUi === true),
+      ui: buildPrivacyStudioUi(
+        config,
+        appId,
+        selection.environmentId,
+        query,
+        input.openUi === true,
+        serviceName,
+      ),
       matches: selectedStatements.map((statement) => formatPolicyMatch(statement, 0, { includeTechnical: true })),
       proposed: safeBuildPolicyUpdateDiff(selection.policy, selectedStatements, decision, input.rawTextHints),
       safety,
@@ -2182,6 +2386,7 @@ async function updatePrivacyPolicy(input, config, client) {
     selection.environmentId,
     query || selectedStatements[0]?.when?.selector || '',
     input.openUi === true,
+    serviceName,
   );
   if (ui.openRequested) {
     try {
@@ -2197,6 +2402,7 @@ async function updatePrivacyPolicy(input, config, client) {
     return {
       status: 'dry_run',
       appId,
+      serviceName: serviceName ?? null,
       environment: selection.environmentId,
       state: selection.state,
       summary: `Prepared privacy policy update for ${selectedStatements.length} statement(s). No API write was made because apply=true was not set.`,
@@ -2211,9 +2417,18 @@ async function updatePrivacyPolicy(input, config, client) {
     };
   }
 
-  const policyTarget = privacyPolicyTargetForApp(appId, selection.record, selection.policy);
+  const policyTarget = privacyPolicyTargetForApp(
+    appId,
+    serviceName,
+    selection.record,
+    selection.policy,
+  );
   const pendingConfig = await client.requestApi(
-    `v1/apps/${encodeURIComponent(appId)}/privacy/environments/${encodeURIComponent(selection.environmentId)}/policy`,
+    buildPrivacyApiPath(
+      appId,
+      serviceName,
+      `/environments/${encodeURIComponent(selection.environmentId)}/policy`,
+    ),
     {
       method: 'PUT',
       headers: input.tenantId ? { 'x-tenant-id': input.tenantId } : undefined,
@@ -2241,7 +2456,11 @@ async function updatePrivacyPolicy(input, config, client) {
   let approvedConfig = null;
   if (approve) {
     approvedConfig = await client.requestApi(
-      `v1/apps/${encodeURIComponent(appId)}/privacy/environments/${encodeURIComponent(selection.environmentId)}/pending/approve`,
+      buildPrivacyApiPath(
+        appId,
+        serviceName,
+        `/environments/${encodeURIComponent(selection.environmentId)}/pending/approve`,
+      ),
       {
         method: 'POST',
         headers: input.tenantId ? { 'x-tenant-id': input.tenantId } : undefined,
@@ -2252,6 +2471,7 @@ async function updatePrivacyPolicy(input, config, client) {
   return {
     status: approve ? 'approved' : 'pending',
     appId,
+    serviceName: serviceName ?? null,
     environment: selection.environmentId,
     previousState: selection.state,
     summary: approve
@@ -2280,8 +2500,9 @@ async function approvePrivacyPolicy(input, config, client) {
     throw rpcError(-32603, 'This MCP client cannot approve app privacy policies');
   }
 
+  const serviceName = optionalNonEmptyString(input.serviceName);
   const requestedEnvironment = optionalNonEmptyString(input.environment);
-  const privacyConfig = await client.requestApi(`v1/apps/${encodeURIComponent(appId)}/privacy`, {
+  const privacyConfig = await client.requestApi(buildPrivacyApiPath(appId, serviceName), {
     method: 'GET',
     headers: input.tenantId ? { 'x-tenant-id': input.tenantId } : undefined,
   });
@@ -2290,13 +2511,25 @@ async function approvePrivacyPolicy(input, config, client) {
     return {
       status: 'not_found',
       appId,
+      serviceName: serviceName ?? null,
       environment: requestedEnvironment ?? null,
       summary: 'No pending privacy policy exists for the requested app/environment.',
-      ui: buildPrivacyStudioUi(config, appId, requestedEnvironment, '', input.openUi === true),
+      ui: buildPrivacyStudioUi(
+        config,
+        appId,
+        requestedEnvironment,
+        '',
+        input.openUi === true,
+        serviceName,
+      ),
     };
   }
   const approvedConfig = await client.requestApi(
-    `v1/apps/${encodeURIComponent(appId)}/privacy/environments/${encodeURIComponent(selection.environmentId)}/pending/approve`,
+    buildPrivacyApiPath(
+      appId,
+      serviceName,
+      `/environments/${encodeURIComponent(selection.environmentId)}/pending/approve`,
+    ),
     {
       method: 'POST',
       headers: input.tenantId ? { 'x-tenant-id': input.tenantId } : undefined,
@@ -2305,9 +2538,17 @@ async function approvePrivacyPolicy(input, config, client) {
   return {
     status: 'approved',
     appId,
+    serviceName: serviceName ?? null,
     environment: selection.environmentId,
     summary: 'Approved pending privacy policy through the Repro API validation path.',
-    ui: buildPrivacyStudioUi(config, appId, selection.environmentId, '', input.openUi === true),
+    ui: buildPrivacyStudioUi(
+      config,
+      appId,
+      selection.environmentId,
+      '',
+      input.openUi === true,
+      serviceName,
+    ),
     api: {
       approvedEnvironmentCount: Array.isArray(approvedConfig?.environments) ? approvedConfig.environments.length : undefined,
     },
@@ -2415,7 +2656,15 @@ function cleanupExpiredPrivacyBlockerSets(now = Date.now()) {
   }
 }
 
-function rememberPrivacyBlockerSet({ tenantId, appId, environment, state, query, statements }) {
+function rememberPrivacyBlockerSet({
+  tenantId,
+  appId,
+  serviceName,
+  environment,
+  state,
+  query,
+  statements,
+}) {
   cleanupExpiredPrivacyBlockerSets();
   const statementSids = mergeUniqueStrings(
     (statements ?? []).map((statement) => String(statement?.sid ?? '')).filter(Boolean),
@@ -2425,6 +2674,7 @@ function rememberPrivacyBlockerSet({ tenantId, appId, environment, state, query,
     v: 1,
     tenantId: tenantId || null,
     appId,
+    serviceName: serviceName || null,
     environment,
     state,
     queryHash: crypto.createHash('sha256').update(query || '').digest('hex').slice(0, 12),
@@ -2439,6 +2689,7 @@ function rememberPrivacyBlockerSet({ tenantId, appId, environment, state, query,
     id,
     tenantId: payload.tenantId,
     appId: payload.appId,
+    serviceName: payload.serviceName,
     environment: payload.environment,
     state: payload.state,
     query: query || null,
@@ -2483,6 +2734,9 @@ function resolvePrivacyBlockerSetSelection(input, expected) {
   }
   const mismatches = [];
   if (record.appId !== expected.appId) mismatches.push(`appId ${record.appId}`);
+  if ((record.serviceName || null) !== (expected.serviceName || null)) {
+    mismatches.push(`serviceName ${record.serviceName || '(app-wide)'}`);
+  }
   if (record.environment !== expected.environment) mismatches.push(`environment ${record.environment}`);
   if (record.state !== expected.state) mismatches.push(`state ${record.state}`);
   if (record.tenantId && expected.tenantId && record.tenantId !== expected.tenantId) {
@@ -2908,15 +3162,21 @@ function mergeUniqueStrings(values) {
   return output;
 }
 
-function privacyPolicyTargetForApp(appId, record, policy) {
+function privacyPolicyTargetForApp(appId, serviceName, record, policy) {
   const target =
     record?.proposal?.target ??
     policy?.sourceProposal?.target ??
     {};
-  return {
+  const result = {
     ...target,
     appId,
   };
+  if (serviceName) {
+    result.serviceName = serviceName;
+  } else {
+    delete result.serviceName;
+  }
+  return result;
 }
 
 function cloneJson(value) {
@@ -3159,7 +3419,14 @@ function buildPolicyBlockerSummaries(statements, config, appId, environment, opt
       const descriptor = describePolicyStatement(statement);
       const review = statement?.meta?.review ?? {};
       const query = descriptor.codeAnchor || descriptor.label || statement?.when?.selector || '';
-      const ui = buildPrivacyStudioUi(config, appId, environment, query, false);
+      const ui = buildPrivacyStudioUi(
+        config,
+        appId,
+        environment,
+        query,
+        false,
+        options.serviceName,
+      );
       const blocker = {
         label: descriptor.label,
         codeAnchor: descriptor.codeAnchor,
@@ -3402,7 +3669,22 @@ function summarizeRawTextHints(policy, query) {
     }));
 }
 
-function buildPrivacyStudioUi(config, appId, environment, query, openRequested) {
+function buildPrivacyApiPath(appId, serviceName, suffix = '') {
+  const path = `v1/apps/${encodeURIComponent(appId)}/privacy${suffix}`;
+  if (!serviceName) {
+    return path;
+  }
+  return `${path}?serviceName=${encodeURIComponent(serviceName)}`;
+}
+
+function buildPrivacyStudioUi(
+  config,
+  appId,
+  environment,
+  query,
+  openRequested,
+  serviceName,
+) {
   const baseUrl = config.webBaseUrl || deriveWebBaseUrl(config.apiBaseUrl);
   if (!baseUrl) {
     return {
@@ -3415,6 +3697,9 @@ function buildPrivacyStudioUi(config, appId, environment, query, openRequested)
 
   const url = new URL('/admin/privacy', baseUrl);
   url.searchParams.set('service', appId);
+  if (serviceName) {
+    url.searchParams.set('serviceName', serviceName);
+  }
   if (environment) {
     url.searchParams.set('env', environment);
   }