webmcp-cli 1.0.0 → 1.2.1

package/dist/llm/types.d.ts

@@ -0,0 +1,233 @@
+/**
+ * LLM Types
+ *
+ * Type definitions for LLM-based rule evaluation.
+ */
+import type { DetectedTool } from '../core/types/tool.js';
+/**
+ * LLM Provider configuration
+ */
+export interface LLMConfig {
+    /**
+     * API key for the LLM provider
+     */
+    apiKey: string;
+    /**
+     * Model identifier (e.g., 'anthropic/claude-sonnet-4.5')
+     */
+    model: string;
+    /**
+     * Base URL for the API (e.g., OpenRouter endpoint)
+     */
+    baseUrl?: string;
+    /**
+     * Temperature for generation (0-1)
+     */
+    temperature?: number;
+    /**
+     * Maximum tokens to generate
+     */
+    maxTokens?: number;
+}
+/**
+ * Context provided to LLM for evaluation
+ */
+export interface EvaluationContext {
+    /**
+     * The tool being evaluated
+     */
+    tool: DetectedTool;
+    /**
+     * The specific question/prompt for evaluation
+     */
+    question: string;
+    /**
+     * Evaluation criteria to check
+     */
+    criteria: string[];
+    /**
+     * Additional context (e.g., other tools on the page)
+     */
+    additionalContext?: string;
+}
+/**
+ * Result from LLM evaluation
+ */
+export interface EvaluationResult {
+    /**
+     * Whether the evaluation passed
+     */
+    passed: boolean;
+    /**
+     * Score from 0-10
+     */
+    score: number;
+    /**
+     * LLM's reasoning for the evaluation
+     */
+    reasoning: string;
+    /**
+     * Specific issues found
+     */
+    issues?: string[];
+    /**
+     * Suggestions for improvement
+     */
+    suggestions?: string[];
+    /**
+     * Raw LLM response (for debugging)
+     */
+    rawResponse?: string;
+    /**
+     * Whether this result came from cache
+     */
+    cached?: boolean;
+}
+/**
+ * Description quality evaluation context
+ */
+export interface DescriptionEvalContext {
+    /**
+     * Tool name
+     */
+    name: string;
+    /**
+     * Tool description
+     */
+    description: string;
+    /**
+     * Input schema (stringified)
+     */
+    inputSchema?: string;
+    /**
+     * What aspect to evaluate
+     */
+    aspect: 'clarity' | 'specificity' | 'positive-framing' | 'completeness' | 'steering' | 'atomicity' | 'similarity' | 'all';
+}
+/**
+ * Full description quality report
+ */
+export interface DescriptionQualityReport {
+    /**
+     * Overall quality score (0-100)
+     */
+    overallScore: number;
+    /**
+     * Individual aspect scores
+     */
+    aspects: {
+        clarity: EvaluationResult;
+        specificity: EvaluationResult;
+        positiveFraming: EvaluationResult;
+        completeness: EvaluationResult;
+        steeringPerformance: EvaluationResult;
+        atomicity: EvaluationResult;
+    };
+    /**
+     * Overall assessment
+     */
+    summary: string;
+    /**
+     * Top priority improvements
+     */
+    priorityImprovements: string[];
+    /**
+     * Suggested rewritten description
+     */
+    suggestedDescription?: string;
+}
+/**
+ * LLM Provider interface
+ */
+export interface LLMProvider {
+    /**
+     * Provider name
+     */
+    name: string;
+    /**
+     * Send a prompt and get a response
+     */
+    complete(prompt: string, systemPrompt?: string): Promise<string>;
+    /**
+     * Evaluate a tool description
+     */
+    evaluateDescription(context: DescriptionEvalContext): Promise<EvaluationResult>;
+    /**
+     * Get a full quality report for a tool
+     */
+    getQualityReport(tool: DetectedTool): Promise<DescriptionQualityReport>;
+    /**
+     * Check if the provider is available (has valid credentials)
+     */
+    isAvailable(): boolean;
+}
+export interface EvaluationCacheEntry {
+    kind: 'evaluation';
+    result: EvaluationResult;
+    timestamp: number;
+    inputHash: string;
+}
+export interface ReportCacheEntry {
+    kind: 'report';
+    result: DescriptionQualityReport;
+    timestamp: number;
+    inputHash: string;
+}
+/**
+ * Cache entry for LLM evaluations/reports.
+ */
+export type CacheEntry = EvaluationCacheEntry | ReportCacheEntry;
+/**
+ * Cache storage structure
+ */
+export interface LLMCache {
+    /**
+     * Version for cache invalidation
+     */
+    version: number;
+    /**
+     * Cached entries by key
+     */
+    entries: Record<string, CacheEntry>;
+}
+/**
+ * Evaluation types for different rules
+ */
+export type EvaluationType = 'desc-specific-verb' | 'desc-positive-framing' | 'desc-explains-what' | 'desc-explains-when' | 'bp-atomic-tool' | 'steering-quality' | 'instruction-similarity' | 'param-clarity' | 'full-quality';
+/**
+ * LLM-generated smart advice for a finding
+ */
+export interface SmartAdvice {
+    currentState: {
+        description: string;
+        problemAreas: string[];
+        agentImpact: string;
+    };
+    enhanced: {
+        suggestedFix: string;
+        explanation: string;
+        codeExample?: string;
+    };
+    benefits: {
+        title: string;
+        items: string[];
+    };
+    confidence: number;
+    cached?: boolean;
+}
+/**
+ * Finding with optional smart advice attached
+ */
+export interface FindingWithAdvice {
+    id: string;
+    ruleId: string;
+    severity: 'critical' | 'warning' | 'info';
+    message: string;
+    tool?: string;
+    page?: string;
+    fix?: string;
+    scoreImpact?: number;
+    advice?: SmartAdvice;
+    adviceLoading?: boolean;
+    adviceError?: string;
+}

package/dist/llm/types.js

@@ -0,0 +1,7 @@
+/**
+ * LLM Types
+ *
+ * Type definitions for LLM-based rule evaluation.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/llm/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/llm/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/rules/best-practices/BP-001.d.ts

@@ -0,0 +1,11 @@
+/**
+ * BP-001: Annotations Present
+ *
+ * Checks if tools have an annotations object defined.
+ * Annotations provide important hints about tool behavior
+ * (readOnlyHint, destructiveHint, etc.) that help agents
+ * make better decisions.
+ */
+import type { Rule } from '../../core/types/rule.js';
+export declare const BP_001: Rule;
+export default BP_001;

package/dist/rules/best-practices/BP-001.js

@@ -0,0 +1,56 @@
+/**
+ * BP-001: Annotations Present
+ *
+ * Checks if tools have an annotations object defined.
+ * Annotations provide important hints about tool behavior
+ * (readOnlyHint, destructiveHint, etc.) that help agents
+ * make better decisions.
+ */
+import { createRuleResult } from '../runner.js';
+export const BP_001 = {
+    id: 'BP-001',
+    category: 'best-practices',
+    name: 'Annotations Present',
+    description: 'Tools should have an annotations object for behavior hints',
+    severity: 'info',
+    maxScore: 5,
+    async check(context) {
+        const tools = context.tools;
+        if (tools.length === 0) {
+            return createRuleResult('BP-001', 5, {
+                passed: true,
+                score: 5,
+                message: 'No tools detected (rule not applicable)',
+            });
+        }
+        const toolsWithoutAnnotations = [];
+        for (const tool of tools) {
+            if (!tool.annotations || Object.keys(tool.annotations).length === 0) {
+                toolsWithoutAnnotations.push(tool.name);
+            }
+        }
+        if (toolsWithoutAnnotations.length === 0) {
+            return createRuleResult('BP-001', 5, {
+                passed: true,
+                score: 5,
+                message: `All ${tools.length} tool(s) have annotations defined`,
+            });
+        }
+        // Deduct 1 point per tool missing annotations, minimum 0
+        const penalty = Math.min(toolsWithoutAnnotations.length, 5);
+        const score = Math.max(0, 5 - penalty);
+        return createRuleResult('BP-001', 5, {
+            passed: false,
+            score,
+            message: `${toolsWithoutAnnotations.length} tool(s) missing annotations`,
+            details: toolsWithoutAnnotations.map((name) => `Tool "${name}" has no annotations object`),
+            suggestions: [
+                'Add annotations object with readOnlyHint, destructiveHint, etc.',
+                'Example: { annotations: { readOnlyHint: true } }',
+            ],
+            affectedTools: toolsWithoutAnnotations,
+        });
+    },
+};
+export default BP_001;
+//# sourceMappingURL=BP-001.js.map

package/dist/rules/best-practices/BP-001.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BP-001.js","sourceRoot":"","sources":["../../../src/rules/best-practices/BP-001.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,MAAM,CAAC,MAAM,MAAM,GAAS;IAC1B,EAAE,EAAE,QAAQ;IACZ,QAAQ,EAAE,gBAAgB;IAC1B,IAAI,EAAE,qBAAqB;IAC3B,WAAW,EAAE,4DAA4D;IACzE,QAAQ,EAAE,MAAM;IAChB,QAAQ,EAAE,CAAC;IAEX,KAAK,CAAC,KAAK,CAAC,OAAoB;QAC9B,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAE5B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,OAAO,gBAAgB,CAAC,QAAQ,EAAE,CAAC,EAAE;gBACnC,MAAM,EAAE,IAAI;gBACZ,KAAK,EAAE,CAAC;gBACR,OAAO,EAAE,yCAAyC;aACnD,CAAC,CAAC;QACL,CAAC;QAED,MAAM,uBAAuB,GAAa,EAAE,CAAC;QAE7C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,CAAC,IAAI,CAAC,WAAW,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACpE,uBAAuB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC1C,CAAC;QACH,CAAC;QAED,IAAI,uBAAuB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzC,OAAO,gBAAgB,CAAC,QAAQ,EAAE,CAAC,EAAE;gBACnC,MAAM,EAAE,IAAI;gBACZ,KAAK,EAAE,CAAC;gBACR,OAAO,EAAE,OAAO,KAAK,CAAC,MAAM,mCAAmC;aAChE,CAAC,CAAC;QACL,CAAC;QAED,yDAAyD;QACzD,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,uBAAuB,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;QAC5D,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC;QAEvC,OAAO,gBAAgB,CAAC,QAAQ,EAAE,CAAC,EAAE;YACnC,MAAM,EAAE,KAAK;YACb,KAAK;YACL,OAAO,EAAE,GAAG,uBAAuB,CAAC,MAAM,8BAA8B;YACxE,OAAO,EAAE,uBAAuB,CAAC,GAAG,CAClC,CAAC,IAAI,EAAE,EAAE,CAAC,SAAS,IAAI,6BAA6B,CACrD;YACD,WAAW,EAAE;gBACX,iEAAiE;gBACjE,kDAAkD;aACnD;YACD,aAAa,EAAE,uBAAuB;SACvC,CAAC,CAAC;IACL,CAAC;CACF,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/dist/rules/best-practices/BP-002.d.ts

@@ -0,0 +1,11 @@
+/**
+ * BP-002: Destructive Hint Used
+ *
+ * Checks if tools with destructive-sounding names/descriptions
+ * have the destructiveHint annotation set to true.
+ *
+ * Destructive operations include: delete, remove, purchase, cancel, etc.
+ */
+import type { Rule } from '../../core/types/rule.js';
+export declare const BP_002: Rule;
+export default BP_002;

package/dist/rules/best-practices/BP-002.js

@@ -0,0 +1,63 @@
+/**
+ * BP-002: Destructive Hint Used
+ *
+ * Checks if tools with destructive-sounding names/descriptions
+ * have the destructiveHint annotation set to true.
+ *
+ * Destructive operations include: delete, remove, purchase, cancel, etc.
+ */
+import { createRuleResult } from '../runner.js';
+import { DESTRUCTIVE_KEYWORDS, hasKeyword, findMatchedKeywords, } from '../utils/keywords.js';
+export const BP_002 = {
+    id: 'BP-002',
+    category: 'best-practices',
+    name: 'Destructive Hint Used',
+    description: 'Tools with destructive operations should have destructiveHint: true',
+    severity: 'warning',
+    maxScore: 8,
+    async check(context) {
+        const tools = context.tools;
+        if (tools.length === 0) {
+            return createRuleResult('BP-002', 8, {
+                passed: true,
+                score: 8,
+                message: 'No tools detected (rule not applicable)',
+            });
+        }
+        const violations = [];
+        for (const tool of tools) {
+            const textToSearch = `${tool.name} ${tool.description}`;
+            if (hasKeyword(textToSearch, DESTRUCTIVE_KEYWORDS)) {
+                // Check if destructiveHint is set
+                const hasDestructiveHint = tool.annotations?.destructiveHint === true;
+                if (!hasDestructiveHint) {
+                    const matchedKeywords = findMatchedKeywords(textToSearch, DESTRUCTIVE_KEYWORDS);
+                    violations.push({ name: tool.name, keywords: matchedKeywords });
+                }
+            }
+        }
+        if (violations.length === 0) {
+            return createRuleResult('BP-002', 8, {
+                passed: true,
+                score: 8,
+                message: 'All destructive-looking tools have destructiveHint annotation',
+            });
+        }
+        // Deduct 2 points per violation
+        const penalty = violations.length * 2;
+        const score = Math.max(0, 8 - penalty);
+        return createRuleResult('BP-002', 8, {
+            passed: false,
+            score,
+            message: `${violations.length} tool(s) with destructive keywords missing destructiveHint`,
+            details: violations.map((v) => `Tool "${v.name}" contains keywords [${v.keywords.join(', ')}] but lacks destructiveHint: true`),
+            suggestions: [
+                'Add destructiveHint: true to annotations for tools that modify/delete data',
+                'Example: { annotations: { destructiveHint: true } }',
+            ],
+            affectedTools: violations.map((v) => v.name),
+        });
+    },
+};
+export default BP_002;
+//# sourceMappingURL=BP-002.js.map

package/dist/rules/best-practices/BP-002.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BP-002.js","sourceRoot":"","sources":["../../../src/rules/best-practices/BP-002.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EACL,oBAAoB,EACpB,UAAU,EACV,mBAAmB,GACpB,MAAM,sBAAsB,CAAC;AAE9B,MAAM,CAAC,MAAM,MAAM,GAAS;IAC1B,EAAE,EAAE,QAAQ;IACZ,QAAQ,EAAE,gBAAgB;IAC1B,IAAI,EAAE,uBAAuB;IAC7B,WAAW,EAAE,qEAAqE;IAClF,QAAQ,EAAE,SAAS;IACnB,QAAQ,EAAE,CAAC;IAEX,KAAK,CAAC,KAAK,CAAC,OAAoB;QAC9B,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAE5B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,OAAO,gBAAgB,CAAC,QAAQ,EAAE,CAAC,EAAE;gBACnC,MAAM,EAAE,IAAI;gBACZ,KAAK,EAAE,CAAC;gBACR,OAAO,EAAE,yCAAyC;aACnD,CAAC,CAAC;QACL,CAAC;QAED,MAAM,UAAU,GAA2C,EAAE,CAAC;QAE9D,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,YAAY,GAAG,GAAG,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YAExD,IAAI,UAAU,CAAC,YAAY,EAAE,oBAAoB,CAAC,EAAE,CAAC;gBACnD,kCAAkC;gBAClC,MAAM,kBAAkB,GAAG,IAAI,CAAC,WAAW,EAAE,eAAe,KAAK,IAAI,CAAC;gBAEtE,IAAI,CAAC,kBAAkB,EAAE,CAAC;oBACxB,MAAM,eAAe,GAAG,mBAAmB,CACzC,YAAY,EACZ,oBAAoB,CACrB,CAAC;oBACF,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,eAAe,EAAE,CAAC,CAAC;gBAClE,CAAC;YACH,CAAC;QACH,CAAC;QAED,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,OAAO,gBAAgB,CAAC,QAAQ,EAAE,CAAC,EAAE;gBACnC,MAAM,EAAE,IAAI;gBACZ,KAAK,EAAE,CAAC;gBACR,OAAO,EAAE,+DAA+D;aACzE,CAAC,CAAC;QACL,CAAC;QAED,gCAAgC;QAChC,MAAM,OAAO,GAAG,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC;QACtC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC;QAEvC,OAAO,gBAAgB,CAAC,QAAQ,EAAE,CAAC,EAAE;YACnC,MAAM,EAAE,KAAK;YACb,KAAK;YACL,OAAO,EAAE,GAAG,UAAU,CAAC,MAAM,4DAA4D;YACzF,OAAO,EAAE,UAAU,CAAC,GAAG,CACrB,CAAC,CAAC,EAAE,EAAE,CACJ,SAAS,CAAC,CAAC,IAAI,wBAAwB,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,mCAAmC,CAClG;YACD,WAAW,EAAE;gBACX,4EAA4E;gBAC5E,qDAAqD;aACtD;YACD,aAAa,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;SAC7C,CAAC,CAAC;IACL,CAAC;CACF,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/dist/rules/best-practices/BP-003.d.ts

@@ -0,0 +1,11 @@
+/**
+ * BP-003: ReadOnly Hint Consistency
+ *
+ * Checks if tools with read-only-sounding names/descriptions
+ * have the readOnlyHint annotation set to true.
+ *
+ * Read-only operations include: get, search, list, fetch, view, etc.
+ */
+import type { Rule } from '../../core/types/rule.js';
+export declare const BP_003: Rule;
+export default BP_003;

package/dist/rules/best-practices/BP-003.js

@@ -0,0 +1,68 @@
+/**
+ * BP-003: ReadOnly Hint Consistency
+ *
+ * Checks if tools with read-only-sounding names/descriptions
+ * have the readOnlyHint annotation set to true.
+ *
+ * Read-only operations include: get, search, list, fetch, view, etc.
+ */
+import { createRuleResult } from '../runner.js';
+import { READONLY_KEYWORDS, DESTRUCTIVE_KEYWORDS, hasKeyword, findMatchedKeywords, } from '../utils/keywords.js';
+export const BP_003 = {
+    id: 'BP-003',
+    category: 'best-practices',
+    name: 'ReadOnly Hint Consistency',
+    description: 'Tools with read-only operations should have readOnlyHint: true',
+    severity: 'info',
+    maxScore: 5,
+    async check(context) {
+        const tools = context.tools;
+        if (tools.length === 0) {
+            return createRuleResult('BP-003', 5, {
+                passed: true,
+                score: 5,
+                message: 'No tools detected (rule not applicable)',
+            });
+        }
+        const violations = [];
+        for (const tool of tools) {
+            const textToSearch = `${tool.name} ${tool.description}`;
+            // Check if tool looks read-only
+            if (hasKeyword(textToSearch, READONLY_KEYWORDS)) {
+                // Skip if it also has destructive keywords (ambiguous)
+                if (hasKeyword(textToSearch, DESTRUCTIVE_KEYWORDS)) {
+                    continue;
+                }
+                // Check if readOnlyHint is set
+                const hasReadOnlyHint = tool.annotations?.readOnlyHint === true;
+                if (!hasReadOnlyHint) {
+                    const matchedKeywords = findMatchedKeywords(textToSearch, READONLY_KEYWORDS);
+                    violations.push({ name: tool.name, keywords: matchedKeywords });
+                }
+            }
+        }
+        if (violations.length === 0) {
+            return createRuleResult('BP-003', 5, {
+                passed: true,
+                score: 5,
+                message: 'All read-only-looking tools have readOnlyHint annotation',
+            });
+        }
+        // Deduct 1 point per violation
+        const penalty = Math.min(violations.length, 5);
+        const score = Math.max(0, 5 - penalty);
+        return createRuleResult('BP-003', 5, {
+            passed: false,
+            score,
+            message: `${violations.length} tool(s) with read-only keywords missing readOnlyHint`,
+            details: violations.map((v) => `Tool "${v.name}" contains keywords [${v.keywords.join(', ')}] but lacks readOnlyHint: true`),
+            suggestions: [
+                'Add readOnlyHint: true to annotations for tools that only read data',
+                'Example: { annotations: { readOnlyHint: true } }',
+            ],
+            affectedTools: violations.map((v) => v.name),
+        });
+    },
+};
+export default BP_003;
+//# sourceMappingURL=BP-003.js.map

package/dist/rules/best-practices/BP-003.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BP-003.js","sourceRoot":"","sources":["../../../src/rules/best-practices/BP-003.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,UAAU,EACV,mBAAmB,GACpB,MAAM,sBAAsB,CAAC;AAE9B,MAAM,CAAC,MAAM,MAAM,GAAS;IAC1B,EAAE,EAAE,QAAQ;IACZ,QAAQ,EAAE,gBAAgB;IAC1B,IAAI,EAAE,2BAA2B;IACjC,WAAW,EAAE,gEAAgE;IAC7E,QAAQ,EAAE,MAAM;IAChB,QAAQ,EAAE,CAAC;IAEX,KAAK,CAAC,KAAK,CAAC,OAAoB;QAC9B,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAE5B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,OAAO,gBAAgB,CAAC,QAAQ,EAAE,CAAC,EAAE;gBACnC,MAAM,EAAE,IAAI;gBACZ,KAAK,EAAE,CAAC;gBACR,OAAO,EAAE,yCAAyC;aACnD,CAAC,CAAC;QACL,CAAC;QAED,MAAM,UAAU,GAA2C,EAAE,CAAC;QAE9D,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,YAAY,GAAG,GAAG,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YAExD,gCAAgC;YAChC,IAAI,UAAU,CAAC,YAAY,EAAE,iBAAiB,CAAC,EAAE,CAAC;gBAChD,uDAAuD;gBACvD,IAAI,UAAU,CAAC,YAAY,EAAE,oBAAoB,CAAC,EAAE,CAAC;oBACnD,SAAS;gBACX,CAAC;gBAED,+BAA+B;gBAC/B,MAAM,eAAe,GAAG,IAAI,CAAC,WAAW,EAAE,YAAY,KAAK,IAAI,CAAC;gBAEhE,IAAI,CAAC,eAAe,EAAE,CAAC;oBACrB,MAAM,eAAe,GAAG,mBAAmB,CACzC,YAAY,EACZ,iBAAiB,CAClB,CAAC;oBACF,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,eAAe,EAAE,CAAC,CAAC;gBAClE,CAAC;YACH,CAAC;QACH,CAAC;QAED,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,OAAO,gBAAgB,CAAC,QAAQ,EAAE,CAAC,EAAE;gBACnC,MAAM,EAAE,IAAI;gBACZ,KAAK,EAAE,CAAC;gBACR,OAAO,EAAE,0DAA0D;aACpE,CAAC,CAAC;QACL,CAAC;QAED,+BAA+B;QAC/B,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;QAC/C,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC;QAEvC,OAAO,gBAAgB,CAAC,QAAQ,EAAE,CAAC,EAAE;YACnC,MAAM,EAAE,KAAK;YACb,KAAK;YACL,OAAO,EAAE,GAAG,UAAU,CAAC,MAAM,uDAAuD;YACpF,OAAO,EAAE,UAAU,CAAC,GAAG,CACrB,CAAC,CAAC,EAAE,EAAE,CACJ,SAAS,CAAC,CAAC,IAAI,wBAAwB,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,gCAAgC,CAC/F;YACD,WAAW,EAAE;gBACX,qEAAqE;gBACrE,kDAAkD;aACnD;YACD,aAAa,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;SAC7C,CAAC,CAAC;IACL,CAAC;CACF,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/dist/rules/coverage/COV-001.d.ts

@@ -0,0 +1,8 @@
+/**
+ * COV-001: Form Coverage
+ *
+ * Checks if all interactive forms on the page are exposed as MCP tools.
+ * Unregistered forms represent missed opportunities for tool coverage.
+ */
+import type { Rule } from '../../core/types/rule.js';
+export declare const COV_001: Rule;

package/dist/rules/coverage/COV-001.js

@@ -0,0 +1,51 @@
+/**
+ * COV-001: Form Coverage
+ *
+ * Checks if all interactive forms on the page are exposed as MCP tools.
+ * Unregistered forms represent missed opportunities for tool coverage.
+ */
+import { createRuleResult } from '../runner.js';
+export const COV_001 = {
+    id: 'COV-001',
+    category: 'coverage',
+    name: 'Form Coverage',
+    description: 'All interactive forms should be exposed as MCP tools',
+    severity: 'warning',
+    maxScore: 5,
+    async check(context) {
+        const { tools, opportunities } = context;
+        if (tools.length === 0 && opportunities.length === 0) {
+            return createRuleResult('COV-001', 5, {
+                passed: true,
+                score: 5,
+                message: 'No tools or forms detected (rule not applicable)',
+            });
+        }
+        if (opportunities.length === 0) {
+            return createRuleResult('COV-001', 5, {
+                passed: true,
+                score: 5,
+                message: 'All detected forms are covered by MCP tools',
+            });
+        }
+        const totalForms = tools.length + opportunities.length;
+        const coverageRatio = tools.length / totalForms;
+        const score = Math.round(coverageRatio * 5);
+        const passed = opportunities.length === 0;
+        const uncoveredNames = opportunities.map((o) => o.contextClues.submitText ||
+            o.contextClues.ariaLabel ||
+            o.contextClues.formId ||
+            o.contextClues.formAction ||
+            'unnamed form');
+        return createRuleResult('COV-001', 5, {
+            passed,
+            score,
+            message: `${tools.length}/${totalForms} forms covered (${Math.round(coverageRatio * 100)}%)`,
+            details: uncoveredNames.map((n) => `Uncovered form: ${n}`),
+            suggestions: opportunities.length > 0
+                ? ['Register uncovered forms as MCP tools to improve coverage']
+                : undefined,
+        });
+    },
+};
+//# sourceMappingURL=COV-001.js.map

package/dist/rules/coverage/COV-001.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"COV-001.js","sourceRoot":"","sources":["../../../src/rules/coverage/COV-001.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,MAAM,CAAC,MAAM,OAAO,GAAS;IAC3B,EAAE,EAAE,SAAS;IACb,QAAQ,EAAE,UAAU;IACpB,IAAI,EAAE,eAAe;IACrB,WAAW,EAAE,sDAAsD;IACnE,QAAQ,EAAE,SAAS;IACnB,QAAQ,EAAE,CAAC;IAEX,KAAK,CAAC,KAAK,CAAC,OAAoB;QAC9B,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC;QAEzC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACrD,OAAO,gBAAgB,CAAC,SAAS,EAAE,CAAC,EAAE;gBACpC,MAAM,EAAE,IAAI;gBACZ,KAAK,EAAE,CAAC;gBACR,OAAO,EAAE,kDAAkD;aAC5D,CAAC,CAAC;QACL,CAAC;QAED,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC/B,OAAO,gBAAgB,CAAC,SAAS,EAAE,CAAC,EAAE;gBACpC,MAAM,EAAE,IAAI;gBACZ,KAAK,EAAE,CAAC;gBACR,OAAO,EAAE,6CAA6C;aACvD,CAAC,CAAC;QACL,CAAC;QAED,MAAM,UAAU,GAAG,KAAK,CAAC,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC;QACvD,MAAM,aAAa,GAAG,KAAK,CAAC,MAAM,GAAG,UAAU,CAAC;QAChD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,aAAa,GAAG,CAAC,CAAC,CAAC;QAC5C,MAAM,MAAM,GAAG,aAAa,CAAC,MAAM,KAAK,CAAC,CAAC;QAE1C,MAAM,cAAc,GAAG,aAAa,CAAC,GAAG,CACtC,CAAC,CAAC,EAAE,EAAE,CACJ,CAAC,CAAC,YAAY,CAAC,UAAU;YACzB,CAAC,CAAC,YAAY,CAAC,SAAS;YACxB,CAAC,CAAC,YAAY,CAAC,MAAM;YACrB,CAAC,CAAC,YAAY,CAAC,UAAU;YACzB,cAAc,CACjB,CAAC;QAEF,OAAO,gBAAgB,CAAC,SAAS,EAAE,CAAC,EAAE;YACpC,MAAM;YACN,KAAK;YACL,OAAO,EAAE,GAAG,KAAK,CAAC,MAAM,IAAI,UAAU,mBAAmB,IAAI,CAAC,KAAK,CAAC,aAAa,GAAG,GAAG,CAAC,IAAI;YAC5F,OAAO,EAAE,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,mBAAmB,CAAC,EAAE,CAAC;YAC1D,WAAW,EACT,aAAa,CAAC,MAAM,GAAG,CAAC;gBACtB,CAAC,CAAC,CAAC,2DAA2D,CAAC;gBAC/D,CAAC,CAAC,SAAS;SAChB,CAAC,CAAC;IACL,CAAC;CACF,CAAC"}

package/dist/rules/description/DESC-003.d.ts

@@ -0,0 +1,13 @@
+/**
+ * DESC-003: Name Kebab Case
+ *
+ * Checks if tool names follow snake_case or kebab-case convention.
+ * Consistent naming helps agents recognize tools and improves
+ * overall API quality.
+ *
+ * Valid: search_flights, search-flights, search
+ * Invalid: searchFlights, SearchFlights
+ */
+import type { Rule } from '../../core/types/rule.js';
+export declare const DESC_003: Rule;
+export default DESC_003;

package/dist/rules/description/DESC-003.js

@@ -0,0 +1,96 @@
+/**
+ * DESC-003: Name Kebab Case
+ *
+ * Checks if tool names follow snake_case or kebab-case convention.
+ * Consistent naming helps agents recognize tools and improves
+ * overall API quality.
+ *
+ * Valid: search_flights, search-flights, search
+ * Invalid: searchFlights, SearchFlights
+ */
+import { createRuleResult } from '../runner.js';
+/**
+ * Check if a name is in valid format (snake_case, kebab-case, or single word lowercase)
+ */
+function isValidToolName(name) {
+    // Allow snake_case, kebab-case, or single lowercase word
+    // Pattern: lowercase letters, numbers, underscores, and hyphens only
+    // Must not have consecutive separators or start/end with separator
+    const validPattern = /^[a-z][a-z0-9]*([_-][a-z0-9]+)*$/;
+    return validPattern.test(name);
+}
+/**
+ * Detect the naming convention used
+ */
+function detectNamingIssue(name) {
+    if (/[A-Z]/.test(name)) {
+        if (/^[A-Z]/.test(name)) {
+            return 'PascalCase';
+        }
+        return 'camelCase';
+    }
+    if (name.includes(' ')) {
+        return 'contains spaces';
+    }
+    if (/^[_-]|[_-]$/.test(name)) {
+        return 'starts or ends with separator';
+    }
+    if (/[_-]{2,}/.test(name)) {
+        return 'consecutive separators';
+    }
+    return 'invalid format';
+}
+export const DESC_003 = {
+    id: 'DESC-003',
+    category: 'description',
+    name: 'Name Kebab Case',
+    description: 'Tool names should use snake_case or kebab-case convention',
+    severity: 'warning',
+    maxScore: 5,
+    async check(context) {
+        const tools = context.tools;
+        if (tools.length === 0) {
+            return createRuleResult('DESC-003', 5, {
+                passed: true,
+                score: 5,
+                message: 'No tools detected (rule not applicable)',
+            });
+        }
+        const violations = [];
+        for (const tool of tools) {
+            if (!tool.name)
+                continue;
+            if (!isValidToolName(tool.name)) {
+                violations.push({
+                    name: tool.name,
+                    issue: detectNamingIssue(tool.name),
+                });
+            }
+        }
+        if (violations.length === 0) {
+            return createRuleResult('DESC-003', 5, {
+                passed: true,
+                score: 5,
+                message: 'All tool names follow proper naming conventions',
+            });
+        }
+        // Deduct 1 point per violation
+        const penalty = Math.min(violations.length, 5);
+        const score = Math.max(0, 5 - penalty);
+        return createRuleResult('DESC-003', 5, {
+            passed: false,
+            score,
+            message: `${violations.length} tool(s) have naming convention issues`,
+            details: violations.map((v) => `Tool "${v.name}" uses ${v.issue}`),
+            suggestions: [
+                'Use snake_case: search_flights, get_user_profile',
+                'Or use kebab-case: search-flights, get-user-profile',
+                'Avoid camelCase or PascalCase for tool names',
+                'Consistent naming improves tool discoverability',
+            ],
+            affectedTools: violations.map((v) => v.name),
+        });
+    },
+};
+export default DESC_003;
+//# sourceMappingURL=DESC-003.js.map

package/dist/rules/description/DESC-003.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DESC-003.js","sourceRoot":"","sources":["../../../src/rules/description/DESC-003.ts"],"names":[],"mappings":"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"}