phlo-mcp 0.2.0__tar.gz

phlo_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.4
+Name: phlo-mcp
+Version: 0.2.0
+Summary: MCP server for Phlo observability and lakehouse operations
+Author-email: Phlo Team <team@phlo.dev>
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/plain
+Requires-Dist: phlo>=0.1.0
+Requires-Dist: phlo-api>=0.1.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: mcp[cli]>=1.20.0
+Requires-Dist: opentelemetry-sdk>=1.38.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+
+MCP server for Phlo observability and lakehouse operations.

phlo_mcp-0.2.0/README.md

@@ -0,0 +1,185 @@
+# phlo-mcp
+
+MCP server for Phlo observability and lakehouse operations.
+
+## Overview
+
+`phlo-mcp` exposes curated read-only MCP tools over Phlo's observability and
+operator surfaces. It sits on top of `phlo-api` and gives MCP clients a stable,
+agent-friendly surface for lakehouse inspection.
+
+## Install
+
+```bash
+uv pip install -e packages/phlo-mcp
+```
+
+## Exposed tools
+
+- `get_platform_health`
+- `get_service_status`
+- `get_recent_alerts`
+- `get_dashboard_links`
+- `get_logs_query_link`
+- `get_metrics_query_link`
+- `get_materialization_history`
+- `get_run_logs`
+- `get_run_trace_spans`
+- `get_trace_spans`
+- `render_trace_spans_tree`
+- `inspect_materialization`
+- `get_asset_materialization_trace`
+- `render_materialization_trace_tree`
+- `render_run_trace_tree`
+
+Optional guarded operational tools:
+
+- `materialize_asset`
+- `retry_failed_run`
+- `get_dagster_run_status`
+
+Resources:
+
+- `phlo://runtime/config`
+- `phlo://runtime/services`
+- `phlo://runtime/services/{service_name}`
+- `phlo://runtime/plugins`
+- `phlo://runtime/assets`
+- `phlo://runtime/assets/{asset_key_path}`
+- `phlo://runtime/schemas/{asset_key_path}`
+- `phlo://runtime/contracts`
+- `phlo://runtime/contracts/{table_name}`
+- `phlo://runtime/dashboards`
+- `phlo://docs/packages/{package_name}`
+
+Run-level and materialization tools rely on the backing `phlo-api` having access
+to Dagster asset history, Loki log queries, and ClickStack OTEL trace storage.
+Trace tools can be filtered by run id, asset key, job name, service name, span
+name, status code, and start/end time.
+Resource URIs are read-only and deterministic so MCP clients can attach Phlo
+runtime context without invoking parameterized tools.
+
+When real spans are available, rendered trees include:
+- span kind
+- status code
+- duration
+- selected Phlo attributes like stage, asset key, job name, and operation
+
+## Usage
+
+Start a backing API first:
+
+```bash
+uv run --package phlo-api uvicorn phlo_api.main:app --host 127.0.0.1 --port 4000
+```
+
+Run the MCP server over stdio:
+
+```bash
+phlo-mcp --api-base-url http://127.0.0.1:4000
+```
+
+For protected `phlo-api` instances, provide a bearer token:
+
+```bash
+phlo-mcp \
+  --api-base-url http://127.0.0.1:4000 \
+  --api-token "$PHLO_API_TOKEN"
+```
+
+Guarded operational tools are disabled by default. To expose asset
+materialization and run retry tools, set `PHLO_MCP_ENABLE_WRITE_TOOLS=true` or
+pass `--enable-write-tools` with an API token. Write tools return structured
+`audit_context` metadata and default to `dry_run=true` where supported. Current
+`phlo-api` operation routes support dry-run validation and run status; live
+Dagster launch and retry are intentionally not implemented yet.
+
+Claude Code example:
+
+```json
+{
+  "mcpServers": {
+    "phlo": {
+      "command": "uv",
+      "args": ["run", "--package", "phlo-mcp", "phlo-mcp", "--api-base-url", "http://127.0.0.1:4000"]
+    }
+  }
+}
+```
+
+Example prompts once connected:
+
+- "Get the latest materializations for `silver/orders`."
+- "Fetch logs for run `abc-123`."
+- "Inspect the latest materialization for `silver/orders`."
+- "Get the latest materialization trace for `silver/orders`."
+- "Render the materialization trace tree for `silver/orders`."
+- "Get OTEL spans for run `abc-123`."
+- "Get failed Dagster spans for asset `silver/orders` in the last hour."
+- "Render the run trace tree for `abc-123`."
+- "Render a trace tree for job `daily_orders`."
+
+Run it over streamable HTTP:
+
+```bash
+phlo-mcp \
+  --transport streamable-http \
+  --host 127.0.0.1 \
+  --port 8000 \
+  --path /mcp \
+  --api-base-url http://127.0.0.1:4000
+```
+
+Optional local span capture:
+
+```bash
+phlo-mcp --trace-file .phlo/phlo-mcp-trace.jsonl
+```
+
+## Live stack smoke
+
+Run the MCP smoke against a live `phlo-api` service and its configured capability backends:
+
+```bash
+uv run python packages/phlo-mcp/tests/smoke_stack.py --start-stack
+```
+
+The smoke checks live `phlo-api`, orchestration connectivity, trace filtering
+through the observability capability, MCP tool registration, MCP resource
+registration, representative MCP resource reads, and a generated
+`mcp_smoke_asset` capability fixture.
+With `--start-stack`, the fixture is written to `.phlo/mcp-smoke-project`,
+which is ignored by git.
+
+When the configured observability backend requires credentials, pass them to
+the backing `phlo-api` process with that backend's environment variables.
+
+To verify guarded write-tool registration without calling mutation endpoints:
+
+```bash
+uv run python packages/phlo-mcp/tests/smoke_stack.py \
+  --enable-write-tools \
+  --api-token "$PHLO_MCP_SMOKE_API_TOKEN"
+```
+
+To call guarded write tools in dry-run mode, add `--exercise-write-tools` and
+`--start-stack`, or provide `--asset-key` when testing an existing project.
+This requires the backing `phlo-api` write endpoints to be available.
+
+```bash
+uv run python packages/phlo-mcp/tests/smoke_stack.py \
+  --start-stack \
+  --enable-write-tools \
+  --api-token "$PHLO_MCP_SMOKE_API_TOKEN" \
+  --exercise-write-tools
+```
+
+Use real data assertions when you have a known run or asset:
+
+```bash
+uv run python packages/phlo-mcp/tests/smoke_stack.py \
+  --run-id abc-123 \
+  --require-run-spans \
+  --asset-key silver/orders \
+  --require-materialization
+```

phlo_mcp-0.2.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+build-backend = "setuptools.build_meta"
+requires = [
+    "setuptools>=45",
+    "wheel",
+]
+
+[project]
+dependencies = [
+    "phlo>=0.1.0",
+    "phlo-api>=0.1.0",
+    "httpx>=0.28.1",
+    "mcp[cli]>=1.20.0",
+    "opentelemetry-sdk>=1.38.0",
+]
+description = "MCP server for Phlo observability and lakehouse operations"
+name = "phlo-mcp"
+requires-python = ">=3.11"
+version = "0.2.0"
+
+[[project.authors]]
+email = "team@phlo.dev"
+name = "Phlo Team"
+
+[project.license]
+text = "MIT"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "ruff>=0.1.0",
+]
+
+[project.readme]
+content-type = "text/plain"
+text = "MCP server for Phlo observability and lakehouse operations."
+
+[project.scripts]
+phlo-mcp = "phlo_mcp.cli:main"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.setuptools.packages.find]
+where = ["src"]

phlo_mcp-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

phlo_mcp-0.2.0/src/phlo_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""Phlo MCP package."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.2.0"

phlo_mcp-0.2.0/src/phlo_mcp/api_client.py

@@ -0,0 +1,189 @@
+"""HTTP client helpers for phlo-mcp."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+from opentelemetry import trace
+
+from phlo_mcp.config import McpConfig
+
+
+class PhloApiClient:
+    """Small typed wrapper around phlo-api observability routes."""
+
+    def __init__(self, config: McpConfig, *, tracer_name: str = "phlo.mcp") -> None:
+        self._config = config
+        self._tracer = trace.get_tracer(tracer_name)
+
+    @property
+    def api_base_url(self) -> str:
+        return self._config.api_base_url
+
+    @property
+    def headers(self) -> dict[str, str]:
+        if self._config.api_token:
+            return {"Authorization": f"Bearer {self._config.api_token}"}
+        return {}
+
+    def get_platform_health(self) -> dict[str, Any]:
+        return self._get_json("/api/observability/health")
+
+    def get_config(self) -> dict[str, Any] | list[dict[str, Any]]:
+        return self._get_json("/api/config")
+
+    def get_plugins(self) -> dict[str, Any] | list[dict[str, Any]]:
+        return self._get_json("/api/plugins")
+
+    def get_services(self) -> dict[str, Any] | list[dict[str, Any]]:
+        return self._get_json("/api/services")
+
+    def get_service_info(self, service_name: str) -> dict[str, Any] | list[dict[str, Any]]:
+        return self._get_json(f"/api/services/{service_name}")
+
+    def get_assets(self) -> dict[str, Any] | list[dict[str, Any]]:
+        return self._get_json("/api/dagster/assets")
+
+    def get_asset_details(self, asset_key_path: str) -> dict[str, Any] | list[dict[str, Any]]:
+        return self._get_json(f"/api/dagster/assets/{asset_key_path}")
+
+    def get_contracts(self) -> dict[str, Any] | list[dict[str, Any]]:
+        return self._get_json("/api/contracts")
+
+    def get_contract(self, table_name: str) -> dict[str, Any] | list[dict[str, Any]]:
+        return self._get_json(f"/api/contracts/{table_name}")
+
+    def get_service_status(self) -> list[dict[str, Any]] | dict[str, Any]:
+        return self._get_json("/api/observability/services")
+
+    def get_recent_alerts(self, limit: int = 5) -> list[dict[str, Any]] | dict[str, Any]:
+        return self._get_json("/api/observability/alerts", params={"limit": limit})
+
+    def get_dashboard_links(self) -> list[dict[str, Any]] | dict[str, Any]:
+        return self._get_json("/api/observability/dashboards")
+
+    def get_run_logs(
+        self,
+        run_id: str,
+        *,
+        level: str | None = None,
+        limit: int = 200,
+    ) -> dict[str, Any] | list[dict[str, Any]]:
+        params: dict[str, Any] = {"limit": limit}
+        if level:
+            params["level"] = level
+        return self._get_json(f"/api/loki/runs/{run_id}", params=params)
+
+    def get_materialization_history(
+        self,
+        asset_key_path: str,
+        *,
+        limit: int = 10,
+    ) -> dict[str, Any] | list[dict[str, Any]]:
+        return self._get_json(
+            f"/api/dagster/assets/{asset_key_path}/history", params={"limit": limit}
+        )
+
+    def get_run_trace_spans(
+        self,
+        run_id: str,
+        *,
+        limit: int = 500,
+    ) -> dict[str, Any] | list[dict[str, Any]]:
+        return self._get_json(f"/api/observability/traces/runs/{run_id}", params={"limit": limit})
+
+    def get_logs_query_link(self, service: str | None = None) -> dict[str, Any]:
+        params = {"service": service} if service else None
+        return self._get_json("/api/observability/links/logs", params=params)
+
+    def get_trace_spans(
+        self,
+        *,
+        run_id: str | None = None,
+        asset_key: str | None = None,
+        job_name: str | None = None,
+        service_name: str | None = None,
+        span_name: str | None = None,
+        status_code: str | None = None,
+        start_time: str | None = None,
+        end_time: str | None = None,
+        limit: int = 500,
+    ) -> dict[str, Any] | list[dict[str, Any]]:
+        params: dict[str, Any] = {"limit": limit}
+        for key, value in {
+            "run_id": run_id,
+            "asset_key": asset_key,
+            "job_name": job_name,
+            "service_name": service_name,
+            "span_name": span_name,
+            "status_code": status_code,
+            "start_time": start_time,
+            "end_time": end_time,
+        }.items():
+            if value:
+                params[key] = value
+        return self._get_json("/api/observability/traces", params=params)
+
+    def get_metrics_query_link(self, metric: str | None = None) -> dict[str, Any]:
+        params = {"metric": metric} if metric else None
+        return self._get_json("/api/observability/links/metrics", params=params)
+
+    def materialize_asset(
+        self,
+        asset_key_path: str,
+        *,
+        dry_run: bool = True,
+        partition_key: str | None = None,
+    ) -> dict[str, Any] | list[dict[str, Any]]:
+        payload: dict[str, Any] = {"dry_run": dry_run}
+        if partition_key:
+            payload["partition_key"] = partition_key
+        return self._post_json(f"/api/dagster/assets/{asset_key_path}/materialize", json=payload)
+
+    def retry_run(
+        self,
+        run_id: str,
+        *,
+        dry_run: bool = True,
+    ) -> dict[str, Any] | list[dict[str, Any]]:
+        return self._post_json(f"/api/dagster/runs/{run_id}/retry", json={"dry_run": dry_run})
+
+    def get_run_status(self, run_id: str) -> dict[str, Any] | list[dict[str, Any]]:
+        return self._get_json(f"/api/dagster/runs/{run_id}/status")
+
+    def _get_json(
+        self,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any] | list[dict[str, Any]]:
+        url = f"{self.api_base_url}{path}"
+        with self._tracer.start_as_current_span(
+            "http.client GET",
+            attributes={
+                "http.request.method": "GET",
+                "url.full": url,
+            },
+        ):
+            response = httpx.get(url, params=params, headers=self.headers, timeout=10.0)
+            response.raise_for_status()
+            return response.json()
+
+    def _post_json(
+        self,
+        path: str,
+        *,
+        json: dict[str, Any],
+    ) -> dict[str, Any] | list[dict[str, Any]]:
+        url = f"{self.api_base_url}{path}"
+        with self._tracer.start_as_current_span(
+            "http.client POST",
+            attributes={
+                "http.request.method": "POST",
+                "url.full": url,
+            },
+        ):
+            response = httpx.post(url, json=json, headers=self.headers, timeout=30.0)
+            response.raise_for_status()
+            return response.json()

phlo_mcp-0.2.0/src/phlo_mcp/cli.py

@@ -0,0 +1,55 @@
+"""CLI entrypoint for phlo-mcp."""
+
+from __future__ import annotations
+
+import argparse
+
+from phlo_mcp.config import McpConfig, config_from_env
+from phlo_mcp.server import create_server
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Run the Phlo MCP server")
+    parser.add_argument(
+        "--transport",
+        choices=("stdio", "streamable-http"),
+        help="MCP transport to use (defaults to PHLO_MCP_TRANSPORT or stdio)",
+    )
+    parser.add_argument("--api-base-url", help="Base URL for the backing phlo-api instance")
+    parser.add_argument("--api-token", help="Bearer token for authenticated phlo-api requests")
+    parser.add_argument(
+        "--enable-write-tools",
+        action="store_true",
+        help="Register guarded operational tools (requires authenticated phlo-api)",
+    )
+    parser.add_argument("--trace-file", help="Optional JSONL file to write local span events")
+    parser.add_argument("--host", help="Bind host for streamable-http transport")
+    parser.add_argument("--port", type=int, help="Bind port for streamable-http transport")
+    parser.add_argument("--path", help="HTTP path for streamable-http transport (default: /mcp)")
+    return parser
+
+
+def parse_args() -> McpConfig:
+    parser = build_parser()
+    args = parser.parse_args()
+    env_config = config_from_env()
+    return McpConfig(
+        api_base_url=(args.api_base_url or env_config.api_base_url).rstrip("/"),
+        api_token=args.api_token if args.api_token is not None else env_config.api_token,
+        enable_write_tools=args.enable_write_tools or env_config.enable_write_tools,
+        trace_file=args.trace_file if args.trace_file is not None else env_config.trace_file,
+        transport=args.transport or env_config.transport,
+        host=args.host or env_config.host,
+        port=args.port if args.port is not None else env_config.port,
+        streamable_http_path=args.path or env_config.streamable_http_path,
+    )
+
+
+def main() -> None:
+    config = parse_args()
+    server = create_server(config)
+    server.run(transport=config.transport)
+
+
+if __name__ == "__main__":
+    main()

phlo_mcp-0.2.0/src/phlo_mcp/config.py

@@ -0,0 +1,41 @@
+"""Configuration helpers for phlo-mcp."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+_DEFAULT_API_BASE_URL = "http://127.0.0.1:4000"
+
+
+@dataclass(frozen=True, slots=True)
+class McpConfig:
+    """Runtime configuration for the Phlo MCP server."""
+
+    api_base_url: str = _DEFAULT_API_BASE_URL
+    api_token: str | None = None
+    enable_write_tools: bool = False
+    trace_file: str | None = None
+    transport: str = "stdio"
+    host: str = "127.0.0.1"
+    port: int = 8000
+    streamable_http_path: str = "/mcp"
+
+
+def _truthy_env(name: str) -> bool:
+    return os.environ.get(name, "").lower() in {"1", "true", "yes", "on"}
+
+
+def config_from_env() -> McpConfig:
+    """Load MCP configuration from environment variables."""
+    port = int(os.environ.get("PHLO_MCP_PORT", "8000"))
+    return McpConfig(
+        api_base_url=os.environ.get("PHLO_MCP_API_BASE_URL", _DEFAULT_API_BASE_URL).rstrip("/"),
+        api_token=os.environ.get("PHLO_MCP_API_TOKEN") or None,
+        enable_write_tools=_truthy_env("PHLO_MCP_ENABLE_WRITE_TOOLS"),
+        trace_file=os.environ.get("PHLO_MCP_TRACE_FILE") or None,
+        transport=os.environ.get("PHLO_MCP_TRANSPORT", "stdio"),
+        host=os.environ.get("PHLO_MCP_HOST", "127.0.0.1"),
+        port=port,
+        streamable_http_path=os.environ.get("PHLO_MCP_HTTP_PATH", "/mcp"),
+    )