Agentic behaviour to call guide before anything else (#4)

Author: anujhydrabadi

README.md

@@ -29,6 +29,7 @@ This MCP (Model Context Protocol) Server provides seamless integration with the
 
 | Tool Name                               | Description                                                                                                       |
 | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `FIRST_STEP_get_api_script_guide`       | **🚀 Start here!** Loads comprehensive API script generation guide - call this tool first before using others.  |
 | `refresh_api_catalog`                   | Refreshes the API catalog by fetching the latest OpenAPI specification from the control plane.                   |
 | `search_api_operations`                 | Search for operations using fuzzy matching across operation IDs, summaries, descriptions, and tags.             |
 | `search_api_schemas`                    | Search for schemas by name and description to find relevant data structures.                                     |
@@ -65,7 +66,7 @@ Add the following to your `claude_desktop_config.json`:
       "command": "uv",
       "args": ["run", "--directory", "/path/to/your/cloned/control-plane-openapi-mcp", "control-plane-openapi-mcp"],
       "env": {
-        "CONTROL_PLANE_URL": "https://facetsdemo.console.facets.cloud",
+        "CONTROL_PLANE_URL": "https://<customername>.console.facets.cloud",
         "FACETS_USERNAME": "<YOUR_USERNAME>",
         "FACETS_TOKEN": "<YOUR_TOKEN>",
         "FACETS_PROFILE": "default",
@@ -97,11 +98,10 @@ For credential setup, refer to the [Facets Authentication Guide](https://readme.
 
 ## Usage Highlights
 
-- Use `search_api_operations` and `search_api_schemas` to find relevant endpoints using natural language
-- Use specific load operations to get detailed parameter and response information
-- Use `call_control_plane_api` to make actual API calls and get real data from your Facets environment
-- Leverage the fuzzy search to find operations even with partial or approximate terms
-- All results exclude deprecated operations for cleaner, more relevant responses
+- Uses `search_api_operations` and `search_api_schemas` to find relevant endpoints using natural language
+- Uses specific load operations to get detailed parameter and response information
+- Uses `call_control_plane_api` to make actual API calls and get real data from your Facets environment
+- Leverages the fuzzy search to find operations even with partial or approximate terms
 
 ## API Coverage
 
@@ -120,15 +120,15 @@ The server provides access to the complete Facets Control Plane API including:
 When using with Claude, try these example prompts:
 
 ```
-"Show me all stack-related operations in the Facets API"
-"What are the required parameters for creating a new stack?"
-"Find operations related to cluster deployments"
-"Show me the Stack schema structure with all its properties"
-"Generate a TypeScript interface for the Stack model"
-"Get the current list of stacks from my environment"
-"Show me details of a specific stack named 'my-production-stack'"
-"What clusters are running in my Facets environment?"
-"Create an example API call to get stack information"
+"Show me all project-related operations in the Facets API"
+"What are the required parameters for creating a new project?"
+"Find operations related to environment deployments"
+"Show me the project schema structure with all its properties"
+"Generate a TypeScript interface for the project model"
+"Get the current list of projects from my environment"
+"Show me details of a specific project named 'my-production-project'"
+"What environments are running in my Facets environment?"
+"Create an example API call to get project information"
 "Find all endpoints that handle artifact routing"
 "What authentication methods are available in the API?"
 ```
@@ -155,24 +155,6 @@ When using with Claude, try these example prompts:
    .venv\Scripts\activate     # On Windows
    ```
 
-### Running Tests
-
-```bash
-# Run the example script to test functionality
-uv run python example.py
-
-# Test direct tool imports
-uv run python test_final.py
-
-# Test specific functionality
-uv run python -c "
-from control_plane_openapi_mcp.tools import search_api_operations
-import json
-result = search_api_operations('stack')
-print(f'Found {len(json.loads(result)[\"operations\"])} operations')
-"
-```
-
 ### Testing the MCP Server
 
 ```bash
@@ -210,34 +192,14 @@ control_plane_openapi_mcp/
 
 ---
 
-## Example Usage
-
-For comprehensive examples of API exploration and integration, check out the included scripts:
-
-- **`example.py`**: Demonstrates all available tools with real API data
-- **`test_final.py`**: Validates functionality and shows expected results
-
-These examples show the complete workflow from API discovery to detailed operation analysis.
-
----
-
 ## Architecture
 
 - **`SpecLoader`**: Fetches and processes OpenAPI specifications with JSON reference resolution
 - **`SpecProcessor`**: Extracts operations and schemas while filtering deprecated endpoints  
 - **`SearchEngine`**: Provides fuzzy search capabilities with configurable matching thresholds
 - **`OpenAPIService`**: Main service coordinating all components with intelligent caching
 - **`SimpleCache`**: TTL-based caching for performance optimization
-- **MCP Tools**: Seven specialized tools exposing functionality to AI assistants
-
-## Comparison with TypeScript Version
-
-This Python implementation provides similar functionality to the TypeScript `@reapi/mcp-openapi` but is:
-
-- **Simpler**: Single API spec focus, no file system operations required
-- **Focused**: Specifically designed for Facets Control Plane integration
-- **Efficient**: Direct JSON processing with smart caching strategies
-- **Lightweight**: Fewer dependencies and cleaner abstractions
+- **MCP Tools**: Specialized tools exposing functionality to AI assistants
 
 ## License
 

control_plane_openapi_mcp/tools.py

@@ -1,5 +1,6 @@
 import json
 import logging
+import os
 
 from .config import mcp, OPENAPI_URL, CACHE_TTL, SPEC_ID
 from .core.service import OpenAPIService
@@ -24,9 +25,58 @@
     logger.info("API client not available - only OpenAPI exploration tools will work")
 
 
+@mcp.resource(uri="resource://control_plane_api_knowledge", name="Control Plane API Knowledge Base")
+def call_always_for_instruction() -> str:
+    return FIRST_STEP_get_api_script_guide()
+
+
+@mcp.tool()
+def FIRST_STEP_get_api_script_guide() -> str:
+    """
+    <important>ALWAYS Call this tool first before calling any other tool of this mcp.</important>
+    Loads the API script generation guide that contains comprehensive instructions for creating 
+    scripts that interact with Control Plane APIs.
+
+    Returns:
+        str: A JSON string containing the content of the API script guide.
+    """
+    try:
+        # Get the directory where this file is located
+        current_dir = os.path.dirname(__file__)
+        guide_path = os.path.join(current_dir, "prompts", "api_script_guide.md")
+        
+        # Read the guide content
+        with open(guide_path, 'r', encoding='utf-8') as f:
+            guide_content = f.read()
+        
+        return json.dumps({
+            "success": True,
+            "message": "API script guide loaded successfully.",
+            "instructions": "Inform User: API script guide loaded successfully.",
+            "data": {
+                "api_script_guide.md": guide_content
+            }
+        }, indent=2)
+    
+    except FileNotFoundError:
+        return json.dumps({
+            "success": False,
+            "message": "API script guide file not found.",
+            "error": f"Could not find api_script_guide.md at {guide_path}"
+        }, indent=2)
+    
+    except Exception as e:
+        return json.dumps({
+            "success": False,
+            "message": "Failed to load API script guide.",
+            "error": str(e)
+        }, indent=2)
+
+
 @mcp.tool()
 def refresh_api_catalog() -> str:
     """
+    <important>Make Sure you have Called FIRST_STEP_get_api_script_guide first before this tool.</important>
     Refresh the API catalog by fetching the latest OpenAPI specification.
     
     Returns:
@@ -49,6 +99,7 @@ def refresh_api_catalog() -> str:
 @mcp.tool()
 def search_api_operations(query: str) -> str:
     """
+    <important>Make Sure you have Called FIRST_STEP_get_api_script_guide first before this tool.</important>
     Search for operations across the OpenAPI specification using fuzzy matching.
     
     Note: Only searches through active (non-deprecated) operations.
@@ -89,6 +140,7 @@ def search_api_operations(query: str) -> str:
 @mcp.tool()
 def search_api_schemas(query: str) -> str:
     """
+    <important>Make Sure you have Called FIRST_STEP_get_api_script_guide first before this tool.</important>
     Search for schemas across the OpenAPI specification using fuzzy matching.
     
     Args:
@@ -146,6 +198,7 @@ def _format_operation_response(operation) -> str:
 @mcp.tool()
 def load_api_operation_by_operationId(operation_id: str) -> str:
     """
+    <important>Make Sure you have Called FIRST_STEP_get_api_script_guide first before this tool.</important>
     Load a specific operation by its operationId.
     
     Args:
@@ -168,6 +221,7 @@ def load_api_operation_by_operationId(operation_id: str) -> str:
 @mcp.tool()
 def load_api_operation_by_path_and_method(path: str, method: str) -> str:
     """
+    <important>Make Sure you have Called FIRST_STEP_get_api_script_guide first before this tool.</important>
     Load a specific operation by its path and HTTP method.
     
     Args:
@@ -191,6 +245,7 @@ def load_api_operation_by_path_and_method(path: str, method: str) -> str:
 @mcp.tool()
 def load_api_schema_by_schemaName(schema_name: str) -> str:
     """
+    <important>Make Sure you have Called FIRST_STEP_get_api_script_guide first before this tool.</important>
     Load a specific schema by its name.
     
     Args:
@@ -228,6 +283,7 @@ def load_api_schema_by_schemaName(schema_name: str) -> str:
 @mcp.tool()
 def call_control_plane_api(path: str) -> str:
     """
+    <important>Make Sure you have Called FIRST_STEP_get_api_script_guide first before this tool.</important>
     Make a GET request to the Facets Control Plane API.
     
     Args: