Patch data on OPA

Instructions

Implementation Reference

• src/tools/server-management/data.ts:75-110 (handler)

  The tool handler for 'opa_patch_data'. Registers an MCP tool that accepts a 'path' and 'operations' (JSON Patch), sends a PATCH request to the OPA server with Content-Type application/json-patch+json, and returns success/failure.

  server.registerTool(
    'opa_patch_data',
    {
      title: 'Patch data on OPA',
      description:
        'Apply a JSON Patch (RFC 6902) to the data document. Each operation is `{ op, path, value? }`.',
      inputSchema: {
        path: z.string().min(1).describe('Data path the patch is applied to. Use "" for the root.'),
        operations: z
          .array(
            z.object({
              op: z.enum(['add', 'remove', 'replace']),
              path: z.string(),
              value: z.unknown().optional(),
            }),
          )
          .min(1)
          .describe('Array of JSON Patch operations.'),
      },
    },
    async ({ path, operations }) => {
      return withToolEnvelope<{ path: string; patched: boolean }>(config, async () => {
        try {
          await opa.request({
            method: 'PATCH',
            path: dataPath(path),
            body: operations,
            headers: { 'Content-Type': 'application/json-patch+json' },
          });
          return ok({ path, patched: true });
        } catch (e) {
          return mapOpaClientError(e);
        }
      });
    },
  );

• src/tools/server-management/data.ts:81-93 (schema)

  Input schema for opa_patch_data using Zod. Defines 'path' (string) and 'operations' (array of {op: 'add'|'remove'|'replace', path: string, value?: unknown}) as required inputs.

  inputSchema: {
    path: z.string().min(1).describe('Data path the patch is applied to. Use "" for the root.'),
    operations: z
      .array(
        z.object({
          op: z.enum(['add', 'remove', 'replace']),
          path: z.string(),
          value: z.unknown().optional(),
        }),
      )
      .min(1)
      .describe('Array of JSON Patch operations.'),
  },

• src/tools/index.ts:37-43 (registration)

  The top-level registration entry point. registerTools() calls registerServerManagementTools() which in turn calls registerDataTools() where opa_patch_data is registered.

  export function registerTools(server: McpServer, config: Config): void {
    registerAuthoringTools(server, config);
    registerEvaluationTools(server, config);
    registerBundleTools(server, config);
    registerServerManagementTools(server, config);
    registerHelperTools(server, config);
  }

• src/tools/server-management/index.ts:16-21 (registration)

  registerServerManagementTools() calls registerDataTools() which registers opa_patch_data among other data tools.

  export function registerServerManagementTools(server: McpServer, config: Config): void {
    registerPolicyTools(server, config);
    registerDataTools(server, config);
    registerDecisionTools(server, config);
    registerStatusTools(server, config);
  }

• src/tools/server-management/_shared.ts:16-45 (helper)

  mapOpaClientError helper function used in the opa_patch_data handler to translate OpaClient exceptions into structured error envelopes.

  export function mapOpaClientError(
    e: unknown,
    notFoundCode: ToolErrorCode = 'UNKNOWN_ERROR',
  ): ToolEnvelope<never> {
    if (e instanceof OpaUnreachableError) {
      return err('OPA_UNREACHABLE', `OPA server unreachable at ${e.url}`, {
        hint: 'Confirm OPA_URL points at a running OPA server (e.g. `curl $OPA_URL/health`).',
        details: { url: e.url },
      });
    }
    if (e instanceof OpaAuthError) {
      return err('OPA_AUTH_FAILED', 'OPA rejected the request with 401 Unauthorized.', {
        hint: 'Set OPA_TOKEN to a valid bearer token, or remove the auth requirement on the OPA server.',
      });
    }
    if (e instanceof OpaHttpError) {
      if (e.status === 404) {
        return err(notFoundCode, `OPA returned 404 Not Found.`, {
          details: { status: e.status, body: e.body },
        });
      }
      return err('UNKNOWN_ERROR', `OPA returned HTTP ${e.status}.`, {
        details: { status: e.status, body: e.body },
      });
    }
    const message = e instanceof Error ? e.message : 'Unknown error';
    return err('UNKNOWN_ERROR', message, {
      details: e instanceof Error ? { stack: e.stack } : { value: e },
    });
  }