Describe Rego policy

Instructions

Implementation Reference

• src/tools/helpers/describe-policy.ts:74-137 (handler)

  The handler function that registers and implements the 'rego_describe_policy' tool. It parses Rego source via `opa parse --format=json`, then extracts package name, imports, rules (with metadata like default/args/body-length), and annotations into a structured summary.

  export function registerRegoDescribePolicy(server: McpServer, config: Config): void {
    const opa = new OpaCli(config);
  
    server.registerTool(
      'rego_describe_policy',
      {
        title: 'Describe Rego policy',
        description:
          'Parse a Rego policy and return a structured summary: package, imports, rules (with default/args/body-length flags), and inline annotations. Useful as the first step in any "what does this policy do" workflow.',
        inputSchema: RegoDescribePolicyInput,
      },
      async ({ source }) => {
        return withToolEnvelope<RegoDescribePolicyOutput>(config, async () => {
          const result = await opa.parse({ source });
          const subprocessFailure = mapSubprocessFailure(result, 'opa');
          if (subprocessFailure) return subprocessFailure;
          if (result.exitCode !== 0) {
            return err('INVALID_REGO', 'opa parse rejected the source.', {
              details: { stderr: result.stderr.trim() },
            });
          }
          const ast = tryParseJson<ParsedAst>(result.stdout);
          if (ast === undefined) {
            return err('UNKNOWN_ERROR', 'opa parse produced no parseable JSON.');
          }
  
          const packageParts = ast.package?.path?.slice(1) ?? [];
          const packageName = refToString(packageParts);
  
          const imports = (ast.imports ?? []).map((imp) => {
            const path = refToString(imp.path?.value);
            return imp.alias ? `${path} as ${imp.alias}` : path;
          });
  
          const seen = new Map<string, DescribedRule>();
          for (const rule of ast.rules ?? []) {
            const name = rule.head?.name ?? refToString(rule.head?.ref);
            if (!name) continue;
            const existing = seen.get(name);
            if (existing) {
              existing.bodyLength += rule.body?.length ?? 0;
              continue;
            }
            seen.set(name, {
              name,
              isDefault: rule.default === true,
              hasArgs: Array.isArray(rule.head?.args) && (rule.head?.args.length ?? 0) > 0,
              bodyLength: rule.body?.length ?? 0,
              annotations: rule.annotations,
            });
          }
          const rules = [...seen.values()];
  
          return ok<RegoDescribePolicyOutput>({
            package: packageName,
            imports,
            ruleCount: rules.length,
            rules,
            packageAnnotations: ast.annotations,
          });
        });
      },
    );
  }

• src/tools/helpers/describe-policy.ts:14-16 (schema)

  Input schema for the tool: a single 'source' string field (Rego source) validated with Zod.

  const RegoDescribePolicyInput = {
    source: z.string().min(1).describe('Rego source to describe.'),
  };

• src/tools/helpers/describe-policy.ts:58-64 (schema)

  Output type definition (RegoDescribePolicyOutput) containing package name, imports list, rule count, rule details, and package-level annotations.

  export interface RegoDescribePolicyOutput {
    package: string;
    imports: string[];
    ruleCount: number;
    rules: DescribedRule[];
    packageAnnotations?: AstAnnotations[];
  }

• src/tools/helpers/index.ts:17-22 (registration)

  Registration bridge: 'registerHelperTools' calls 'registerRegoDescribePolicy(server, config)' to wire the tool into the MCP server.

  export function registerHelperTools(server: McpServer, config: Config): void {
    registerRegoExplainDecision(server, config);
    registerRegoGenerateTestSkeleton(server, config);
    registerRegoDescribePolicy(server, config);
    registerRegoSuggestFix(server, config);
  }

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

  Top-level registration entry point: 'registerTools' calls 'registerHelperTools' which ultimately registers rego_describe_policy.

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