focus-mcp 0.2.0__py3-none-any.whl

focus_mcp/__init__.py

@@ -0,0 +1,10 @@
+"""FOCUS MCP server: query FOCUS billing data over the Model Context Protocol."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("focus-mcp")
+except PackageNotFoundError:  # running from a source tree with no install
+    __version__ = "0.0.0.dev0"
+
+__all__ = ["__version__"]

focus_mcp/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for `python -m focus_mcp`."""
+
+from focus_mcp.server import main
+
+if __name__ == "__main__":
+    main()

focus_mcp/config.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+"""
+FOCUS MCP Server Configuration - Environment-based settings.
+
+This module centralizes all configuration for the FOCUS MCP server,
+providing a single point of control for data paths, FOCUS version,
+and other runtime settings.
+
+Configuration is environment-driven to support different deployment
+scenarios (development, staging, production) without code changes.
+All settings have sensible defaults for quick local development.
+
+Environment Variables:
+    FOCUS_DATA_LOCATION: Path to FOCUS data (local path, s3:// or gs:// URI)
+                         Default: "data/focus-export"
+                         Relative local paths are resolved against the working
+                         directory at startup and reported as absolute.
+
+    AWS_REGION: AWS region for S3 access
+                Default: "us-east-1"
+
+    AWS_PROFILE: Optional AWS profile for authentication
+                 Uses credential chain if not specified
+
+    GCS_HMAC_KEY_ID: GCS HMAC access key for gs:// locations
+                     (create with: gcloud storage hmac create <service-account>)
+
+    GCS_HMAC_SECRET: GCS HMAC secret paired with GCS_HMAC_KEY_ID.
+                     If unset, Application Default Credentials are used
+                     when gcsfs is installed (gcs extra).
+
+    FOCUS_VERSION: FOCUS specification version
+                   Default: "1.0"
+
+The configuration supports both absolute and relative paths for data,
+with relative paths resolved from the server's working directory.
+"""
+
+import os
+from pathlib import Path
+
+# Data source configuration
+# Supports local paths, S3 locations, and GCS locations
+# Examples:
+#   Local: "/path/to/focus/data" or "data/focus-export"
+#   S3: "s3://bucket-name/path/to/focus/data"
+#   GCS: "gs://bucket-name/path/to/focus/data"
+#
+# For S3, authentication is handled automatically via AWS credential chain:
+# - IAM roles (EC2, ECS, Lambda)
+# - Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
+# - AWS CLI profiles (AWS_PROFILE)
+# - Instance metadata service
+#
+# For GCS, authentication is tiered (see storage_backends.py):
+# - HMAC env vars (GCS_HMAC_KEY_ID, GCS_HMAC_SECRET) if set
+# - Application Default Credentials via gcsfs (gcs extra) otherwise
+# - Keyless access as last resort (public buckets only)
+def _resolve_location(location: str) -> str:
+    """Make local paths absolute; leave remote URIs exactly as given.
+
+    A relative path resolved against an MCP client's working directory is not
+    something a user can debug from an error message. Remote URIs must survive
+    verbatim: Path() would collapse the double slash in "s3://bucket".
+    """
+    if "://" in location:
+        return location
+    return str(Path(location).expanduser().resolve())
+
+
+DATA_LOCATION = _resolve_location(os.getenv("FOCUS_DATA_LOCATION", "data/focus-export"))
+
+# AWS Configuration (optional)
+# Region for S3 access - defaults to us-east-1 if not specified
+AWS_REGION = os.getenv("AWS_REGION", os.getenv("AWS_DEFAULT_REGION", "us-east-1"))
+
+# FOCUS specification version
+# Determines which queries are available based on their focus_versions field
+# Queries are filtered from the unified YAML file at runtime
+# This allows supporting multiple FOCUS versions with version-specific query sets
+FOCUS_VERSION = os.getenv("FOCUS_VERSION", "1.0")

focus_mcp/data_loading.py

@@ -0,0 +1,266 @@
+#!/usr/bin/env python3
+"""
+Data Loading Module - How focus_data_table sources its Parquet files.
+
+Two strategies, picked at view-creation time:
+
+1. Manifest-driven, for AWS BCM Data Exports. AWS writes
+   {location}/metadata/<PARTITION>/<export>-Manifest.json once per
+   billing period and rewrites it on every delivery; its dataFiles array
+   lists the full URIs of exactly the current delivery. Globbing such an
+   export is wrong: the prefix also holds blanked OVERWRITE_REPORT
+   chunks (zero-byte Parquet that crashes read_parquet), superseded
+   CREATE_NEW_REPORT executions, and partition folders orphaned when AWS
+   switches the casing of billing_period= (which also makes DuckDB's
+   Hive inference throw). None of those appear in a manifest, so reading
+   the manifests needs no special-casing of any of them.
+2. Glob fallback, for everything else - bundled sample data, BigQuery
+   FOCUS exports written to GCS, arbitrary directories - which has no
+   metadata/ prefix. An export whose manifests cannot be read is an
+   error rather than a reason to glob it: the manifests are proof that
+   globbing would double-count.
+
+Both strategies run over the connection the storage backend prepared, so
+they behave the same on local paths, s3:// and gs://.
+"""
+
+import logging
+import re
+
+import duckdb
+
+logger = logging.getLogger(__name__)
+
+# Exactly one directory level: partition-level manifests only. Manifests
+# of individual CREATE_NEW_REPORT executions live a level deeper, and the
+# sibling <export>-Manifest-FOCUS.json does not end in "Manifest.json".
+MANIFEST_GLOB = "{location}/metadata/*/*Manifest.json"
+
+# AWS documents BILLING_PERIOD= but has delivered billing_period= too,
+# so both the discovery filter and the derived column ignore casing.
+PARTITION_DIR_PATTERN = re.compile(r"billing_period=\d{4}-\d{2}", re.IGNORECASE)
+BILLING_PERIOD_EXPR = (
+    r"regexp_extract(filename, '(?i)billing_period=(\d{4}-\d{2})', 1)"
+)
+
+# dataFiles holds the URIs of the bucket the export was delivered to. A
+# copy of that export (aws s3 sync into a directory, a mirror in another
+# bucket) keeps AWS's data/<PARTITION>/[<execution>/]<file> layout but not
+# those URIs, so only the layout tail is trusted.
+DATA_FILE_TAIL_PATTERN = re.compile(
+    r"(?:^|/)(data/billing_period=\d{4}-\d{2}/.+)$", re.IGNORECASE
+)
+
+
+def _sql_literal(value: str) -> str:
+    """Quote a string for inlining: views cannot carry bound parameters."""
+    escaped = value.replace("'", "''")
+    return f"'{escaped}'"
+
+
+def _is_partition_manifest(path: str) -> bool:
+    """Whether the manifest sits directly in a billing-period directory."""
+    segments = path.split("/")
+    return len(segments) >= 2 and bool(
+        PARTITION_DIR_PATTERN.fullmatch(segments[-2])
+    )
+
+
+def discover_manifests(
+    conn: duckdb.DuckDBPyConnection, location: str
+) -> list[str]:
+    """Return the partition-level export manifests under the location.
+
+    A location that is not an export simply globs to nothing. An error
+    means the metadata/ prefix could not be listed, which must not be
+    read as "no manifests here": that silently downgrades an export to
+    the glob, so it propagates instead.
+    """
+    pattern = MANIFEST_GLOB.format(location=location)
+    rows = conn.execute("SELECT file FROM glob(?)", [pattern]).fetchall()
+    return sorted(p for (p,) in rows if _is_partition_manifest(p))
+
+
+def read_manifest_data_files(
+    conn: duckdb.DuckDBPyConnection, manifest: str
+) -> list[str]:
+    """Return the dataFiles URIs of one manifest, [] if it can't be read."""
+    try:
+        rows = conn.execute(
+            "SELECT dataFiles FROM read_json_auto(?)", [manifest]
+        ).fetchall()
+    except duckdb.Error as e:
+        logger.warning("Skipping unreadable manifest %s: %s", manifest, e)
+        return []
+    # dataFiles is a flat array of URIs; anything else isn't a file path
+    return [
+        entry
+        for (data_files,) in rows
+        for entry in (data_files or [])
+        if isinstance(entry, str)
+    ]
+
+
+def rebase_data_file(location: str, uri: str) -> str:
+    """Point a dataFiles URI at the location the export is read from.
+
+    Reading the export where it was delivered rebases it onto itself; a
+    copy of it is read from the copy instead of from the original bucket.
+    """
+    match = DATA_FILE_TAIL_PATTERN.search(uri)
+    if not match:
+        # Layout AWS does not write: the manifest's own URI is all we have
+        logger.warning("Unexpected data file path in manifest: %s", uri)
+        return uri
+    return f"{location}/{match.group(1)}"
+
+
+def collect_data_files(
+    conn: duckdb.DuckDBPyConnection, manifests: list[str], location: str
+) -> list[str]:
+    """Union the manifests' dataFiles, deduped, in discovery order."""
+    files: list[str] = []
+    for manifest in manifests:
+        files.extend(
+            rebase_data_file(location, uri)
+            for uri in read_manifest_data_files(conn, manifest)
+        )
+    return list(dict.fromkeys(files))
+
+
+def manifest_view_sql(data_files: list[str]) -> str:
+    """View over an explicit file list, with billing_period derived.
+
+    union_by_name absorbs schema drift between billing periods (FOCUS 1.0
+    months next to 1.2 months); Hive inference stays off because the file
+    list already excludes the orphaned partitions it would trip over.
+    """
+    file_list = ", ".join(_sql_literal(f) for f in data_files)
+    return f"""
+        CREATE OR REPLACE VIEW focus_data_table AS
+        SELECT * EXCLUDE (filename), {BILLING_PERIOD_EXPR} AS billing_period
+        FROM read_parquet(
+            [{file_list}],
+            union_by_name=true,
+            hive_partitioning=false,
+            filename=true
+        )
+    """
+
+
+def glob_view_sql(location: str, hive_partitioning: bool) -> str:
+    """View over every Parquet file under the location.
+
+    union_by_name absorbs schema drift between billing periods here for
+    the same reason it does in manifest_view_sql.
+    """
+    pattern = _sql_literal(f"{location}/**/*.parquet")
+    if hive_partitioning:
+        return f"""
+            CREATE OR REPLACE VIEW focus_data_table AS
+            SELECT * FROM read_parquet(
+                {pattern}, union_by_name=true, hive_partitioning=true
+            )
+        """
+    # Retry path: inference is off, so billing_period is derived from the
+    # path instead of being dropped from the view.
+    return f"""
+        CREATE OR REPLACE VIEW focus_data_table AS
+        SELECT * EXCLUDE (filename), {BILLING_PERIOD_EXPR} AS billing_period
+        FROM read_parquet(
+            {pattern},
+            union_by_name=true,
+            hive_partitioning=false,
+            filename=true
+        )
+    """
+
+
+def _is_readable(conn: duckdb.DuckDBPyConnection, path: str) -> bool:
+    """Whether DuckDB can still see a file a manifest points at."""
+    try:
+        return bool(
+            conn.execute("SELECT count(*) FROM glob(?)", [path]).fetchone()[0]
+        )
+    except duckdb.Error:
+        return False
+
+
+def _create_manifest_view(
+    conn: duckdb.DuckDBPyConnection, location: str, manifests: list[str]
+) -> str:
+    """Create the view from the export's own manifests."""
+    data_files = collect_data_files(conn, manifests, location)
+    if not data_files:
+        # The manifests are proof this is an export, and globbing an
+        # export double-counts it, so there is nothing to fall back to.
+        raise RuntimeError(
+            f"Found {len(manifests)} export manifest(s) under {location} but "
+            "no data file in any of them; the export cannot be loaded "
+            "without readable manifests"
+        )
+    logger.info(
+        "Loading FOCUS data from %d export manifest(s): %d file(s)",
+        len(manifests),
+        len(data_files),
+    )
+    try:
+        conn.execute(manifest_view_sql(data_files))
+    except duckdb.IOException as e:
+        # A manifest outlives its data when a period is expired or cleaned
+        # up by hand. Serve the periods that are left rather than nothing.
+        present = [f for f in data_files if _is_readable(conn, f)]
+        if not present or len(present) == len(data_files):
+            raise
+        logger.warning(
+            "%d of %d manifested file(s) under %s cannot be read (%s); "
+            "loading the other %d",
+            len(data_files) - len(present),
+            len(data_files),
+            location,
+            e,
+            len(present),
+        )
+        conn.execute(manifest_view_sql(present))
+        return "manifest-partial"
+    return "manifest"
+
+
+def _create_glob_view(conn: duckdb.DuckDBPyConnection, location: str) -> str:
+    """Create the view from every Parquet file under the location."""
+    logger.info(
+        "No export manifests under %s; loading every Parquet file "
+        "under the location",
+        location,
+    )
+    try:
+        conn.execute(glob_view_sql(location, hive_partitioning=True))
+    except duckdb.BinderException as e:
+        if "hive partition" not in str(e).lower():
+            raise
+        # Mixed partition-key casings, no manifests to disambiguate them
+        logger.warning(
+            "Hive partition mismatch under %s (%s); loading without "
+            "partition inference",
+            location,
+            e,
+        )
+        conn.execute(glob_view_sql(location, hive_partitioning=False))
+        return "glob-no-hive"
+    return "glob"
+
+
+def create_focus_view(conn: duckdb.DuckDBPyConnection, location: str) -> str:
+    """Create the focus_data_table view over the data at the location.
+
+    Returns the name of the strategy used, which callers surface: a glob
+    over what turns out to be an export is the failure mode this module
+    exists to avoid, and it is invisible otherwise.
+
+    Errors propagate: the caller decides whether to attach a backend hint
+    to them.
+    """
+    manifests = discover_manifests(conn, location)
+    if manifests:
+        return _create_manifest_view(conn, location, manifests)
+    return _create_glob_view(conn, location)

focus_mcp/paths.py

@@ -0,0 +1,22 @@
+"""Locate data files that ship inside the focus_mcp package.
+
+Resources are addressed through importlib.resources rather than __file__ or a
+relative path, so they resolve identically whether the server was started from
+a checkout, a wheel installed by uvx, or the Docker image.
+"""
+
+from importlib.resources import files
+from pathlib import Path
+
+
+def resource_path(*parts: str) -> Path:
+    """Return the absolute path to a file under focus_mcp/resources/.
+
+    Args:
+        parts: Path components below the resources directory, for example
+            ("specifications", "columns.yaml").
+
+    The package is always installed unzipped, so this yields a real filesystem
+    path that DuckDB and PyYAML can open directly.
+    """
+    return Path(str(files("focus_mcp").joinpath("resources", *parts)))

focus_mcp/queries.py

@@ -0,0 +1,215 @@
+#!/usr/bin/env python3
+"""
+FOCUS Query Library - Dynamic query loader for FOCUS billing analytics.
+
+This module provides a structured way to load and manage predefined analytical
+queries for FOCUS (FinOps Open Cost and Usage Specification) billing data.
+Queries are loaded from a comprehensive JSON file containing all use cases
+from focus.finops.org, with automatic filtering based on the configured
+FOCUS version.
+
+The query library provides:
+- Version-specific query filtering (v1.0, v1.1, v1.2)
+- Comprehensive metadata including columns and parameters
+- Parameter descriptions with types and examples
+- Column identification for query validation
+- Source attribution for all queries
+"""
+
+import sys
+import yaml
+from dataclasses import dataclass, field
+from typing import List, Dict, Optional
+from . import config
+from .paths import resource_path
+
+
+@dataclass
+class Query:
+    """
+    Represents a single FOCUS analytical query with comprehensive metadata.
+
+    This class encapsulates all information needed to execute, understand,
+    and validate a FOCUS billing query, including the SQL text and metadata.
+
+    Attributes:
+        name: Human-readable name of the query
+        description: Description of what the query analyzes
+        query: The SQL text with ? placeholders for parameters
+        focus_versions: FOCUS specification versions this query supports
+        citation: Source URL from focus.finops.org
+        slug: URL-friendly identifier
+    """
+    name: str
+    description: str
+    query: str
+    focus_versions: List[str] = field(default_factory=list)
+    citation: str = ""
+    slug: str = ""
+
+
+class QueryLoader:
+    """
+    Manages loading and accessing FOCUS analytical queries from JSON.
+
+    This class loads all FOCUS use cases from a comprehensive JSON file
+    and filters them based on the configured FOCUS version. It provides
+    rich metadata for each query including columns, parameters, and descriptions.
+
+    The loader automatically filters queries at initialization based on
+    the FOCUS_VERSION environment variable and provides methods to access
+    queries by ID, slug, or iterate through all available queries.
+    """
+
+    def __init__(self):
+        """Initialize the query loader and load version-specific queries."""
+        self.queries: Dict[str, Query] = {}
+        self.adjustments: Dict[str, dict] = {}  # Store raw adjustments with comments
+        self._load_queries()
+
+    def _load_queries(self):
+        """
+        Load all queries from the YAML file and filter by FOCUS version.
+
+        The loading process:
+        1. Loads the comprehensive YAML file with all use cases
+        2. Loads adjustments from focus_query_adjustments.yaml
+        3. Applies adjustments by overriding fields
+        4. Filters queries based on configured FOCUS_VERSION
+        5. Converts YAML data to Query objects with full metadata
+        6. Indexes queries by slug for flexible access
+
+        This approach provides version-specific query sets while maintaining
+        all metadata from the focus.finops.org website.
+        """
+        # Find the YAML files that ship inside the package
+        yaml_file = resource_path("queries", "focus_use_cases.yaml")
+        adjustments_file = resource_path("queries", "focus_use_cases_adjustments.yaml")
+
+        if not yaml_file.exists():
+            print(f"Warning: Query file {yaml_file} does not exist", file=sys.stderr)
+            print("Run 'python scrape_to_yaml.py' to generate it", file=sys.stderr)
+            return
+
+        try:
+            with open(yaml_file, 'r', encoding='utf-8') as f:
+                all_queries = yaml.safe_load(f)
+        except Exception as e:
+            print(f"Error loading queries from {yaml_file}: {e}", file=sys.stderr)
+            return
+
+        # Load adjustments if file exists
+        if adjustments_file.exists():
+            try:
+                with open(adjustments_file, 'r', encoding='utf-8') as f:
+                    self.adjustments = yaml.safe_load(f) or {}
+                print(f"Loaded {len(self.adjustments)} query adjustments", file=sys.stderr)
+            except Exception as e:
+                print(f"Error loading adjustments from {adjustments_file}: {e}", file=sys.stderr)
+                self.adjustments = {}
+
+        # Normalize the configured version (e.g., "1.0" -> "v1.0")
+        configured_version = f"v{config.FOCUS_VERSION}"
+
+        # Process each query
+        for key, query_data in all_queries.items():
+            # Apply adjustments if they exist for this query
+            if key in self.adjustments:
+                adjustment = self.adjustments[key]
+                # Override fields from adjustment (except fix_comment)
+                for field, value in adjustment.items():
+                    if field != 'fix_comment':
+                        query_data[field] = value
+
+            # Filter by FOCUS version
+            focus_versions = query_data.get('focus_versions', [])
+            if configured_version not in focus_versions:
+                continue  # Skip queries not compatible with configured version
+
+            # Create Query object with all metadata
+            query = Query(
+                name=query_data.get('title', ''),
+                description=query_data.get('description', ''),
+                query=query_data.get('sql', ''),
+                focus_versions=focus_versions,
+                citation=query_data.get('source_url', ''),
+                slug=query_data.get('slug', key)
+            )
+
+            # Index by slug (key)
+            self.queries[key] = query
+
+        print(f"Loaded {len(self.queries)} queries for FOCUS {config.FOCUS_VERSION}", file=sys.stderr)
+
+    def get_query(self, query_identifier: str) -> Optional[Query]:
+        """
+        Retrieve a specific query by its slug identifier.
+
+        Args:
+            query_identifier: The query slug (underscore-separated key)
+
+        Returns:
+            Query object if found, None otherwise
+        """
+        return self.queries.get(query_identifier)
+
+    def list_queries(self) -> List[Dict[str, str]]:
+        """
+        List all available queries with basic metadata.
+
+        Returns:
+            List of dictionaries with query metadata for display
+        """
+        return [
+            {
+                'slug': query.slug,
+                'name': query.name,
+                'description': query.description or 'No description available',
+                'parameter_count': query.query.count('?'),
+                'versions': ', '.join(query.focus_versions)
+            }
+            for query in self.queries.values()
+        ]
+
+    def get_query_info(self, query: Query) -> str:
+        """
+        Generate comprehensive information about a query for the LLM.
+
+        This method creates a detailed description of the query that helps
+        the LLM understand what parameters are needed and how to use the query.
+
+        Args:
+            query: The Query object to describe
+
+        Returns:
+            Formatted string with complete query information
+        """
+        info = []
+        info.append(f"Query: {query.name}")
+
+        if query.description:
+            info.append(f"Description: {query.description}")
+
+        info.append(f"\nFOCUS Versions: {', '.join(query.focus_versions)}")
+
+        # Just show parameter count from SQL
+        param_count = query.query.count('?')
+        if param_count > 0:
+            info.append(f"\nParameters Required: {param_count}")
+
+        # Add SQL preview
+        sql_preview = query.query[:200] + "..." if len(query.query) > 200 else query.query
+        info.append("\nSQL Preview:")
+        info.append(sql_preview)
+
+        # Add source
+        if query.citation:
+            info.append(f"\nSource: {query.citation}")
+
+        return "\n".join(info)
+
+
+# Global query loader instance
+# Initialized at module import to pre-load all available queries
+# This singleton pattern ensures queries are loaded once and cached
+focus_queries = QueryLoader()