Compile (partially evaluate) a query on OPA

Instructions

Implementation Reference

• src/tools/server-management/decisions.ts:88-105 (handler)

  Handler function for the opa_compile_query tool. Sends a POST to OPA's /v1/compile endpoint for partial evaluation, returning the residual query.

    async ({ query, input, unknowns }) => {
      return withToolEnvelope<{ result: unknown }>(config, async () => {
        try {
          const body: Record<string, unknown> = { query };
          if (input !== undefined) body['input'] = input;
          body['unknowns'] = unknowns?.length ? unknowns : ['input'];
          const data = await opa.request<{ result: unknown }>({
            method: 'POST',
            path: '/v1/compile',
            body,
          });
          return ok({ result: data.result });
        } catch (e) {
          return mapOpaClientError(e);
        }
      });
    },
  );

• src/tools/server-management/decisions.ts:75-87 (schema)

  Input schema and metadata for the opa_compile_query tool, defining the 'query' (required string), 'input' (optional unknown), and 'unknowns' (optional array of strings) parameters.

  {
    title: 'Compile (partially evaluate) a query on OPA',
    description:
      "Send a query to the OPA server's `/v1/compile` endpoint for partial evaluation. Returns the residual query — what remains after substituting in everything that's known.",
    inputSchema: {
      query: z.string().min(1).describe('Rego query to compile, e.g. "data.rbac.allow == true".'),
      input: z.unknown().optional().describe('Optional partial input document.'),
      unknowns: z
        .array(z.string())
        .optional()
        .describe('Refs to treat as unknown (default: ["input"]).'),
    },
  },

• src/tools/server-management/decisions.ts:73-105 (registration)

  Tool registration on the MCP server via server.registerTool, within the registerDecisionTools function exported from the decisions module.

  server.registerTool(
    'opa_compile_query',
    {
      title: 'Compile (partially evaluate) a query on OPA',
      description:
        "Send a query to the OPA server's `/v1/compile` endpoint for partial evaluation. Returns the residual query — what remains after substituting in everything that's known.",
      inputSchema: {
        query: z.string().min(1).describe('Rego query to compile, e.g. "data.rbac.allow == true".'),
        input: z.unknown().optional().describe('Optional partial input document.'),
        unknowns: z
          .array(z.string())
          .optional()
          .describe('Refs to treat as unknown (default: ["input"]).'),
      },
    },
    async ({ query, input, unknowns }) => {
      return withToolEnvelope<{ result: unknown }>(config, async () => {
        try {
          const body: Record<string, unknown> = { query };
          if (input !== undefined) body['input'] = input;
          body['unknowns'] = unknowns?.length ? unknowns : ['input'];
          const data = await opa.request<{ result: unknown }>({
            method: 'POST',
            path: '/v1/compile',
            body,
          });
          return ok({ result: data.result });
        } catch (e) {
          return mapOpaClientError(e);
        }
      });
    },
  );

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

  Error mapping helper used by the tool handler to translate OPA client 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 },
    });
  }