fix: Various Fixes (#2)

* tests: fix test mocks

* fix: logic bug in file filter

* precommit fixes

* chore: update common dev

* fix: input sanitaization for lists

* fix: improve tool descriptions for better llm guidance

* fix: enhance prompts

* refactor: simplify search_modules interface and clean unused parameters

      - Remove namespace and provider parameters from search_modules tool
      - Server now uses configured namespace automatically
      - Remove unused provider and verified parameters from TerraformClient
      - Clean up LLM documentation to focus on actionable guidance
      - Update all tests to match simplified interface

      This reduces complexity for LLMs while maintaining all functionality
      through server-side configuration.

* feat: add download count sorting to search results
- Always fetch 100 results internally for better sorting accuracy
 - Sort modules by download count in descending order (highest first)
- Return user's requested limit from the sorted results
- Add comprehensive tests for download sorting functionality

* docs: update readme

Author: daniel-butler-irl

.gitignore

@@ -120,4 +120,4 @@ dmypy.json
 .env
 
 .bob/
-.bobignore
+.bobignore

.secrets.baseline

@@ -3,7 +3,7 @@
     "files": "go.sum|^.secrets.baseline$",
     "lines": null
   },
-  "generated_at": "2025-08-11T08:44:39Z",
+  "generated_at": "2025-09-24T11:38:27Z",
   "plugins_used": [
     {
       "name": "AWSKeyDetector"
@@ -77,13 +77,93 @@
     }
   ],
   "results": {
-    "README.md": [
+    "test/test_get_content.py": [
       {
-        "hashed_secret": "ff9ee043d85595eb255c05dfe32ece02a53efbb2",
+        "hashed_secret": "887c04fb792699ceb6b29d9d4cb017d2854f8314",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 65,
-        "type": "Secret Keyword",
+        "line_number": 44,
+        "type": "Base64 High Entropy String",
+        "verified_result": null
+      },
+      {
+        "hashed_secret": "f2fc748e82e02ed29053ddbb52f241a7e10e9a4f",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 45,
+        "type": "Base64 High Entropy String",
+        "verified_result": null
+      },
+      {
+        "hashed_secret": "52a3342b7890ccda14efd7f947fa9ee6fda62529",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 62,
+        "type": "Base64 High Entropy String",
+        "verified_result": null
+      },
+      {
+        "hashed_secret": "67e1c41f7a21c2c3e818b0192a161092ab074b69",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 63,
+        "type": "Base64 High Entropy String",
+        "verified_result": null
+      },
+      {
+        "hashed_secret": "5eb844612e49e7ae88d1297b833d1057f4dddcb8",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 80,
+        "type": "Base64 High Entropy String",
+        "verified_result": null
+      },
+      {
+        "hashed_secret": "462c772756a6e7e0f4c042b643072166fe491e80",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 232,
+        "type": "Base64 High Entropy String",
+        "verified_result": null
+      },
+      {
+        "hashed_secret": "6aee17ecbbef021e3e8e9529facc4fa044180b64",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 284,
+        "type": "Base64 High Entropy String",
+        "verified_result": null
+      },
+      {
+        "hashed_secret": "f10ba892b2ef72888d523de9812f53860cb752b5",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 300,
+        "type": "Base64 High Entropy String",
+        "verified_result": null
+      },
+      {
+        "hashed_secret": "8744edae886af9ba92b6394b0b8820c228fecbcf",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 687,
+        "type": "Base64 High Entropy String",
+        "verified_result": null
+      },
+      {
+        "hashed_secret": "ccd9fa3711ccbf21e2951d7443fcb0c53b651eb9",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 695,
+        "type": "Base64 High Entropy String",
+        "verified_result": null
+      },
+      {
+        "hashed_secret": "0de58b3d996020b8925e18e91bd571cf25cb7fd8",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 703,
+        "type": "Base64 High Entropy String",
         "verified_result": null
       }
     ]

README.md

@@ -16,6 +16,18 @@ Get started with TIM-MCP in Claude Desktop in under 2 minutes:
    ```
 
 2. **Add to Claude Desktop** - Copy this configuration to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+   ```json
+   {
+     "mcpServers": {
+       "tim-terraform": {
+         "command": "uv",
+         "args": ["run", "--from", "git+https://github.com/terraform-ibm-modules/tim-mcp.git", "tim-mcp"]
+       }
+     }
+   }
+   ```
+
+   **Optional: Add GitHub Token** (recommended to avoid rate limits):
    ```json
    {
      "mcpServers": {
@@ -71,7 +83,11 @@ uv run tim-mcp
 
 ### Environment Variables
 
-- `GITHUB_TOKEN`: GitHub API token for accessing private repositories and avoiding rate limits
+- `GITHUB_TOKEN` (optional): GitHub personal access token
+  - **When to use:** Recommended for frequent usage to avoid GitHub API rate limits
+  - **Not required for:** Basic functionality - the server works fine without it for light usage
+  - **Permissions needed:** None (read-only access to public repositories)
+  - **Create token at:** https://github.com/settings/tokens
 - `TIM_ALLOWED_NAMESPACES`: Comma-separated list of allowed module namespaces (default: `terraform-ibm-modules`)
 - `TIM_EXCLUDED_MODULES`: Comma-separated list of module IDs to exclude from search results
 
@@ -83,8 +99,24 @@ TIM-MCP can be configured as an MCP server for use with Claude Desktop or other
 
 This method downloads and runs TIM-MCP directly from the GitHub repository without requiring local installation.
 
-Add this configuration to your Claude Desktop MCP settings (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+**Basic Configuration** (works without GitHub token):
+```json
+{
+  "mcpServers": {
+    "tim-terraform": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--from",
+        "git+https://github.com/terraform-ibm-modules/tim-mcp.git",
+        "tim-mcp"
+      ]
+    }
+  }
+}
+```
 
+**Enhanced Configuration** (with GitHub token to avoid rate limits):
 ```json
 {
   "mcpServers": {
@@ -112,6 +144,23 @@ Add this configuration to your Claude Desktop MCP settings (`~/Library/Applicati
 
 This method is ideal for development and testing, using your local clone of the repository.
 
+**Basic Configuration:**
+```json
+{
+  "mcpServers": {
+    "tim-terraform": {
+      "command": "uv",
+      "args": [
+        "run",
+        "tim-mcp"
+      ],
+      "cwd": "/path/to/your/tim-mcp"
+    }
+  }
+}
+```
+
+**With GitHub Token** (recommended for heavy usage):
 ```json
 {
   "mcpServers": {
@@ -146,12 +195,96 @@ Test the connection by asking Claude: "What IBM Cloud Terraform modules are avai
 
 ## Available MCP Tools
 
-Once configured, TIM-MCP provides these tools to Claude:
+Once configured, TIM-MCP provides these tools to Claude for comprehensive Terraform module discovery and implementation:
+
+### 1. `search_modules`
+**Search Terraform Registry for IBM Cloud modules with intelligent result optimization.**
+
+**Purpose:** Find relevant modules based on search terms, with results optimized by download count for better quality.
+
+**Inputs:**
+- `query` (string, required): Specific search term (e.g., "vpc", "kubernetes", "security")
+- `limit` (integer, optional): Maximum results to return (default: 10, range: 1-100)
+
+**Output:** JSON formatted search results including:
+- Module identifiers and basic metadata
+- Download counts and verification status
+- Descriptions and source repository URLs
+- Publication dates and version information
+
+**Usage Examples:**
+- Quick reference: `limit=3` for "I need a VPC module"
+- Exploring options: `limit=10-15` (default) for comparing alternatives
+- Comprehensive research: `limit=20+` for thorough analysis
+
+### 2. `get_module_details`
+**Retrieve structured module metadata from Terraform Registry - lightweight module interface overview.**
+
+**Purpose:** Get comprehensive module interface information including inputs, outputs, and dependencies without fetching source code.
+
+**Inputs:**
+- `module_id` (string, required): Full module identifier (e.g., "terraform-ibm-modules/vpc/ibm")
+- `version` (string, optional): Specific version or "latest" (default: "latest")
+
+**Output:** Markdown formatted module details including:
+- Module description and documentation
+- Required and optional input variables with types, descriptions, and defaults
+- Available outputs with types and descriptions
+- Provider requirements and version constraints
+- Module dependencies and available versions
+
+**When to Use:** First step after finding a module to understand its interface - often sufficient to answer user questions without fetching implementation files.
+
+### 3. `list_content`
+**Discover available paths in a module repository with README summaries.**
+
+**Purpose:** Explore repository structure to understand available examples, submodules, and solutions before fetching specific content.
+
+**Inputs:**
+- `module_id` (string, required): Full module identifier (e.g., "terraform-ibm-modules/vpc/ibm")
+- `version` (string, optional): Git tag/branch to scan (default: "latest")
+
+**Output:** Markdown formatted content listing organized by category:
+- **Root Module:** Main terraform files, inputs/outputs definitions
+- **Examples:** Deployable examples showing module usage (ideal starting point)
+- **Submodules:** Reusable components within the module
+- **Solutions:** Complete architecture patterns for complex scenarios
+
+**Usage Tips:** Use before `get_content` to select the most relevant path for your needs.
+
+### 4. `get_content`
+**Retrieve source code, examples, and documentation from GitHub repositories with targeted content filtering.**
+
+**Purpose:** Fetch actual implementation files, examples, and documentation with precise filtering to avoid large responses.
+
+**Inputs:**
+- `module_id` (string, required): Full module identifier (e.g., "terraform-ibm-modules/vpc/ibm")
+- `path` (string, optional): Specific path - "" (root), "examples/basic", "modules/vpc", etc.
+- `include_files` (list[string], optional): Regex patterns for files to include
+- `exclude_files` (list[string], optional): Regex patterns for files to exclude
+- `include_readme` (boolean, optional): Include README.md for context (default: true)
+- `version` (string, optional): Git tag/branch to fetch from (default: "latest")
+
+**Output:** Markdown formatted content with file contents, organized by:
+- File paths and content
+- File sizes for reference
+- Context from README files when requested
+
+**Common Patterns:**
+- Input variables only: `include_files=["variables\\.tf$"]`
+- Basic example: `path="examples/basic", include_files=["main\\.tf$", "variables\\.tf$"]`
+- Complete module: `include_files=[".*\\.tf$"]`
+
+## Tool Workflow
+
+The tools are designed to work together in an efficient workflow:
+
+1. **`search_modules`** → Find relevant modules
+2. **`get_module_details`** → Understand module interface (often sufficient)
+3. **`list_content`** → Explore repository structure if needed
+4. **`get_content`** → Fetch specific implementation details
 
-1. **`search_modules`** - Search Terraform Registry for IBM Cloud modules
-2. **`get_module_details`** - Retrieve detailed module metadata and documentation
-3. **`list_content`** - Discover available files and structure in module repositories
-4. **`get_content`** - Fetch source code, examples, and documentation from GitHub
+This progressive approach minimizes API calls and provides context-aware information at each step.
 
 ## Troubleshooting
 

common-dev-assets

@@ -9,4 +9,4 @@
       }
     }
   }
-}
+}

examples/claude_desktop.json

@@ -7,4 +7,4 @@
       "env": {}
     }
   }
-}
+}