nxd-tools 0.1.0__tar.gz

nxd_tools-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,61 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          uv pip install --system -e ".[dev,mcp-bridge]"
+
+      - name: Run ruff check
+        run: ruff check .
+
+      - name: Run ruff format check
+        run: ruff format --check .
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          uv pip install --system -e ".[mcp-bridge]"
+
+      - name: Verify installation
+        run: |
+          python -c "import nxd_tools; print(nxd_tools.__version__)"
+          python -m nxd_tools.mcp_bridge --help || true
+          nxd-bridge --help || true

nxd_tools-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,58 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: read
+  id-token: write  # Required for trusted publishing
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build dependencies
+        run: |
+          uv pip install --system build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+          # repository-url: https://test.pypi.org/legacy/ # For testing

nxd_tools-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

nxd_tools-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,31 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.4
+    hooks:
+      # Run the linter
+      - id: ruff
+        args: [--fix]
+      # Run the formatter
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: check-toml
+
+ci:
+  autofix_commit_msg: |
+    [pre-commit.ci] auto fixes from pre-commit.com hooks
+
+    for more information, see https://pre-commit.ci
+  autofix_prs: true
+  autoupdate_branch: ''
+  autoupdate_commit_msg: '[pre-commit.ci] pre-commit autoupdate'
+  autoupdate_schedule: weekly
+  skip: []
+  submodules: false

nxd_tools-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

nxd_tools-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nextdata
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nxd_tools-0.1.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: nxd-tools
+Version: 0.1.0
+Summary: Collection of tools for working with MCP and other protocols
+Author-email: Nextdata <dev@nextdata.com>
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: pre-commit>=4.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Provides-Extra: mcp-bridge
+Requires-Dist: anyio>=4.8.0; extra == 'mcp-bridge'
+Requires-Dist: httpx>=0.28.1; extra == 'mcp-bridge'
+Requires-Dist: mcp>=1.1.2; extra == 'mcp-bridge'
+Description-Content-Type: text/markdown
+
+# nxd-tools
+
+Collection of tools for working with MCP (Model Context Protocol) and other protocols.
+
+## Installation
+
+```bash
+# Install the MCP bridge
+pip install nxd-tools[mcp-bridge]
+
+# Or with uv
+uv pip install nxd-tools[mcp-bridge]
+```
+
+## Components
+
+### MCP Bridge (`nxd-tools[mcp-bridge]`)
+
+A stdio-to-HTTP proxy that enables stdio-based MCP clients (like Claude Desktop) to communicate with remote streamable HTTP MCP servers.
+
+**Usage:**
+
+```bash
+# Using the console script
+nxd-bridge --base-url https://server.example.com --token YOUR_TOKEN
+
+# Using module invocation
+python -m nxd_tools.mcp_bridge --base-url https://server.example.com --token YOUR_TOKEN
+
+# Disable SSL verification (for development)
+nxd-bridge --base-url https://server.example.com --token YOUR_TOKEN --no-ssl-verify
+```
+
+**Claude Desktop Configuration:**
+
+Add to your Claude Desktop MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "my-remote-server": {
+      "command": "nxd-bridge",
+      "args": [
+        "--base-url",
+        "https://server.example.com",
+        "--token",
+        "YOUR_TOKEN"
+      ]
+    }
+  }
+}
+```
+
+## Development
+
+```bash
+# Install with dev dependencies
+uv pip install -e ".[dev,mcp-bridge]"
+
+# Install pre-commit hooks
+pre-commit install
+
+# Run quality checks
+ruff check . --fix
+ruff format .
+
+# Build package
+python -m build
+```

nxd_tools-0.1.0/README.md

@@ -0,0 +1,69 @@
+# nxd-tools
+
+Collection of tools for working with MCP (Model Context Protocol) and other protocols.
+
+## Installation
+
+```bash
+# Install the MCP bridge
+pip install nxd-tools[mcp-bridge]
+
+# Or with uv
+uv pip install nxd-tools[mcp-bridge]
+```
+
+## Components
+
+### MCP Bridge (`nxd-tools[mcp-bridge]`)
+
+A stdio-to-HTTP proxy that enables stdio-based MCP clients (like Claude Desktop) to communicate with remote streamable HTTP MCP servers.
+
+**Usage:**
+
+```bash
+# Using the console script
+nxd-bridge --base-url https://server.example.com --token YOUR_TOKEN
+
+# Using module invocation
+python -m nxd_tools.mcp_bridge --base-url https://server.example.com --token YOUR_TOKEN
+
+# Disable SSL verification (for development)
+nxd-bridge --base-url https://server.example.com --token YOUR_TOKEN --no-ssl-verify
+```
+
+**Claude Desktop Configuration:**
+
+Add to your Claude Desktop MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "my-remote-server": {
+      "command": "nxd-bridge",
+      "args": [
+        "--base-url",
+        "https://server.example.com",
+        "--token",
+        "YOUR_TOKEN"
+      ]
+    }
+  }
+}
+```
+
+## Development
+
+```bash
+# Install with dev dependencies
+uv pip install -e ".[dev,mcp-bridge]"
+
+# Install pre-commit hooks
+pre-commit install
+
+# Run quality checks
+ruff check . --fix
+ruff format .
+
+# Build package
+python -m build
+```

nxd_tools-0.1.0/nxd_tools/__init__.py

@@ -0,0 +1,3 @@
+"""nxd-tools: A collection of tools for working with MCP and other protocols."""
+
+__version__ = "0.1.0"

nxd_tools-0.1.0/nxd_tools/__main__.py

@@ -0,0 +1,16 @@
+"""Main entry point for python -m nxd_tools."""
+
+import sys
+
+
+def main():
+    """Main entry point showing available subcommands."""
+    print("nxd-tools: Available commands:")
+    print("  python -m nxd_tools.mcp_bridge  - Run the MCP stdio bridge")
+    print("\nOr use the console scripts:")
+    print("  nxd-bridge                       - Run the MCP stdio bridge")
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

nxd_tools-0.1.0/nxd_tools/mcp_bridge/__init__.py

@@ -0,0 +1,5 @@
+"""MCP stdio bridge for proxying to remote HTTP MCP servers."""
+
+from nxd_tools.mcp_bridge.bridge import main
+
+__all__ = ["main"]

nxd_tools-0.1.0/nxd_tools/mcp_bridge/__main__.py

@@ -0,0 +1,8 @@
+"""Main entry point for python -m nxd_tools.mcp_bridge."""
+
+import sys
+
+from nxd_tools.mcp_bridge.bridge import main
+
+if __name__ == "__main__":
+    sys.exit(main())

nxd_tools-0.1.0/nxd_tools/mcp_bridge/bridge.py

@@ -0,0 +1,142 @@
+"""
+MCP stdio bridge for Claude Desktop.
+Creates a stdio MCP server that proxies all requests to a remote streamable HTTP MCP server.
+"""
+
+import argparse
+import asyncio
+import logging
+from contextlib import AsyncExitStack
+
+import httpx
+from mcp import ClientSession
+from mcp.client.streamable_http import streamablehttp_client
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import Tool
+
+# Set up logging
+logging.basicConfig(
+    level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+)
+logger = logging.getLogger(__name__)
+
+
+class MCPProxyServer:
+    """MCP server that proxies to a remote streamable HTTP MCP server."""
+
+    def __init__(self, base_url: str, token: str, no_ssl_verify: bool = False):
+        self.base_url = base_url
+        self.token = token
+        self.no_ssl_verify = no_ssl_verify
+        self.mcp_url = f"{base_url}/mcp"
+        self.server = Server("mcp-stdio-bridge")
+        self.remote_session: ClientSession | None = None
+        self.tools_cache: list[Tool] = []
+        self.exit_stack = AsyncExitStack()
+
+        # Register handlers
+        self.server.list_tools()(self.handle_list_tools)
+        self.server.call_tool()(self.handle_call_tool)
+
+    def create_httpx_client(self, headers=None, timeout=None, auth=None):
+        """Create httpx client with SSL verification settings."""
+        return httpx.AsyncClient(
+            verify=not self.no_ssl_verify,
+            headers=headers,
+            timeout=timeout or 30.0,
+            auth=auth,
+        )
+
+    async def connect_to_remote(self):
+        """Connect to the remote MCP server."""
+        logger.info(f"Connecting to remote MCP server at {self.mcp_url}")
+        headers = {"X-Nextdata-Token": self.token}
+
+        # Use AsyncExitStack to properly manage context managers
+        read_stream, write_stream, _ = await self.exit_stack.enter_async_context(
+            streamablehttp_client(
+                self.mcp_url,
+                headers=headers,
+                httpx_client_factory=self.create_httpx_client,
+            )
+        )
+
+        # Create and enter the client session context
+        self.remote_session = await self.exit_stack.enter_async_context(
+            ClientSession(read_stream, write_stream)
+        )
+
+        # Initialize the remote session
+        await self.remote_session.initialize()
+        logger.info("Remote MCP session initialized successfully")
+
+        # Cache available tools
+        tools_result = await self.remote_session.list_tools()
+        self.tools_cache = tools_result.tools
+        logger.info(f"Cached {len(self.tools_cache)} tools from remote server")
+
+    async def handle_list_tools(self) -> list[Tool]:
+        """Handle list_tools request by returning cached tools from remote server."""
+        logger.info(f"Handling list_tools request, returning {len(self.tools_cache)} tools")
+        return self.tools_cache
+
+    async def handle_call_tool(self, name: str, arguments: dict):
+        """Handle call_tool request by proxying to remote server."""
+        logger.info(f"Handling call_tool request for {name} with args: {arguments}")
+
+        if not self.remote_session:
+            raise RuntimeError("Not connected to remote server")
+
+        # Call the tool on the remote server
+        result = await self.remote_session.call_tool(name, arguments)
+
+        if result.isError:
+            logger.error(f"Tool call failed: {result.content}")
+            raise RuntimeError(f"Tool call failed: {result.content}")
+
+        logger.info(f"Tool call successful, returning {len(result.content)} content items")
+        return result.content
+
+    async def cleanup(self):
+        """Clean up all connections."""
+        await self.exit_stack.aclose()
+
+
+async def async_main(args):
+    """Async main function."""
+    # Create proxy server
+    proxy = MCPProxyServer(args.base_url, args.token, args.no_ssl_verify)
+
+    try:
+        # Connect to remote server first
+        await proxy.connect_to_remote()
+
+        # Run stdio server
+        logger.info("Starting stdio MCP server...")
+        async with stdio_server() as (read_stream, write_stream):
+            await proxy.server.run(
+                read_stream, write_stream, proxy.server.create_initialization_options()
+            )
+    except KeyboardInterrupt:
+        logger.info("Shutting down...")
+    except Exception as e:
+        logger.error(f"Error running MCP bridge: {e}", exc_info=True)
+        raise
+    finally:
+        await proxy.cleanup()
+
+
+def main():
+    """Main entry point for the MCP bridge."""
+    parser = argparse.ArgumentParser(description="MCP stdio bridge for Claude Desktop")
+    parser.add_argument("--base-url", required=True, help="Base URL for MCP server")
+    parser.add_argument("--token", required=True, help="PAT token for authentication")
+    parser.add_argument("--no-ssl-verify", action="store_true", help="Disable SSL verification")
+    args = parser.parse_args()
+
+    asyncio.run(async_main(args))
+
+
+if __name__ == "__main__":
+    main()

nxd_tools-0.1.0/pyproject.toml

@@ -0,0 +1,71 @@
+[project]
+name = "nxd-tools"
+version = "0.1.0"
+description = "Collection of tools for working with MCP and other protocols"
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [
+    { name = "Nextdata", email = "dev@nextdata.com" }
+]
+license = { text = "MIT" }
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = []
+
+[project.optional-dependencies]
+mcp-bridge = [
+    "mcp>=1.1.2",
+    "httpx>=0.28.1",
+    "anyio>=4.8.0",
+]
+dev = [
+    "ruff>=0.8.0",
+    "pre-commit>=4.0.0",
+]
+
+[project.scripts]
+nxd-bridge = "nxd_tools.mcp_bridge:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["nxd_tools"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "E",      # pycodestyle errors
+    "W",      # pycodestyle warnings
+    "F",      # pyflakes
+    "I",      # isort
+    "N",      # pep8-naming
+    "UP",     # pyupgrade
+    "B",      # flake8-bugbear
+    "C4",     # flake8-comprehensions
+    "SIM",    # flake8-simplify
+    "RUF",    # ruff-specific rules
+]
+ignore = [
+    "E501",   # line too long (handled by formatter)
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["nxd_tools"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"