fix: Add instructions + fix meta-resources (#35)

* docs: fix bob instructions@

* feat: enrich resource meta-data definitions

* fix: mcp resource description

* fix: mcp resource description

* feature: explicit instructions to llm to use index first before searching

* fix: path with uvx

* fix: path with uvx

Author: vburckhardt

static/instructions.md

@@ -15,13 +15,14 @@ This MCP server is designed to help you leverage Terraform IBM Modules (TIM) to
 
 ## Purpose of this MCP Server
 
-The main purpose of this MCP server is to help generate terraform-based compositions of modules. It provides tools to:
+The main purpose of this MCP server is to help generate terraform-based compositions of modules. It provides tools and resources to:
 
-1. Search for relevant Terraform IBM Modules
-2. Discover available examples and repository structure
-3. Get detailed information about modules, including inputs, outputs, and examples
-4. Access example code and specific files to understand how to use and combine modules
-5. Generate complete, working Terraform configurations
+1. Browse the module index for a high-level overview of available modules
+2. Search for specific Terraform IBM Modules when needed
+3. Discover available examples and repository structure
+4. Get detailed information about modules, including inputs, outputs, and examples
+5. Access example code and specific files to understand how to use and combine modules
+6. Generate complete, working Terraform configurations
 
 ## Architectural Best Practices
 
@@ -44,10 +45,11 @@ The server supports two distinct workflows based on user intent:
 
 Keywords to detect this intent: "example", "sample", "deploy", "show me", "simple"
 
-1. **`search_modules`** → Find relevant modules
-2. **`get_module_details`** → Understand module capabilities using module ID from search results
-3. **`list_content`** → Check what examples are available for the module
-4. **`get_content`** → Fetch example Terraform files (main.tf, provider.tf, version.tf)
+1. First, check the **`catalog://terraform-ibm-modules-index`** resource to get a broad, high-level picture of available modules
+2. If needed, use **`search_modules`** to find more specific modules (optional if the index provides enough information)
+3. Use **`get_module_details`** to understand module capabilities using module ID from the index or search results
+4. Use **`list_content`** to check what examples are available for the module
+5. Use **`get_content`** to fetch example Terraform files (main.tf, provider.tf, version.tf)
 
 The example files provide valuable insights:
 - **Main configuration file**: Shows how to use and combine the module with others
@@ -62,14 +64,22 @@ Note: File names may vary (e.g., main.tf, provider.tf, version.tf, variables.tf,
 
 Keywords to detect this intent: "create", "build", "inputs", "outputs", "develop"
 
-1. **`search_modules`** → Find relevant modules
-2. **`get_module_details`** → Understand inputs/outputs/interface using module ID from search results
-3. **`list_content`** → Explore available examples and structure
-4. **`get_content`** → Fetch example files to understand usage patterns and provider setup
+1. First, check the **`catalog://terraform-ibm-modules-index`** resource to get a broad, high-level picture of available modules
+2. If needed, use **`search_modules`** to find more specific modules (optional if the index provides enough information)
+3. Use **`get_module_details`** to understand inputs/outputs/interface using module ID from the index or search results
+4. Use **`list_content`** to explore available examples and structure
+5. Use **`get_content`** to fetch example files to understand usage patterns and provider setup
 
-## Tool Usage Tips
+## Resource and Tool Usage Tips
+
+### Module Index Resource
+- Start with the module index resource (`catalog://terraform-ibm-modules-index`) to get a broad, high-level picture of available modules
+- Use the index to understand the overall ecosystem of available modules before diving into specific searches
+- The index provides a comprehensive overview that can help identify the most relevant modules for your needs
+- Only proceed to search if the index doesn't provide enough specific information
 
 ### Search Strategy
+- Use search only when you need more specific results than what the index provides
 - Use specific terms rather than generic ones (e.g., "vpc" better than "network")
 - Be specific in requests to minimize context usage and API calls
 - Consider download counts as indicators of module quality and maintenance
@@ -88,11 +98,12 @@ Keywords to detect this intent: "create", "build", "inputs", "outputs", "develop
 
 ## Optimization Principles
 
-1. **Be specific in requests** to minimize context usage and API calls
-2. **Start with narrow scope** (specific files/paths), broaden only if needed
-3. **Exclude test files by default**: `[".*test.*", ".*\\.tftest$", ".*_test\\..*"]`
-4. **For examples, prefer single targeted example** over fetching all examples
-5. **Avoid multiple searches** unless comparing approaches
+1. **Start with the module index resource** to get a comprehensive overview before specific searches
+2. **Be specific in requests** to minimize context usage and API calls
+3. **Start with narrow scope** (specific files/paths), broaden only if needed
+4. **Exclude test files by default**: `[".*test.*", ".*\\.tftest$", ".*_test\\..*"]`
+5. **For examples, prefer single targeted example** over fetching all examples
+6. **Avoid multiple searches** unless comparing approaches
 
 ## Example Workflows
 
@@ -103,8 +114,8 @@ Keywords to detect this intent: "create", "build", "inputs", "outputs", "develop
 
 **Workflow:**
 ```
-1. search_modules("vpc")
-   # Returns: terraform-ibm-modules/landing-zone-vpc/ibm/8.4.0 (among others)
+1. Check catalog://terraform-ibm-modules-index
+   # Browse the index to identify relevant VPC modules
 2. get_module_details("terraform-ibm-modules/landing-zone-vpc/ibm/8.4.0")
    # Understand module capabilities, inputs, outputs
 3. list_content("terraform-ibm-modules/landing-zone-vpc/ibm/8.4.0")
@@ -120,8 +131,8 @@ Keywords to detect this intent: "create", "build", "inputs", "outputs", "develop
 
 **Workflow:**
 ```
-1. search_modules("vpc")
-   # Returns: terraform-ibm-modules/landing-zone-vpc/ibm/8.4.0 (among others)
+1. Check catalog://terraform-ibm-modules-index
+   # Browse the index to identify relevant VPC modules
 2. get_module_details("terraform-ibm-modules/landing-zone-vpc/ibm/8.4.0")
    # Get detailed inputs, outputs, and module interface
 3. list_content("terraform-ibm-modules/landing-zone-vpc/ibm/8.4.0")
@@ -138,12 +149,12 @@ Keywords to detect this intent: "create", "build", "inputs", "outputs", "develop
 
 **Workflow:**
 ```
-1. search_modules("vpc")
-   # Returns: terraform-ibm-modules/landing-zone-vpc/ibm/8.4.0, etc.
+1. Check catalog://terraform-ibm-modules-index
+   # Browse the index to identify relevant modules for VPC, security groups, and clusters
 2. search_modules("security group")
-   # Returns: terraform-ibm-modules/security-group/ibm/2.7.0, etc.
+   # Optional: Search for specific security group modules if needed
 3. search_modules("cluster")
-   # Returns: terraform-ibm-modules/base-ocp-vpc/ibm/3.62.0, etc.
+   # Optional: Search for specific cluster modules if needed
 4. get_module_details("terraform-ibm-modules/landing-zone-vpc/ibm/8.4.0")
 5. get_module_details("terraform-ibm-modules/security-group/ibm/2.7.0")
 6. get_module_details("terraform-ibm-modules/base-ocp-vpc/ibm/3.62.0")
@@ -159,8 +170,8 @@ Keywords to detect this intent: "create", "build", "inputs", "outputs", "develop
 
 **Workflow:**
 ```
-1. search_modules("vpc")
-   # Returns: terraform-ibm-modules/landing-zone-vpc/ibm/8.4.0, etc.
+1. Check catalog://terraform-ibm-modules-index
+   # Browse the index to identify relevant VPC modules
 2. get_module_details("terraform-ibm-modules/landing-zone-vpc/ibm/8.4.0")
    # Understand what the module does and its capabilities
 3. list_content("terraform-ibm-modules/landing-zone-vpc/ibm/8.4.0")
@@ -176,8 +187,8 @@ Keywords to detect this intent: "create", "build", "inputs", "outputs", "develop
 
 **Workflow:**
 ```
-1. search_modules("vpc")
-   # Returns: terraform-ibm-modules/landing-zone-vpc/ibm/8.4.0, etc.
+1. Check catalog://terraform-ibm-modules-index
+   # Browse the index to identify relevant VPC modules
 2. get_module_details("terraform-ibm-modules/landing-zone-vpc/ibm/8.4.0")
    # Understand module interface
 3. list_content("terraform-ibm-modules/landing-zone-vpc/ibm/8.4.0")
@@ -249,6 +260,11 @@ When generating Terraform configurations:
 - Only use IBM Cloud Terraform provider resources when no appropriate module exists
 - Gain insights from example code to understand when to use modules vs provider resources
 
+### Module Discovery
+- **Start with the module index resource** to get a comprehensive overview of available modules
+- Use search only when you need more specific information than what the index provides
+- The index gives you a broad, high-level picture that helps identify the most relevant modules
+
 ### Search Strategy
 - Use specific, targeted search terms
 - Limit results appropriately to avoid information overload

tim_mcp/server.py

@@ -7,6 +7,7 @@
 
 import json
 import time
+import textwrap
 from pathlib import Path
 from typing import Any
 
@@ -30,33 +31,48 @@
 logger = get_logger(__name__)
 
 
-def _load_instructions() -> str:
-    """Load instructions from the static instructions file."""
+def _find_static_file(filename: str) -> Path:
+    """
+    Find a file in the static directory, checking both packaged and development locations.
+    
+    Args:
+        filename: Name of the file to find in the static directory
+        
+    Returns:
+        Path object to the found file
+        
+    Raises:
+        FileNotFoundError: If the file cannot be found in either location
+    """
     # First try the packaged location (when installed via pip/uvx)
-    packaged_path = Path(__file__).parent / "static" / "instructions.md"
+    packaged_path = Path(__file__).parent / "static" / filename
     # Then try the development location (when running from source)
-    dev_path = Path(__file__).parent.parent / "static" / "instructions.md"
-
-    for instructions_path in [packaged_path, dev_path]:
-        if instructions_path.exists():
-            try:
-                return instructions_path.read_text(encoding="utf-8")
-            except Exception as e:
-                logger.error(
-                    f"Error reading instructions file at {instructions_path}: {e}"
-                )
-                continue
-
+    dev_path = Path(__file__).parent.parent / "static" / filename
+    
+    for file_path in [packaged_path, dev_path]:
+        if file_path.exists():
+            return file_path
+            
     # If neither path works, provide helpful error message
-    logger.error(f"Instructions file not found at {packaged_path} or {dev_path}")
+    logger.error(f"File not found at {packaged_path} or {dev_path}")
     raise FileNotFoundError(
-        f"Required instructions file not found. Searched locations:\n"
+        f"Required file '{filename}' not found. Searched locations:\n"
         f"  - {packaged_path} (packaged installation)\n"
         f"  - {dev_path} (development installation)\n"
-        f"Please ensure the instructions.md file exists in the static directory."
+        f"Please ensure the file exists in the static directory."
     )
 
 
+def _load_instructions() -> str:
+    """Load instructions from the static instructions file."""
+    try:
+        instructions_path = _find_static_file("instructions.md")
+        return instructions_path.read_text(encoding="utf-8")
+    except Exception as e:
+        logger.error(f"Error reading instructions file: {e}")
+        raise
+
+
 # Initialize FastMCP server
 mcp = FastMCP(
     "TIM-MCP",
@@ -513,39 +529,28 @@ async def get_content(
 @mcp.resource(
     uri="whitepaper://terraform-best-practices-on-ibm-cloud",
     name="IBM Terraform Whitepaper",
-    description="IBM Cloud Terraform Best Practices white paper in markdown format.",
+    description=textwrap.dedent("""
+    A concise guide to best practices for designing, coding, securing, and operating Terraform Infrastructure as Code solutions on IBM Cloud. 
+    Focuses on modularity, deployable architectures, security governance, and operational workflows.
+    """),
     mime_type="text/markdown",
     tags={"documentation", "best-practices", "terraform"},
     meta={
         "version": "1.0",
         "team": "IBM Cloud",
         "update_frequency": "monthly",
-        "file_size_bytes": (Path(__file__).parent.parent / "static" / "terraform-white-paper.md").stat().st_size
+        "file_size_bytes": _find_static_file("terraform-white-paper.md").stat().st_size
     }
 )
 async def terraform_whitepaper():
-    """IBM Cloud Terraform Best Practices white paper in markdown format."""
-    whitepaper_path = (
-        Path(__file__).parent.parent / "static" / "terraform-white-paper.md"
-    )
+    whitepaper_path = _find_static_file("terraform-white-paper.md")
     return whitepaper_path.read_text(encoding="utf-8")
 
 
 @mcp.resource(
     uri="catalog://terraform-ibm-modules-index",
     name="IBM Terraform Modules Index",
-    description="An compact list of all recommended IBM Terraform modules from the terraform-ibm-modules (TIM) namespace.",
-    mime_type="application/json",
-    tags={"index", "modules", "terraform"},
-    meta={
-        "version": "1.0",
-        "team": "IBM Cloud",
-        "update_frequency": "weekly",
-        "file_size_bytes": (Path(__file__).parent.parent / "static" / "module_index.json").stat().st_size if (Path(__file__).parent.parent / "static" / "module_index.json").exists() else 0
-    }
-)
-async def module_index():
-    """
+    description=textwrap.dedent("""
     IBM Terraform Modules Index - A comprehensive list of all IBM Terraform modules.
 
     This resource provides a curated index of IBM Terraform modules from the
@@ -562,10 +567,21 @@ async def module_index():
 
     Use this resource to get an overview of available modules for context enrichment.
     For detailed module information (inputs, outputs, etc.), use the get_module_details tool.
-    """
-    module_index_path = Path(__file__).parent.parent / "static" / "module_index.json"
-
-    if not module_index_path.exists():
+    """),
+    mime_type="application/json",
+    tags={"index", "modules", "terraform"},
+    meta={
+        "version": "1.0",
+        "team": "IBM Cloud",
+        "update_frequency": "weekly",
+        "file_size_bytes": _find_static_file("module_index.json").stat().st_size
+    }
+)
+async def module_index():
+    try:
+        module_index_path = _find_static_file("module_index.json")
+        return module_index_path.read_text(encoding="utf-8")
+    except FileNotFoundError:
         logger.warning("Module index not found, returning empty index")
         return json.dumps(
             {
@@ -578,8 +594,6 @@ async def module_index():
             indent=2,
         )
 
-    return module_index_path.read_text(encoding="utf-8")
-
 
 def main(transport_config=None):
     """