datajunction 0.0.147__tar.gz → 0.0.148__tar.gz

{datajunction-0.0.147 → datajunction-0.0.148}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datajunction
-Version: 0.0.147
+Version: 0.0.148
 Summary: DataJunction client library for connecting to a DataJunction server
 Project-URL: repository, https://github.com/DataJunction/dj
 Author-email: DataJunction Authors <yian.shang@gmail.com>
@@ -20,7 +20,6 @@ Requires-Dist: requests<3.0.0,>=2.28.2
 Requires-Dist: rich>=13.7.0
 Provides-Extra: mcp
 Requires-Dist: mcp>=1.0.0; extra == 'mcp'
-Requires-Dist: plotext>=5.2.8; extra == 'mcp'
 Requires-Dist: pydantic-settings>=2.10.1; extra == 'mcp'
 Requires-Dist: pydantic>=2.0; extra == 'mcp'
 Provides-Extra: pandas

{datajunction-0.0.147 → datajunction-0.0.148}/datajunction/__about__.py

@@ -2,4 +2,4 @@
 Version for Hatch
 """
 
-__version__ = "0.0.147"
+__version__ = "0.0.148"

datajunction-0.0.148/datajunction/mcp/__init__.py

@@ -0,0 +1,12 @@
+"""
+DataJunction MCP stdio→HTTP proxy.
+
+The canonical MCP server is hosted by ``datajunction-server`` at the
+``/mcp`` endpoint (Streamable HTTP transport). This package provides a
+small ``dj-mcp`` CLI that bridges stdio MCP clients (e.g. Claude Desktop)
+to the hosted server, so users on stdio-only clients can still talk to a
+deployed DJ.
+
+For HTTP-capable clients (Claude Code, Cursor, Slack agents) connect to
+the hosted ``/mcp`` endpoint directly — no local CLI required.
+"""

datajunction-0.0.148/datajunction/mcp/cli.py

@@ -0,0 +1,135 @@
+"""
+Stdio→HTTP proxy for the DataJunction MCP server.
+
+The server-side MCP implementation now lives in ``datajunction-server``
+(`/mcp` endpoint, Streamable HTTP transport). This CLI exists so users on
+clients that only speak stdio (e.g. Claude Desktop today) can still talk
+to a hosted DJ MCP without running anything heavyweight locally.
+
+It opens an HTTP MCP client to the configured hosted endpoint, hosts a
+stdio MCP server, and forwards every list_tools / call_tool / list_resources /
+read_resource request to the upstream. The wire shape is identical, so
+clients see the same tool surface as the hosted server exposes.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import sys
+
+import mcp.types as types
+from mcp.client.session import ClientSession
+from mcp.client.streamable_http import streamablehttp_client
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+
+from datajunction.mcp.config import get_mcp_settings
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    stream=sys.stderr,  # stdout is reserved for MCP protocol traffic
+)
+logger = logging.getLogger(__name__)
+
+
+async def _proxy_list_tools(upstream: ClientSession) -> list[types.Tool]:
+    """Forward ``tools/list`` to the upstream session."""
+    result = await upstream.list_tools()
+    return list(result.tools)
+
+
+async def _proxy_call_tool(
+    upstream: ClientSession,
+    name: str,
+    arguments: dict,
+) -> list[types.ContentBlock]:
+    """Forward ``tools/call`` to the upstream session.
+
+    ``result.content`` may be a tuple/list of content blocks; normalize to list.
+    """
+    result = await upstream.call_tool(name, arguments=arguments or {})
+    return list(result.content)
+
+
+async def _proxy_list_resources(upstream: ClientSession) -> list[types.Resource]:
+    """Forward ``resources/list`` to the upstream session."""
+    result = await upstream.list_resources()
+    return list(result.resources)
+
+
+async def _proxy_read_resource(upstream: ClientSession, uri: str) -> str:
+    """Forward ``resources/read`` and surface the first text payload.
+
+    The hosted DJ doesn't expose any resources today, but if it ever does
+    we return the first ``text`` content block.
+    """
+    result = await upstream.read_resource(uri)  # type: ignore[arg-type]
+    for block in result.contents:
+        text = getattr(block, "text", None)
+        if text is not None:
+            return text
+    return ""  # pragma: no cover
+
+
+def _build_proxy_app(upstream: ClientSession) -> Server:
+    """Create an MCP ``Server`` whose handlers all forward to ``upstream``.
+
+    Split out from ``_serve`` so the wiring is testable without spinning
+    up stdio.
+    """
+    app: Server = Server("datajunction")
+    app.list_tools()(lambda: _proxy_list_tools(upstream))
+    app.call_tool()(
+        lambda name, arguments: _proxy_call_tool(upstream, name, arguments),
+    )
+    app.list_resources()(lambda: _proxy_list_resources(upstream))
+    app.read_resource()(lambda uri: _proxy_read_resource(upstream, uri))
+    return app
+
+
+async def _serve(upstream: ClientSession) -> None:
+    """Run a stdio MCP server that forwards every request to ``upstream``."""
+    app = _build_proxy_app(upstream)
+    async with stdio_server() as (read_stream, write_stream):
+        await app.run(
+            read_stream,
+            write_stream,
+            app.create_initialization_options(),
+        )
+
+
+async def main() -> None:
+    """Connect to the hosted DJ MCP and bridge it to stdio."""
+    settings = get_mcp_settings()
+
+    headers = {}
+    if settings.dj_api_token:
+        headers["Authorization"] = f"Bearer {settings.dj_api_token}"
+
+    logger.info("Bridging stdio MCP → %s", settings.mcp_url)
+
+    async with streamablehttp_client(
+        url=settings.mcp_url,
+        headers=headers or None,
+        timeout=settings.request_timeout,
+    ) as (read, write, _get_session_id):
+        async with ClientSession(read, write) as upstream:
+            await upstream.initialize()
+            await _serve(upstream)
+
+
+def run() -> None:
+    """Synchronous entrypoint for ``dj-mcp`` script registration."""
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        logger.info("dj-mcp stopped by user")
+    except Exception as exc:
+        logger.error("dj-mcp error: %s", exc, exc_info=True)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    run()

datajunction-0.0.148/datajunction/mcp/config.py

@@ -0,0 +1,71 @@
+"""
+Configuration for the DataJunction MCP stdio→HTTP proxy CLI.
+
+The CLI connects to a hosted DJ ``/mcp`` endpoint over Streamable HTTP and
+re-exposes its tools to local stdio MCP clients (e.g. Claude Desktop).
+
+Settings are read from env on every ``get_mcp_settings()`` call (no caching),
+so override behavior is predictable in tests and shell-set values are picked
+up at startup.
+
+Resolution order for the upstream MCP URL:
+
+1. ``DJ_MCP_URL`` if set — full URL of the ``/mcp`` endpoint.
+2. ``DJ_API_URL`` if set — backwards-compatible fallback for users of the
+   pre-migration ``dj-mcp`` CLI. We append ``/mcp`` to it.
+3. ``http://localhost:8000/mcp`` — local-dev default.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+def _resolve_default_mcp_url() -> str:
+    """Fall back to the legacy ``DJ_API_URL`` env var when ``DJ_MCP_URL``
+    is unset.
+
+    Pre-migration deployments configured the stdio CLI with ``DJ_API_URL``
+    (the base DJ API URL); the new CLI talks directly to ``/mcp``. We read
+    ``DJ_API_URL`` and append the path so existing setups don't silently
+    break.
+
+    Pydantic-settings reads ``DJ_MCP_URL`` via the field alias before this
+    factory fires, so we only need to handle the legacy + default cases.
+    """
+    legacy = os.environ.get("DJ_API_URL")
+    if legacy:
+        return legacy.rstrip("/") + "/mcp"
+    return "http://localhost:8000/mcp"
+
+
+class MCPSettings(BaseSettings):
+    """Settings for the dj-mcp stdio CLI."""
+
+    # Hosted DJ MCP endpoint. Override with ``DJ_MCP_URL``; ``DJ_API_URL``
+    # is accepted as a backwards-compatible fallback (see module docstring).
+    mcp_url: str = Field(
+        default_factory=_resolve_default_mcp_url,
+        alias="DJ_MCP_URL",
+    )
+
+    # Bearer token forwarded as Authorization on every upstream request.
+    # Use ``DJ_API_TOKEN`` to align with the rest of the DJ tooling.
+    dj_api_token: Optional[str] = Field(default=None, alias="DJ_API_TOKEN")
+
+    # Request timeout for upstream calls.
+    request_timeout: float = 30.0
+
+    model_config = SettingsConfigDict(
+        case_sensitive=False,
+        populate_by_name=True,
+    )
+
+
+def get_mcp_settings() -> MCPSettings:
+    """Return MCP settings. Re-reads env on every call."""
+    return MCPSettings()

{datajunction-0.0.147 → datajunction-0.0.148}/pyproject.toml

@@ -30,11 +30,14 @@ classifiers = [
 
 [project.optional-dependencies]
 pandas = ["pandas>=2.0.2"]
+# Optional dependencies for the dj-mcp stdio→HTTP proxy CLI. plotext was
+# previously needed for client-side rendering of `visualize_metrics`; that
+# logic now lives server-side in datajunction-server, so the client only
+# needs the MCP SDK + pydantic-settings to read env-var configuration.
 mcp = [
     "mcp>=1.0.0",
     "pydantic>=2.0",
     "pydantic-settings>=2.10.1",
-    "plotext>=5.2.8",
 ]
 
 [tool.hatch.version]
@@ -90,5 +93,5 @@ test = [
     "nbformat>=5.10.4",
     "sqlglot>=18.0.1",
     "pydantic-settings>=2.11.0",
-    "mcp>=1.0.0",  # For MCP tests
+    "mcp>=1.0.0",  # For dj-mcp proxy CLI tests
 ]

datajunction-0.0.148/tests/mcp/README.md

@@ -0,0 +1,16 @@
+# dj-mcp CLI tests
+
+The DataJunction MCP server is hosted in `datajunction-server` at the
+`/mcp` endpoint (Streamable HTTP transport). The client package only
+ships a thin stdio→HTTP proxy CLI (`dj-mcp`) for stdio-only MCP clients
+like Claude Desktop.
+
+These tests cover the proxy wiring:
+
+- env vars (`DJ_API_TOKEN`, `DJ_MCP_URL`) → upstream URL + Authorization header
+- `run()` invokes `asyncio.run(main())`
+
+End-to-end tool behavior is covered server-side under
+`datajunction-server/tests/dj_mcp/`. There's no per-tool coverage here
+because the CLI doesn't implement tools — it forwards every request to
+the hosted server.

datajunction-0.0.148/tests/mcp/test_cli.py

@@ -0,0 +1,285 @@
+"""
+Tests for the dj-mcp stdio→HTTP proxy CLI.
+
+The CLI delegates everything to a hosted DJ MCP server via Streamable HTTP.
+We just verify the wiring: settings → headers, upstream connect, stdio
+bridge runs. Actual tool behavior is tested in datajunction-server's
+``tests/dj_mcp/`` suite.
+"""
+
+from unittest.mock import AsyncMock, MagicMock
+
+import mcp.types as types
+import pytest
+from mcp.server import Server
+
+from datajunction.mcp import cli
+
+
+def test_dj_api_url_backwards_compat(monkeypatch) -> None:
+    """Pre-migration deployments set ``DJ_API_URL``; the new CLI honours
+    it and appends ``/mcp`` so existing setups don't silently break."""
+    from datajunction.mcp.config import get_mcp_settings
+
+    monkeypatch.delenv("DJ_MCP_URL", raising=False)
+    monkeypatch.setenv("DJ_API_URL", "https://dj.example.com")
+    assert get_mcp_settings().mcp_url == "https://dj.example.com/mcp"
+
+
+def test_dj_mcp_url_takes_precedence_over_dj_api_url(monkeypatch) -> None:
+    """If both are set, ``DJ_MCP_URL`` wins — no surprise when explicitly configured."""
+    from datajunction.mcp.config import get_mcp_settings
+
+    monkeypatch.setenv("DJ_MCP_URL", "https://override/mcp")
+    monkeypatch.setenv("DJ_API_URL", "https://legacy")
+    assert get_mcp_settings().mcp_url == "https://override/mcp"
+
+
+def test_default_mcp_url_when_neither_set(monkeypatch) -> None:
+    """No env vars → localhost default."""
+    from datajunction.mcp.config import get_mcp_settings
+
+    monkeypatch.delenv("DJ_MCP_URL", raising=False)
+    monkeypatch.delenv("DJ_API_URL", raising=False)
+    assert get_mcp_settings().mcp_url == "http://localhost:8000/mcp"
+
+
+@pytest.mark.asyncio
+async def test_main_connects_with_bearer_token_when_set(monkeypatch):
+    """When DJ_API_TOKEN is set, it's forwarded as an Authorization header."""
+    monkeypatch.setenv("DJ_API_TOKEN", "test-token")
+    monkeypatch.setenv("DJ_MCP_URL", "http://example.com/mcp")
+
+    captured: dict = {}
+
+    class _FakeStreamCtx:
+        async def __aenter__(self):
+            return (MagicMock(), MagicMock(), lambda: None)
+
+        async def __aexit__(self, *exc):
+            return False
+
+    def fake_streamablehttp_client(url, headers=None, timeout=None):
+        captured["url"] = url
+        captured["headers"] = headers
+        return _FakeStreamCtx()
+
+    class _FakeSessionCtx:
+        def __init__(self, *a, **kw):
+            pass
+
+        async def __aenter__(self):
+            session = MagicMock()
+            session.initialize = AsyncMock()
+            return session
+
+        async def __aexit__(self, *exc):
+            return False
+
+    monkeypatch.setattr(cli, "streamablehttp_client", fake_streamablehttp_client)
+    monkeypatch.setattr(cli, "ClientSession", _FakeSessionCtx)
+    monkeypatch.setattr(cli, "_serve", AsyncMock())
+
+    await cli.main()
+
+    assert captured["url"] == "http://example.com/mcp"
+    assert captured["headers"] == {"Authorization": "Bearer test-token"}
+
+
+@pytest.mark.asyncio
+async def test_main_without_token_omits_auth_header(monkeypatch):
+    """No DJ_API_TOKEN → no Authorization header (None passed to httpx)."""
+    monkeypatch.delenv("DJ_API_TOKEN", raising=False)
+    monkeypatch.setenv("DJ_MCP_URL", "http://example.com/mcp")
+
+    captured: dict = {}
+
+    class _FakeStreamCtx:
+        async def __aenter__(self):
+            return (MagicMock(), MagicMock(), lambda: None)
+
+        async def __aexit__(self, *exc):
+            return False
+
+    def fake_streamablehttp_client(url, headers=None, timeout=None):
+        captured["headers"] = headers
+        return _FakeStreamCtx()
+
+    class _FakeSessionCtx:
+        def __init__(self, *a, **kw):
+            pass
+
+        async def __aenter__(self):
+            session = MagicMock()
+            session.initialize = AsyncMock()
+            return session
+
+        async def __aexit__(self, *exc):
+            return False
+
+    monkeypatch.setattr(cli, "streamablehttp_client", fake_streamablehttp_client)
+    monkeypatch.setattr(cli, "ClientSession", _FakeSessionCtx)
+    monkeypatch.setattr(cli, "_serve", AsyncMock())
+
+    await cli.main()
+    assert captured["headers"] is None
+
+
+def test_run_invokes_asyncio_run(monkeypatch):
+    """``run()`` is the script entrypoint — it should drive ``main()`` via asyncio."""
+
+    invoked = {}
+
+    def fake_asyncio_run(coro):
+        invoked["called"] = True
+        coro.close()  # avoid "coroutine was never awaited" warning
+
+    monkeypatch.setattr(cli.asyncio, "run", fake_asyncio_run)
+    cli.run()
+    assert invoked["called"]
+
+
+def test_run_swallows_keyboard_interrupt(monkeypatch):
+    """``Ctrl-C`` in the CLI should log and exit cleanly, not propagate."""
+
+    def fake_asyncio_run(coro):
+        coro.close()
+        raise KeyboardInterrupt
+
+    monkeypatch.setattr(cli.asyncio, "run", fake_asyncio_run)
+    cli.run()  # must not raise
+
+
+def test_run_logs_and_exits_on_unhandled_exception(monkeypatch):
+    """Any other exception is logged and the process exits with code 1."""
+
+    def fake_asyncio_run(coro):
+        coro.close()
+        raise RuntimeError("boom")
+
+    exits: list = []
+
+    def fake_exit(code):
+        exits.append(code)
+
+    monkeypatch.setattr(cli.asyncio, "run", fake_asyncio_run)
+    monkeypatch.setattr(cli.sys, "exit", fake_exit)
+    cli.run()
+    assert exits == [1]
+
+
+# ---------------------------------------------------------------------------
+# Proxy handlers — verify each MCP method forwards to the upstream session
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_proxy_list_tools_forwards_to_upstream():
+    """``list_tools`` returns the upstream's tools verbatim, normalised to list."""
+
+    upstream = MagicMock()
+    upstream.list_tools = AsyncMock(
+        return_value=MagicMock(
+            tools=(
+                types.Tool(name="foo", description="d", inputSchema={"type": "object"}),
+            ),
+        ),
+    )
+
+    out = await cli._proxy_list_tools(upstream)
+    assert [t.name for t in out] == ["foo"]
+    upstream.list_tools.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_proxy_call_tool_forwards_arguments():
+    """``call_tool`` forwards (name, arguments) and returns the content list."""
+
+    upstream = MagicMock()
+    block = types.TextContent(type="text", text="ok")
+    upstream.call_tool = AsyncMock(return_value=MagicMock(content=(block,)))
+
+    out = await cli._proxy_call_tool(upstream, "foo", {"k": "v"})
+    assert out == [block]
+    upstream.call_tool.assert_awaited_once_with("foo", arguments={"k": "v"})
+
+
+@pytest.mark.asyncio
+async def test_proxy_call_tool_normalises_none_arguments():
+    """If ``arguments`` is None it's coerced to an empty dict before forwarding."""
+
+    upstream = MagicMock()
+    upstream.call_tool = AsyncMock(return_value=MagicMock(content=()))
+
+    out = await cli._proxy_call_tool(upstream, "foo", None)  # type: ignore[arg-type]
+    assert out == []
+    upstream.call_tool.assert_awaited_once_with("foo", arguments={})
+
+
+@pytest.mark.asyncio
+async def test_proxy_list_resources_forwards_to_upstream():
+    """``list_resources`` returns the upstream's resources verbatim."""
+
+    upstream = MagicMock()
+    res = types.Resource(uri="dj://x", name="x")
+    upstream.list_resources = AsyncMock(return_value=MagicMock(resources=(res,)))
+
+    out = await cli._proxy_list_resources(upstream)
+    assert out == [res]
+
+
+@pytest.mark.asyncio
+async def test_proxy_read_resource_returns_first_text_block():
+    """``read_resource`` surfaces the first ``text`` block in the upstream response."""
+
+    upstream = MagicMock()
+    block_no_text = MagicMock(spec=[])  # no .text attribute
+    block_with_text = MagicMock()
+    block_with_text.text = "hello"
+    upstream.read_resource = AsyncMock(
+        return_value=MagicMock(contents=[block_no_text, block_with_text]),
+    )
+
+    out = await cli._proxy_read_resource(upstream, "dj://x")
+    assert out == "hello"
+
+
+@pytest.mark.asyncio
+async def test_build_proxy_app_registers_all_four_handlers():
+    """``_build_proxy_app`` returns a Server with handlers for every MCP method."""
+
+    upstream = MagicMock()
+    app = cli._build_proxy_app(upstream)
+    assert isinstance(app, Server)
+    # The MCP SDK stores registered handlers in ``request_handlers`` keyed by
+    # the request type. We just need to confirm all four are wired.
+    handler_count = len(app.request_handlers)
+    assert handler_count >= 4
+
+
+@pytest.mark.asyncio
+async def test_serve_drives_app_run_with_stdio_streams(monkeypatch):
+    """``_serve`` opens stdio_server, builds the proxy app, runs it. Stub
+    everything so we just verify the wiring."""
+
+    sentinel_app = MagicMock()
+    sentinel_app.run = AsyncMock()
+    sentinel_app.create_initialization_options = MagicMock(return_value="opts")
+
+    monkeypatch.setattr(cli, "_build_proxy_app", lambda upstream: sentinel_app)
+
+    class _StdioCtx:
+        async def __aenter__(self):
+            return ("read-stream", "write-stream")
+
+        async def __aexit__(self, *exc):
+            return False
+
+    monkeypatch.setattr(cli, "stdio_server", lambda: _StdioCtx())
+
+    await cli._serve(MagicMock())
+    sentinel_app.run.assert_awaited_once_with(
+        "read-stream",
+        "write-stream",
+        "opts",
+    )

datajunction-0.0.147/datajunction/mcp/__init__.py

@@ -1,6 +0,0 @@
-"""
-DataJunction MCP (Model Context Protocol) Server
-
-This module provides an MCP server for AI agents to interact with the
-DataJunction semantic layer.
-"""

datajunction-0.0.147/datajunction/mcp/cli.py

@@ -1,52 +0,0 @@
-"""
-CLI entry point for DataJunction MCP Server
-"""
-
-import asyncio
-import logging
-import sys
-
-from mcp.server.stdio import stdio_server
-
-from datajunction.mcp.server import app
-from datajunction.mcp.config import get_mcp_settings
-
-# Configure logging
-logging.basicConfig(
-    level=logging.INFO,
-    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
-    stream=sys.stderr,  # Log to stderr so stdout is clean for MCP protocol
-)
-
-logger = logging.getLogger(__name__)
-
-
-async def main():
-    """Main entry point for MCP server"""
-    settings = get_mcp_settings()
-
-    logger.info("Starting DataJunction MCP Server")
-    logger.info(f"Connecting to DJ API at: {settings.dj_api_url}")
-
-    # Run the MCP server using stdio transport
-    async with stdio_server() as (read_stream, write_stream):
-        await app.run(
-            read_stream,
-            write_stream,
-            app.create_initialization_options(),
-        )
-
-
-def run():
-    """Synchronous wrapper for async main"""
-    try:
-        asyncio.run(main())
-    except KeyboardInterrupt:
-        logger.info("MCP Server stopped by user")
-    except Exception as e:
-        logger.error(f"MCP Server error: {str(e)}", exc_info=True)
-        sys.exit(1)
-
-
-if __name__ == "__main__":
-    run()

datajunction-0.0.147/datajunction/mcp/config.py

@@ -1,27 +0,0 @@
-"""
-Configuration for DataJunction MCP Server
-"""
-
-import os
-from typing import Optional
-from pydantic_settings import BaseSettings
-
-
-class MCPSettings(BaseSettings):
-    """Settings for MCP server"""
-
-    # DJ API connection
-    dj_api_url: str = os.getenv("DJ_API_URL", "http://localhost:8000")
-    dj_api_token: Optional[str] = os.getenv("DJ_API_TOKEN")
-
-    # Optional: Basic auth (if not using token)
-    dj_username: Optional[str] = os.getenv("DJ_USERNAME")
-    dj_password: Optional[str] = os.getenv("DJ_PASSWORD")
-
-    # Request timeout
-    request_timeout: int = 30
-
-
-def get_mcp_settings() -> MCPSettings:
-    """Get MCP settings singleton"""
-    return MCPSettings()