Merge branch 'feature'

Author: nemozak1

.env.example

@@ -2,11 +2,15 @@
 OBP_BASE_URL="http://localhost:8080"
 OBP_API_VERSION="v6.0.0"
 
+# Basic Server Config
+FASTMCP_PORT=9101
+FASTMCP_HOST=0.0.0.0
+
 # OAuth Settings
 ENABLE_OAUTH="false"
 
 ## this is the url of this mcp application i.e. http://localhost:9100
-BASE_URL="http://localhost:9100"
+BASE_URL="http://localhost:9101"
 
 # Choose authentication provider:
 #   - "bearer-only": Simple JWT validation only (recommended for Opey/internal agents)
@@ -28,6 +32,18 @@ AUTH_PROVIDER=obp-oidc
 # For bearer-only: Set this to accept tokens from OBP-OIDC
 OBP_OIDC_ISSUER_URL=http://localhost:9000/obp-oidc
 
+# This setting controls how we authorize API requests to OBP after authentication.
+# Options:
+#   - "oauth":  Use OAuth the oauth access token. Best for when using an MCP client that cannot perform the 
+#               consent flow itself (e.g. VS Code extension, Claude Desktop).
+#   - "consent": Elicit user consent before each API call. Best for MCP clients like Opey that will support
+#               user consent flows.
+#   - "none":   No authorization method is used. OBP-API calls are made but with limited access (only public endpoints).
+OBP_AUTHORIZATION_VIA="none" # Options: "oauth", "consent", "none"
+
+# OBP API consumer key that opey uses (required for "consent" authorization method with opey)
+OPEY_OPEY_OBP_CONSUMER_KEY="obp-opey-ii-client"
+
 # Multi-issuer bearer-only mode:
 # Set BOTH KEYCLOAK_REALM_URL and OBP_OIDC_ISSUER_URL with AUTH_PROVIDER=bearer-only
 # to accept tokens from either identity provider. The server will route validation
@@ -54,3 +70,6 @@ UPDATE_INDEX_ENDPOINT_TYPE="all"
 
 # Periodic refresh interval in minutes (0 to disable)
 REFRESH_INTERVAL_MINUTES="5"
+
+# Options: "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"
+LOG_LEVEL="INFO" 

CLAUDE.md

@@ -0,0 +1,89 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+OBP-MCP is a Model Context Protocol (MCP) server for the Open Bank Project API, built with `fastmcp`. It exposes 600+ OBP API endpoints to AI assistants through a hybrid tag-based routing system with OAuth 2.1 authentication.
+
+## Common Commands
+
+All commands use `uv` as the package manager:
+
+```bash
+# Install/sync dependencies
+uv sync
+
+# Run the server
+./run_server.sh              # normal mode
+./run_server.sh --watch      # auto-reload on file changes
+uv run python src/mcp_server_obp/server.py  # direct
+
+# Run tests
+uv run pytest                         # all tests
+uv run pytest tests/test_auth.py      # single file
+uv run pytest -v                      # verbose
+
+# Generate data indexes (requires OBP_BASE_URL in .env)
+uv run python scripts/generate_endpoint_index.py
+uv run python scripts/generate_glossary_index.py
+
+# Add a dependency
+uv add <package>
+```
+
+## Architecture
+
+### Three-Step Endpoint Discovery (not RAG)
+
+The server avoids vector databases. Instead it uses a tag-based discovery pattern:
+
+1. **`list_endpoints_by_tag(tags)`** — returns lightweight summaries (~50-100 tokens each) from `endpoint_index.json` (250KB)
+2. **`get_endpoint_schema(endpoint_id)`** — lazy-loads full OpenAPI schema from `endpoint_schemas.json` (4.3MB)
+3. **`call_obp_api(endpoint_id, ...)`** — executes the actual HTTP request against OBP-API
+
+Additional tools: `list_glossary_terms(search_query)` and `get_glossary_term(term_id)` for 800+ banking terms.
+
+### Key Modules
+
+- **`src/mcp_server_obp/server.py`** — FastMCP server definition, all tool/resource registrations
+- **`src/mcp_server_obp/auth.py`** — Multi-provider auth: `bearer-only`, `obp-oidc`, `keycloak`, `none`
+- **`src/mcp_server_obp/lifespan.py`** — Server lifecycle, startup index updates, periodic refresh
+- **`src/tools/endpoint_index.py`** — `EndpointIndex` class with strict Pydantic types, tag filtering, lazy schema loading
+- **`src/tools/glossary_index.py`** — `GlossaryIndex` class for term search/retrieval
+- **`database/`** — JSON index files, `startup_updater.py` for auto-refresh, `data_hash_manager.py` for change detection
+- **`scripts/`** — Standalone generators that fetch from OBP resource-docs/swagger API
+
+### Authentication Modes (`AUTH_PROVIDER` env var)
+
+| Mode | Use Case | Notes |
+|------|----------|-------|
+| `bearer-only` | Internal agents (e.g., Opey) | JWT validation only, multi-issuer support |
+| `obp-oidc` | External MCP clients | Full OAuth 2.1 + Dynamic Client Registration |
+| `keycloak` | External MCP clients | OAuth 2.1 + minimal DCR proxy workaround |
+| `none` | Development/testing | No auth required |
+
+### Data Flow
+
+- JSON indexes stored in `database/` — no external database needed
+- `DataHashManager` compares hashes to detect upstream changes
+- `IndexStartupUpdater` refreshes on startup if `UPDATE_INDEX_ON_STARTUP=true`
+- Periodic refresh configurable via `REFRESH_INTERVAL_MINUTES`
+
+## Configuration
+
+All config via environment variables. Copy `.env.example` to `.env`. Key variables:
+
+- `OBP_BASE_URL` — OBP API instance URL
+- `OBP_API_VERSION` — API version (e.g., `v6.0.0`)
+- `AUTH_PROVIDER` — Authentication mode (see table above)
+- `OBP_AUTHORIZATION_VIA` — How API calls are authorized: `oauth`, `consent`, or `none`
+- `LOG_LEVEL` — `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`
+- `FASTMCP_HOST` / `FASTMCP_PORT` — Server bind address
+
+## Testing Conventions
+
+- Tests live in `tests/` using pytest
+- `conftest.py` provides shared fixtures (auth URLs, JWT payloads, `clean_env` for env isolation)
+- Test files: `test_auth.py` (auth providers), `test_endpoint_index.py` (endpoint index)
+- Tests use `pytest-asyncio` for async code

ai_env

@@ -6,26 +6,47 @@
 from typing import Dict, Any
 
 
-def get_obp_config(endpoint_type="static"):
-    """Get OBP configuration from environment variables."""
+def get_obp_config(endpoint_type: str = "static", use_resource_docs: bool = True) -> Dict[str, str]:
+    """
+    Get OBP configuration from environment variables.
+    
+    Args:
+        endpoint_type: Type of endpoints to fetch ("static", "dynamic", or "all")
+        use_resource_docs: If True, use resource-docs endpoint (includes roles).
+                          If False, use swagger endpoint.
+    
+    Returns:
+        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")
 
-    return {
+    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}"
+        "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}",
     }
+    
+    # Set the primary data URL based on preference
+    if use_resource_docs:
+        config["data_url"] = config["resource_docs_url"]
+        config["data_format"] = "resource_docs"
+    else:
+        config["data_url"] = config["swagger_url"]
+        config["data_format"] = "swagger"
+    
+    return config
 
 
 def fetch_obp_data(url: str) -> Dict[str, Any]:
     """Fetch data from OBP API endpoint."""
     print(f"Fetching data from: {url}")
-    response = requests.get(url, timeout=30)
+    response = requests.get(url, timeout=60)  # Increased timeout for large responses
     try:
         response.raise_for_status()
     except requests.exceptions.HTTPError as e:

database/obp_utils.py

@@ -1,9 +1,10 @@
 #!/usr/bin/env python3
 """
-Script to generate the lightweight endpoint index from OBP swagger data.
+Script to generate the lightweight endpoint index from OBP resource docs.
 
-This script fetches the swagger/OpenAPI specification from the OBP API
-and generates a lightweight index for fast endpoint discovery.
+This script fetches the resource docs from the OBP API and generates a 
+lightweight index for fast endpoint discovery. Resource docs provide richer
+information than swagger, including roles/entitlements required for each endpoint.
 """
 import os
 import sys
@@ -23,7 +24,7 @@ def main():
 
     # Parse command line arguments
     parser = argparse.ArgumentParser(
-        description="Generate lightweight endpoint index from OBP swagger data."
+        description="Generate lightweight endpoint index from OBP resource docs."
     )
     parser.add_argument(
         "--endpoints",
@@ -37,33 +38,48 @@ def main():
         default=None,
         help="Output file path for the index (default: database/endpoint_index.json)"
     )
+    parser.add_argument(
+        "--use-swagger",
+        action="store_true",
+        help="Use swagger endpoint instead of resource docs (not recommended - lacks role info)"
+    )
     args = parser.parse_args()
 
+    use_resource_docs = not args.use_swagger
+    
     try:
         # Get configuration
-        config = get_obp_config(args.endpoints)
+        config = get_obp_config(args.endpoints, use_resource_docs=use_resource_docs)
 
-        # Fetch swagger data
+        # Fetch data
         print("\n" + "="*50)
-        print("FETCHING SWAGGER DATA")
+        print(f"FETCHING {'RESOURCE DOCS' if use_resource_docs else 'SWAGGER'} DATA")
         print("="*50)
-        swagger_data = fetch_obp_data(config["swagger_url"])
+        print(f"URL: {config['data_url']}")
+        
+        data = fetch_obp_data(config["data_url"])
 
         # Build index
         print("\n" + "="*50)
         print("BUILDING ENDPOINT INDEX")
         print("="*50)
 
         index = EndpointIndex(index_file=args.output)
-        index.build_index_from_swagger(swagger_data)
+        
+        if use_resource_docs:
+            index.build_index_from_resource_docs(data)
+        else:
+            index.build_index_from_swagger(data)
 
         # Print statistics
         print("\n" + "="*50)
         print("INDEX GENERATION COMPLETE")
         print("="*50)
+        print(f"Data source: {'Resource Docs' if use_resource_docs else 'Swagger'}")
         print(f"Total endpoints indexed: {len(index._index)}")
         print(f"Total unique tags: {len(index.get_all_tags())}")
-        print(f"Output file: {index.index_file}")
+        print(f"Index file: {index.index_file}")
+        print(f"Schemas file: {index.schemas_file}")
 
         # Print sample of tags
         all_tags = index.get_all_tags()
@@ -72,8 +88,18 @@ def main():
             for tag in all_tags[:10]:
                 print(f"  - {tag}")
 
+        # If using resource docs, show role statistics
+        if use_resource_docs:
+            endpoints_with_roles = sum(
+                1 for schema in index._schemas.values() 
+                if schema.get("roles")
+            )
+            print(f"\nEndpoints with role requirements: {endpoints_with_roles}")
+        
     except Exception as e:
         print(f"Error during index generation: {e}")
+        import traceback
+        traceback.print_exc()
         sys.exit(1)
 
 

scripts/generate_endpoint_index.py

@@ -178,8 +178,14 @@ async def verify_token(self, token: str):
             AccessToken object if valid, None if invalid or expired
         """
         logger.info("🔐 Starting token verification")
-        logger.debug(f"Token (first 20 chars): {token[:20]}...")
-        logger.debug(f"Configured issuers: {list(self._verifiers.keys())}")
+        logger.info(f"Token (first 20 chars): {token[:20]}...")
+        logger.info(f"Configured issuers: {list(self._verifiers.keys())}")
+
+        # Fast-fail on clearly malformed tokens to avoid noisy verifier errors
+        token = token.strip()
+        if token.count(".") < 2:
+            logger.warning("Rejected token without JWT structure (expected header.payload.signature)")
+            return None
 
         # Extract issuer from token
         issuer = self._extract_issuer(token)

src/mcp_server_obp/auth.py

@@ -1,4 +1,5 @@
 import asyncio
+import json
 import logging
 import os
 from contextlib import asynccontextmanager
@@ -8,6 +9,53 @@
 logger = logging.getLogger(__name__)
 
 
+def print_client_configs():
+    """Print copy-pasteable MCP client configuration snippets."""
+    host = os.getenv("FASTMCP_HOST", "127.0.0.1")
+    port = os.getenv("FASTMCP_PORT", "9100")
+    auth_provider = os.getenv("AUTH_PROVIDER", "none")
+    requires_auth = auth_provider != "none"
+    base_url = f"http://{host}:{port}/mcp"
+
+    configs = {
+        "Opey": {
+            "servers": [
+                {
+                    "name": "obp",
+                    "url": base_url,
+                    "transport": "http",
+                    "requires_auth": requires_auth,
+                }
+            ]
+        },
+        "Claude Desktop / claude_desktop_config.json": {
+            "mcpServers": {
+                "obp": {
+                    "url": base_url,
+                }
+            }
+        },
+        "VS Code / settings.json": {
+            "mcp": {
+                "servers": {
+                    "obp": {
+                        "url": base_url,
+                    }
+                }
+            }
+        },
+    }
+
+    separator = "=" * 60
+    print(f"\n{separator}")
+    print("MCP Client Configurations")
+    print(separator)
+    for name, config in configs.items():
+        print(f"\n--- {name} ---\n")
+        print(json.dumps(config, indent=2))
+    print(f"\n{separator}\n")
+
+
 async def periodic_index_refresh(interval_minutes: int):
     """Periodically check and update the index every N minutes."""
     interval_seconds = interval_minutes * 60
@@ -42,7 +90,8 @@ async def lifespan(server) -> AsyncIterator[dict[str, Any]]:
     """
     # Startup actions
     logger.info("Starting MCP server...")
-    
+    print_client_configs()
+
     # Check and update index on startup
     success = await update_index_on_startup()
     if not success: