fix: Clarify path-filters parameter logic and syntax

anrgct · anrgct · commit 5011e4bf57ca · 2025-12-23T16:35:11.000+08:00
diff --git a/src/cli.ts b/src/cli.ts
@@ -337,21 +337,18 @@ Options:
   --cache <path>                Custom cache path
   --json                        Output results in JSON format
   --path-filters, -f <filters>   Filter search results by path patterns (comma-separated)
-                                Top-level comma-separated patterns use OR logic.
-                                Within each pattern, all substrings must match (AND logic).
-                                Supports limited glob syntax compiled to Qdrant filters:
-                                  -f "src/**/*.ts"                # All .ts files in src
-                                  -f "components/*.tsx"           # All .tsx in components
+                                Logic:
+                                - Include patterns (no ! prefix): OR logic - matches ANY pattern
+                                - Exclude patterns (! prefix): AND logic - applied globally to exclude ALL matches
+                                - Within each pattern: case-insensitive substring matching, order-independent
+                                Supported: ** (recursive), * (single-level), {a,b} (braces), !prefix (exclude)
+                                Examples:
+                                  -f "src/**/*.ts"                # src tree only
+                                  -f "components/*.tsx"           # all .tsx in components
                                   -f "{src,lib}/**/*.js"          # .js files in multiple dirs
-                                  -f "!.md,!.txt"                 # Exclude markdown/text files
-                                  -f "src/**/*.ts,lib/**/*.ts"    # OR logic: either src or lib .ts files
-                                Supported syntax:
-                                  **  Recursive directories (e.g., src/**/*)
-                                  *   Single level wildcard (e.g., src/*)
-                                  {a,b}  Brace expansion for OR (e.g., {src,lib})
-                                  !   Exclusion prefix (e.g., !*.test.ts)
-                                Note: Uses substring matching, case-insensitive.
-                                Unsupported features ([]) are ignored, ? is treated as a regular character.
+                                  -f "!.md,!.txt"                 # exclude markdown/text files
+                                  -f "src/**/*.ts,lib/**/*.ts"    # src OR lib .ts files
+                                  -f "**/*.ts,!**/*.test.ts"      # all .ts excluding tests
   --limit, -l <number>           Maximum number of search results (default: from config, max 50)
                                 Examples: --limit=30, -l 20
   --min-score, -s <number>       Minimum similarity score for search results (0-1, default: from config)
diff --git a/src/examples/debug-qdrant-query.js b/src/examples/debug-qdrant-query.js
diff --git a/src/mcp/http-server.ts b/src/mcp/http-server.ts
@@ -56,12 +56,23 @@ export class CodebaseHTTPMCPServer {
                 ]).optional()
                 .describe('Maximum number of results to return (default from config, max 50)'),
                 filters: z.object({
-                    pathFilters: z.array(z.string()).optional().describe("Filter by path patterns with limited glob support. " +
-                        "Top-level patterns (array elements) use OR logic. Within each pattern, all substrings must match (AND logic). " +
-                        "Supports: ** (recursive), * (single level), {a,b} (brace expansion), ! (exclusion). " +
-                        "Use ! prefix for exclusion. Compiled to Qdrant substring filters (case-insensitive, not strict glob matching). " +
-                        "Examples: ['src/**/*.ts', 'components/*.tsx', '!**/*.test.ts']. " +
-                        "Unsupported features ([]) are ignored, ? is treated as a regular character."),
+                    pathFilters: z.array(z.string()).optional().describe(
+                        "Filter paths using glob-like patterns.\n\n" +
+
+                        "**Logic:**\n" +
+                        "- Include patterns (no ! prefix): OR logic - matches ANY pattern\n" +
+                        "- Exclude patterns (! prefix): AND logic - applied globally to exclude ALL matches\n" +
+                        "- Within each pattern: case-insensitive substring matching, order-independent, all parts must exist\n\n" +
+
+                        "**Supported:**\n" +
+                        "- ** (recursive), * (single-level), {a,b} (braces), !prefix (exclude)\n\n" +
+
+                        "**Examples:**\n" +
+                        "- ['src/**/*.ts'] → src tree only\n" +
+                        "- ['src/**/*.ts', 'lib/**/*.ts'] → src OR lib\n" +
+                        "- ['**/*.ts', '!**/*.test.ts'] → all .ts excluding tests\n" +
+                        "- ['src/{components,utils}/*.ts'] → specific folders"
+                    ),
                     minScore: z.union([
                         z.coerce.number(),
                         z.string().transform(s => Number(s))
