fix(ca): optimize list rule tool for output token (#351)

Author: aruntyagiTutu

packages/mcp-provider-code-analyzer/src/actions/list-rules.ts

@@ -27,8 +27,6 @@ export type ListRulesOutput = {
         engine: string
         severity: number
         tags: string[]
-        description: string
-        resources: string[]
     }[]
 };
 
@@ -82,8 +80,6 @@ export class ListRulesActionImpl implements ListRulesAction {
                 name: r.getName(),
                 engine: r.getEngineName(),
                 severity: r.getSeverityLevel(),
-                description: r.getDescription(),
-                resources: r.getResourceUrls(),
                 tags: r.getTags()
             }
         });

packages/mcp-provider-code-analyzer/src/tools/list_code_analyzer_rules.ts

@@ -30,10 +30,13 @@ const ALLOWED_SELECTOR_TOKENS_LOWER: ReadonlySet<string> = new Set<string>([
 const DESCRIPTION: string = `A tool for selecting Code Analyzer rules based on a number of criteria.\n` +
     `This tool returns a JSON array describing Code Analyzer rules that match a "selector".\n` +
     `A selector is a colon-separated (:) string of tokens; tags and severity names are case-insensitive.\n` +
+    `You can OR multiple tokens of the same type by grouping them in parentheses and separating with commas, e.g. "(Performance,Security)".\n` +
     `\n` +
     `Examples:\n` +
     `- "Recommended" → all rules tagged as Recommended.\n` +
     `- "Performance:pmd:Critical" → rules in the PMD engine with the Performance tag and Critical severity.\n` +
+    `- "pmd:(Performance,Security):2" → PMD rules with Performance OR Security tags and severity 2.\n` +
+    `- "(Apex,JavaScript):Recommended" → rules for Apex OR JavaScript languages that are Recommended.\n` +
     `- "Security:High" → rules tagged Security with High severity.\n` +
     `- "Apex:Recommended" → rules for the Apex language that are Recommended.\n` +
     `- "DevPreview" → rules marked as DevPreview.\n` +
@@ -46,7 +49,9 @@ const DESCRIPTION: string = `A tool for selecting Code Analyzer rules based on a
     `- General tags: Recommended, Custom, All\n` +
     `- Categories: BestPractices, CodeStyle, Design, Documentation, ErrorProne, Security, Performance\n` +
     `- Languages: Apex, CSS, HTML, JavaScript, TypeScript, Visualforce, XML\n` +
-    `- Engine-specific tags: DevPreview, LWC
+    `- Engine-specific tags: DevPreview, LWC\n` +
+    `\n` +
+    `Tip: Use the "describe_code_analyzer_rule" tool to get details for any listed rule.
     `;
 
 export const inputSchema = z.object({
@@ -60,9 +65,7 @@ const outputSchema = z.object({
         name: z.string().describe('The name of the rule, equivalent to the `ruleName` input property.'),
         engine: z.string().describe('The name of the engine to which the rule belongs.'),
         severity: z.number().describe('An integer between 1 and 5 indicating the severity of the rule. Lower numbers are MORE severe.'),
-        tags: z.array(z.string()).describe('An array of strings indicating tags applicable to the rule, e.g. "performance", "security", etc.'),
-        description: z.string().describe('A string describing the purpose and functionality of the rule.'),
-        resources: z.array(z.string()).describe('A possibly empty array of strings that represent links to documentation or other helpful material.')
+        tags: z.array(z.string()).describe('An array of strings indicating tags applicable to the rule, e.g. "performance", "security", etc.')
     })).optional().describe('An array of rules that matched the selector. Empty if no rules matched.')
 });
 type OutputArgsShape = typeof outputSchema.shape;
@@ -89,6 +92,25 @@ export class CodeAnalyzerListRulesMcpTool extends McpTool<InputArgsShape, Output
 
         const invalid: string[] = [];
         for (const token of rawTokens) {
+            // Support OR groups inside parentheses, e.g., (Performance,Security)
+            if (token.startsWith('(') && token.endsWith(')')) {
+                const inner = token.slice(1, -1);
+                const innerTokens = inner
+                    .split(',')
+                    .map(t => t.trim())
+                    .filter(t => t.length > 0);
+                if (innerTokens.length === 0) {
+                    invalid.push(token);
+                    continue;
+                }
+                for (const innerToken of innerTokens) {
+                    const normInner = innerToken.toLowerCase();
+                    if (!ALLOWED_SELECTOR_TOKENS_LOWER.has(normInner)) {
+                        invalid.push(innerToken);
+                    }
+                }
+                continue;
+            }
             const normalized = token.toLowerCase();
             if (!ALLOWED_SELECTOR_TOKENS_LOWER.has(normalized)) {
                 invalid.push(token);
@@ -160,7 +182,10 @@ export class CodeAnalyzerListRulesMcpTool extends McpTool<InputArgsShape, Output
             output = { status: getErrorMessage(e) }
         }
         return {
-            content: [{ type: "text", text: JSON.stringify(output)}],
+            content: [
+                { type: "text", text: `Tip: Use the "describe_code_analyzer_rule" tool to get details for any listed rule.` },
+                { type: "text", text: JSON.stringify(output)}
+            ],
             structuredContent: output
         };
     }

packages/mcp-provider-code-analyzer/test/actions/list-rules.test.ts

@@ -27,8 +27,6 @@ describe('ListRulesActionImpl', () => {
         const found = output.rules!.find(r => r.name === 'stub1RuleA' && r.engine === 'EngineThatLogsError');
         expect(found).toBeDefined();
         expect(found!.tags).toContain('Recommended');
-        expect(found!.description).toContain('Some description');
-        expect(Array.isArray(found!.resources)).toBe(true);
     });
 
     it('emits telemetry for engine selection', async () => {

packages/mcp-provider-code-analyzer/test/tools/list_code_analyzer_rules.test.ts

@@ -34,18 +34,17 @@ describe('CodeAnalyzerListRulesMcpTool', () => {
                 name: 'stub1RuleA',
                 engine: 'EngineThatLogsError',
                 severity: 5,
-                tags: ['Recommended'],
-                description: 'Some description',
-                resources: ['https://example.com/stub1RuleA']
+                tags: ['Recommended']
             }]
         };
         const tool = new CodeAnalyzerListRulesMcpTool(new StubListRulesAction(expected));
 
         const result = await tool.exec({ selector: 'Recommended' });
 
         expect(result.structuredContent).toEqual(expected);
-        const text = result.content[0]?.type === 'text' ? result.content[0].text : '';
-        expect(JSON.parse(text)).toEqual(expected);
+        const jsonItem: any = result.content.find((c: any) => c.type === 'text' && typeof c.text === 'string' && c.text.trim().startsWith('{'));
+        const jsonText: string = typeof jsonItem?.text === 'string' ? jsonItem.text : '';
+        expect(JSON.parse(jsonText)).toEqual(expected);
     });
 
     it('catches errors and returns error status', async () => {
@@ -104,4 +103,25 @@ describe('CodeAnalyzerListRulesMcpTool', () => {
         expect(result.isError).toBe(true);
         expect(result.structuredContent?.status).toContain('Invalid selector token(s): <empty>');
       });
+
+    it('validateSelector accepts OR groups in parentheses', () => {
+        const res = CodeAnalyzerListRulesMcpTool.validateSelector('pmd:(Performance,Security):2');
+        expect(res.valid).toBe(true);
+    });
+
+    it('validateSelector rejects empty OR group', () => {
+        const res = CodeAnalyzerListRulesMcpTool.validateSelector('pmd:()');
+        expect(res.valid).toBe(false);
+        if (res.valid === false) {
+            expect(res.invalidTokens).toContain('()');
+        }
+    });
+
+    it('validateSelector rejects group with unknown token', () => {
+        const res = CodeAnalyzerListRulesMcpTool.validateSelector('pmd:(Performance,NotATag):2');
+        expect(res.valid).toBe(false);
+        if (res.valid === false) {
+            expect(res.invalidTokens).toContain('NotATag');
+        }
+    });
 });