jfrog_execute_aql_query
Execute Artifactory Query Language (AQL) queries to search for artifacts, builds, or entities in JFrog Artifactory. Supports complex criteria, sorting, and pagination for precise artifact discovery.
Instructions
Execute an Artifactory Query Language (AQL) query to search for artifacts, builds, or other entities in JFrog Artifactory. AQL is a powerful query language for searching and filtering artifacts in Artifactory repositories. It supports complex criteria, sorting, pagination, and more.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| domain | No | The primary domain to search in. If not specified, it will be extracted from the query. | |
| include_fields | No | Fields to include in the results | |
| limit | No | Maximum number of results to return | |
| offset | No | Number of results to skip | |
| query | Yes | The AQL query to execute. Must follow AQL syntax (e.g., items.find({"repo":"my-repo"}).include("name","path")) | |
| sort_by | No | Field to sort results by | |
| sort_order | No | Sort order | asc |
| transitive | No | Whether to search in remote repositories |
Implementation Reference
- tools/aql.ts:76-91 (handler)The handler function for the 'jfrog_execute_aql_query' tool. Parses input args with schema, executes the AQL query via helper, and returns JSON-formatted results as MCP content.handler: async (args: any) => { const parsedArgs = aqlSchemas.AQLSearchSchema.parse(args); const results = await executeAQLQuery(args.query, { transitive: parsedArgs.transitive, domain: parsedArgs.domain, limit: parsedArgs.limit, offset: parsedArgs.offset, include_fields: parsedArgs.include_fields, sort_by: parsedArgs.sort_by, sort_order: parsedArgs.sort_order }); return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }], }; }
- schemas/aql.ts:4-14 (schema)Input schema (AQLSearchSchema) used for validating tool arguments, defining query and various AQL options.export const AQLSearchSchema = z.object({ query: z.string().describe("The AQL query to execute. Must follow AQL syntax (e.g., items.find({\"repo\":\"my-repo\"}).include(\"name\",\"path\"))"), transitive: z.boolean().optional().default(false).describe("Whether to search in remote repositories"), domain: z.enum(["items", "builds", "archive.entries", "build.promotions", "releases"]).optional() .describe("The primary domain to search in. If not specified, it will be extracted from the query."), limit: z.number().default(50).describe("Maximum number of results to return"), offset: z.number().optional().describe("Number of results to skip"), include_fields: z.array(z.string()).optional().describe("Fields to include in the results"), sort_by: z.string().optional().describe("Field to sort results by"), sort_order: z.enum(["asc", "desc"]).optional().default("asc").describe("Sort order") });
- tools/aql.ts:12-67 (helper)Helper function that builds the full AQL query string from base query and options, sends it to Artifactory API via jfrogRequest, and parses the response.export async function executeAQLQuery( query: string, options: { transitive?: boolean; domain?: string; limit?: number; offset?: number; include_fields?: string[]; sort_by?: string; sort_order?: "asc" | "desc"; } = {} ): Promise<any> { let aqlQuery = query; // If the query doesn't already have a domain specified, add it if (options.domain && !aqlQuery.includes(".find(")) { aqlQuery = `${options.domain}.find(${aqlQuery})`; } // Add include fields if specified if (options.include_fields && options.include_fields.length > 0 && !aqlQuery.includes(".include(")) { const includeFields = options.include_fields.map(field => `"${field}"`).join(","); aqlQuery = `${aqlQuery}.include(${includeFields})`; } // Add sorting if specified if (options.sort_by && !aqlQuery.includes(".sort(")) { const sortOrder = options.sort_order || "asc"; aqlQuery = `${aqlQuery}.sort({"$${sortOrder}":["${options.sort_by}"]})`; } // Add limit if specified if (options.limit && !aqlQuery.includes(".limit(")) { aqlQuery = `${aqlQuery}.limit(${options.limit})`; } // Add offset if specified if (options.offset && !aqlQuery.includes(".offset(")) { aqlQuery = `${aqlQuery}.offset(${options.offset})`; } // Add transitive if specified if (options.transitive) { aqlQuery = `${aqlQuery}.transitive()`; } const response = await jfrogRequest("/artifactory/api/search/aql", { method: "POST", body: aqlQuery, headers: { "Content-Type": "text/plain" } }); return aqlSchemas.AQLSearchResponseSchema.parse(response); }
- tools/aql.ts:71-98 (registration)Local tool registration: defines the tool object with name, description, inputSchema reference, and handler; exported as AQLTools array.const executeAQLQueryTool = { name: "jfrog_execute_aql_query", description: "Execute an Artifactory Query Language (AQL) query to search for artifacts, builds, or other entities in JFrog Artifactory. AQL is a powerful query language for searching and filtering artifacts in Artifactory repositories. It supports complex criteria, sorting, pagination, and more.", inputSchema: zodToJsonSchema(aqlSchemas.AQLSearchSchema), //outputSchema: zodToJsonSchema(aqlSchemas.AQLSearchResponseSchema), handler: async (args: any) => { const parsedArgs = aqlSchemas.AQLSearchSchema.parse(args); const results = await executeAQLQuery(args.query, { transitive: parsedArgs.transitive, domain: parsedArgs.domain, limit: parsedArgs.limit, offset: parsedArgs.offset, include_fields: parsedArgs.include_fields, sort_by: parsedArgs.sort_by, sort_order: parsedArgs.sort_order }); return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }], }; } }; /* End of Tools creation Section */ export const AQLTools = [ executeAQLQueryTool ];
- tools/index.ts:13-23 (registration)Global tool registration: spreads AQLTools (containing jfrog_execute_aql_query) into the main exported tools array.export const tools =[ ...RepositoryTools, ...BuildsTools, ...RuntimeTools, ...AccessTools, ...AQLTools, ...CatalogTools, ...CurationTools, ...PermissionsTools, ...ArtifactSecurityTools, ];