Separating version_to_call and version_of_interest

Author: simonredfern

.env.example

@@ -1,6 +1,9 @@
 # OBP API Configuration
 OBP_BASE_URL="http://localhost:8080"
-OBP_API_VERSION="v7.0.0"
+# Version of the OBP meta-endpoint to call (resource-docs, glossary, /root)
+OBP_VERSION_TO_CALL="v7.0.0"
+# Which API version's endpoint catalog to request (requestedApiVersion)
+API_VERSION_OF_INTEREST="v7.0.0"
 
 # Basic Server Config
 FASTMCP_PORT=9101

Dockerfile

@@ -22,7 +22,8 @@ ENV PATH="/app/.venv/bin:$PATH"
 ENV FASTMCP_HOST=0.0.0.0
 ENV FASTMCP_PORT=9100
 ENV OBP_BASE_URL=https://apisandbox.openbankproject.com
-ENV OBP_API_VERSION=v7.0.0
+ENV OBP_VERSION_TO_CALL=v7.0.0
+ENV API_VERSION_OF_INTEREST=v7.0.0
 
 EXPOSE 9100
 

README.md

@@ -18,7 +18,8 @@ curl -LsSf https://astral.sh/uv/install.sh | sh
 
 ```bash
 OBP_BASE_URL=https://apisandbox.openbankproject.com
-OBP_API_VERSION=v7.0.0
+OBP_VERSION_TO_CALL=v7.0.0
+API_VERSION_OF_INTEREST=v7.0.0
 FASTMCP_HOST=127.0.0.1
 FASTMCP_PORT=9100
 ```

database/data_hash_manager.py

@@ -16,6 +16,8 @@
 from pathlib import Path
 import requests
 
+from .obp_utils import DEFAULT_API_VERSION
+
 logger = logging.getLogger(__name__)
 
 
@@ -35,10 +37,11 @@ def __init__(self, hash_storage_path: Optional[str] = None):
 
         self.hash_storage_path = Path(hash_storage_path)
         self.base_url = os.getenv("OBP_BASE_URL")
-        self.api_version = os.getenv("OBP_API_VERSION")
-        
-        if not self.base_url or not self.api_version:
-            raise ValueError("OBP_BASE_URL and OBP_API_VERSION must be set in environment")
+        self.version_to_call = os.getenv("OBP_VERSION_TO_CALL", DEFAULT_API_VERSION)
+        self.version_of_interest = os.getenv("API_VERSION_OF_INTEREST", DEFAULT_API_VERSION)
+
+        if not self.base_url:
+            raise ValueError("OBP_BASE_URL must be set in environment")
 
     def check_obp_health(self) -> bool:
         """
@@ -47,7 +50,7 @@ def check_obp_health(self) -> bool:
         Returns:
             True if OBP is healthy, False otherwise
         """
-        root_url = f"{self.base_url}/obp/{self.api_version}/root"
+        root_url = f"{self.base_url}/obp/{self.version_to_call}/root"
         try:
             response = requests.get(root_url, timeout=10)
             response.raise_for_status()
@@ -116,8 +119,8 @@ def fetch_current_data_hashes(self, endpoint_type: str = "all") -> Dict[str, str
         Returns:
             Dictionary with 'glossary' and 'endpoints' hashes
         """
-        glossary_url = f"{self.base_url}/obp/{self.api_version}/api/glossary"
-        swagger_url = f"{self.base_url}/obp/{self.api_version}/resource-docs/{self.api_version}/swagger?content={endpoint_type}"
+        glossary_url = f"{self.base_url}/obp/{self.version_to_call}/api/glossary"
+        swagger_url = f"{self.base_url}/obp/{self.version_to_call}/resource-docs/{self.version_of_interest}/swagger?content={endpoint_type}"
 
         try:
             # Fetch data

database/obp_utils.py

@@ -5,6 +5,8 @@
 import requests
 from typing import Dict, Any
 
+DEFAULT_API_VERSION = "v7.0.0"
+
 
 def get_obp_config(endpoint_type: str = "static", use_resource_docs: bool = True) -> Dict[str, str]:
     """
@@ -19,17 +21,21 @@ def get_obp_config(endpoint_type: str = "static", use_resource_docs: bool = True
         Dictionary with configuration including URLs for data fetching
     """
     base_url = os.getenv("OBP_BASE_URL")
-    api_version = os.getenv("OBP_API_VERSION")
-    
-    if not all([base_url, api_version]):
-        raise ValueError("Missing required environment variables: OBP_BASE_URL, OBP_API_VERSION")
-    
+    # Two distinct version axes: the version of the meta-endpoint we hit, and
+    # the requestedApiVersion that selects which endpoint catalog comes back.
+    version_to_call = os.getenv("OBP_VERSION_TO_CALL", DEFAULT_API_VERSION)
+    version_of_interest = os.getenv("API_VERSION_OF_INTEREST", DEFAULT_API_VERSION)
+
+    if not base_url:
+        raise ValueError("Missing required environment variable: OBP_BASE_URL")
+
     config = {
         "base_url": base_url,
-        "api_version": api_version,
-        "glossary_url": f"{base_url}/obp/{api_version}/api/glossary",
-        "swagger_url": f"{base_url}/obp/{api_version}/resource-docs/{api_version}/swagger?content={endpoint_type}",
-        "resource_docs_url": f"{base_url}/obp/{api_version}/resource-docs/{api_version}/obp?content={endpoint_type}",
+        "version_to_call": version_to_call,
+        "version_of_interest": version_of_interest,
+        "glossary_url": f"{base_url}/obp/{version_to_call}/api/glossary",
+        "swagger_url": f"{base_url}/obp/{version_to_call}/resource-docs/{version_of_interest}/swagger?content={endpoint_type}",
+        "resource_docs_url": f"{base_url}/obp/{version_to_call}/resource-docs/{version_of_interest}/obp?content={endpoint_type}",
     }
 
     # Set the primary data URL based on preference

docker-compose.yml

@@ -15,7 +15,8 @@ services:
 
       # OBP API Configuration
       OBP_BASE_URL: ${OBP_BASE_URL:-https://apisandbox.openbankproject.com}
-      OBP_API_VERSION: ${OBP_API_VERSION:-v7.0.0}
+      OBP_VERSION_TO_CALL: ${OBP_VERSION_TO_CALL:-v7.0.0}
+      API_VERSION_OF_INTEREST: ${API_VERSION_OF_INTEREST:-v7.0.0}
 
       # Authentication Configuration (optional)
       ENABLE_OAUTH: ${ENABLE_OAUTH:-false}

docs/HYBRID_ROUTING.md

@@ -221,7 +221,8 @@ python scripts/generate_endpoint_index.py --output /path/to/custom_index.json
 
 **Requirements:**
 - `OBP_BASE_URL` environment variable (e.g., `https://apisandbox.openbankproject.com`)
-- `OBP_API_VERSION` environment variable (e.g., `v7.0.0`)
+- `OBP_VERSION_TO_CALL` environment variable — version of the OBP meta-endpoint to call (e.g., `v7.0.0`)
+- `API_VERSION_OF_INTEREST` environment variable — `requestedApiVersion` for the endpoint catalog (e.g., `v7.0.0`)
 
 ## Deprecated: RAG-Based Tools
 

run_server.sh

@@ -16,7 +16,8 @@ fi
 export FASTMCP_HOST=${FASTMCP_HOST:-0.0.0.0}
 export FASTMCP_PORT=${FASTMCP_PORT:-9100}
 export OBP_BASE_URL=${OBP_BASE_URL:-https://apisandbox.openbankproject.com}
-export OBP_API_VERSION=${OBP_API_VERSION:-v7.0.0}
+export OBP_VERSION_TO_CALL=${OBP_VERSION_TO_CALL:-v7.0.0}
+export API_VERSION_OF_INTEREST=${API_VERSION_OF_INTEREST:-v7.0.0}
 
 # Parse command line arguments
 WATCH_MODE=false
@@ -41,7 +42,8 @@ echo "=========================================="
 echo "Host: $FASTMCP_HOST"
 echo "Port: $FASTMCP_PORT"
 echo "OBP Base URL: $OBP_BASE_URL"
-echo "OBP API Version: $OBP_API_VERSION"
+echo "OBP Version To Call: $OBP_VERSION_TO_CALL"
+echo "API Version Of Interest: $API_VERSION_OF_INTEREST"
 if [ "$WATCH_MODE" = true ]; then
     echo "Watch Mode: ENABLED (auto-reload on changes)"
 fi

src/mcp_server_obp/server.py

@@ -33,6 +33,8 @@
 from src.tools.endpoint_index import get_endpoint_index
 from src.tools.glossary_index import get_glossary_index
 
+from database.obp_utils import DEFAULT_API_VERSION
+
 from mcp_server_obp.lifespan import lifespan
 from mcp_server_obp.auth import get_auth_provider
 from mcp_server_obp.status import health_endpoint, ready_endpoint, status_endpoint
@@ -250,7 +252,7 @@ async def call_obp_api(
     Execute an OBP API request to a specific endpoint.
     
     Uses the lightweight endpoint index to construct and execute the API call.
-    Requires OBP_BASE_URL and OBP_API_VERSION environment variables to be set.
+    Requires the OBP_BASE_URL environment variable to be set.
     You may also need authentication headers depending on the endpoint.
     
     Args:
@@ -279,11 +281,11 @@ async def call_obp_api(
 
         # Build the request URL
         base_url = os.getenv("OBP_BASE_URL")
-        api_version = os.getenv("OBP_API_VERSION")
-        
-        if not base_url or not api_version:
+        version_to_call = os.getenv("OBP_VERSION_TO_CALL", DEFAULT_API_VERSION)
+
+        if not base_url:
             return json.dumps({
-                "error": "OBP_BASE_URL and OBP_API_VERSION environment variables must be set"
+                "error": "OBP_BASE_URL environment variable must be set"
             }, indent=2)
 
         # Construct the path with parameters
@@ -296,7 +298,7 @@ async def call_obp_api(
                 path = path.replace(key, str(value))
 
         # Replace VERSION placeholder
-        path = path.replace("VERSION", api_version)
+        path = path.replace("VERSION", version_to_call)
 
         # Build full URL
         url = f"{base_url}{path}"

src/mcp_server_obp/status.py

@@ -22,6 +22,8 @@
 from starlette.requests import Request
 from starlette.responses import HTMLResponse, JSONResponse, Response
 
+from database.obp_utils import DEFAULT_API_VERSION
+
 logger = logging.getLogger(__name__)
 
 _START_TIME = time.time()
@@ -66,7 +68,8 @@ async def build_status() -> dict[str, Any]:
     from src.tools.glossary_index import get_glossary_index
 
     obp_base_url = os.getenv("OBP_BASE_URL", "").rstrip("/")
-    obp_api_version = os.getenv("OBP_API_VERSION", "")
+    obp_version_to_call = os.getenv("OBP_VERSION_TO_CALL", DEFAULT_API_VERSION)
+    obp_version_of_interest = os.getenv("API_VERSION_OF_INTEREST", DEFAULT_API_VERSION)
     auth_enabled = os.getenv("ENABLE_OAUTH", "false").lower() == "true"
     auth_provider = os.getenv("AUTH_PROVIDER", "none") if auth_enabled else "none"
     outbound_auth_via = os.getenv("OBP_AUTHORIZATION_VIA", "").lower() or None
@@ -95,8 +98,8 @@ async def build_status() -> dict[str, Any]:
     obp_check: dict[str, Any] | None = None
     if obp_base_url:
         root_url = (
-            f"{obp_base_url}/obp/{obp_api_version}/root"
-            if obp_api_version
+            f"{obp_base_url}/obp/{obp_version_to_call}/root"
+            if obp_version_to_call
             else obp_base_url
         )
         obp_check = {"url": root_url, **(await _check_http(root_url))}
@@ -125,7 +128,8 @@ async def build_status() -> dict[str, Any]:
         },
         "obp_api": {
             "base_url": obp_base_url or None,
-            "api_version": obp_api_version or None,
+            "version_to_call": obp_version_to_call or None,
+            "version_of_interest": obp_version_of_interest or None,
             "check": obp_check,
         },
         "auth": {
@@ -196,7 +200,8 @@ def row(label: str, value: Any) -> str:
     obp_check = obp.get("check") or {}
     obp_rows = "".join([
         row("Base URL", obp.get("base_url")),
-        row("API version", obp.get("api_version")),
+        row("Version to call", obp.get("version_to_call")),
+        row("API version of interest", obp.get("version_of_interest")),
         row("Probe URL", obp_check.get("url")),
         row("Reachable", obp_check.get("reachable")),
         row("HTTP status", obp_check.get("status_code")),
@@ -333,11 +338,11 @@ async def ready_endpoint(request: Request) -> Response:
         ok = False
 
     obp_base_url = os.getenv("OBP_BASE_URL", "").rstrip("/")
-    obp_api_version = os.getenv("OBP_API_VERSION", "")
+    obp_version_to_call = os.getenv("OBP_VERSION_TO_CALL", DEFAULT_API_VERSION)
     if obp_base_url:
         url = (
-            f"{obp_base_url}/obp/{obp_api_version}/root"
-            if obp_api_version
+            f"{obp_base_url}/obp/{obp_version_to_call}/root"
+            if obp_version_to_call
             else obp_base_url
         )
         result = await _check_http(url, timeout=2.0)