cdcasasagi 0.1.0__tar.gz

cdcasasagi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nikkie
+
+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.

cdcasasagi-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.3
+Name: cdcasasagi
+Version: 0.1.0
+Summary: 鵲 - Bridge Claude Desktop to Streamable HTTP MCP servers via mcp-proxy 
+Author: ftnext
+Author-email: ftnext <takuyafjp+develop@gmail.com>
+License: MIT License
+         
+         Copyright (c) 2026 nikkie
+         
+         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.
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Utilities
+Requires-Dist: typer>=0.9
+Requires-Dist: mcp-proxy
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# cdcasasagi
+鵲 - Bridge Claude Desktop to Streamable HTTP MCP servers via mcp-proxy
+
+## Install
+
+```
+uv tool install cdcasasagi
+```
+
+## Usage
+
+Preview what will be written to `claude_desktop_config.json`:
+
+```
+cdcasasagi add https://developers.openai.com/mcp --name openai-developer-docs
+```
+
+This shows a unified diff of the proposed change. No files are modified.
+
+Apply the change:
+
+```
+cdcasasagi add https://developers.openai.com/mcp --name openai-developer-docs --write
+```
+
+This writes the following entry to your Claude Desktop config:
+
+```json
+{
+  "mcpServers": {
+    "openai-developer-docs": {
+      "command": "/Users/you/.local/bin/mcp-proxy",
+      "args": [
+        "--transport",
+        "streamablehttp",
+        "https://developers.openai.com/mcp"
+      ]
+    }
+  }
+}
+```
+
+The `--name` flag is optional. If omitted, a name is automatically derived from the URL hostname (e.g. `developers` for the URL above).
+
+### Options
+
+| Option | Description |
+|---|---|
+| `--name` | Key name for the `mcpServers` entry. Auto-derived from URL if omitted. |
+| `--transport` | Transport type passed to mcp-proxy. Default: `streamablehttp`. |
+| `--force` | Overwrite an existing entry with the same name. |
+| `--write` | Actually write to the config file. Without this flag, only a preview is shown. |

cdcasasagi-0.1.0/README.md

@@ -0,0 +1,52 @@
+# cdcasasagi
+鵲 - Bridge Claude Desktop to Streamable HTTP MCP servers via mcp-proxy
+
+## Install
+
+```
+uv tool install cdcasasagi
+```
+
+## Usage
+
+Preview what will be written to `claude_desktop_config.json`:
+
+```
+cdcasasagi add https://developers.openai.com/mcp --name openai-developer-docs
+```
+
+This shows a unified diff of the proposed change. No files are modified.
+
+Apply the change:
+
+```
+cdcasasagi add https://developers.openai.com/mcp --name openai-developer-docs --write
+```
+
+This writes the following entry to your Claude Desktop config:
+
+```json
+{
+  "mcpServers": {
+    "openai-developer-docs": {
+      "command": "/Users/you/.local/bin/mcp-proxy",
+      "args": [
+        "--transport",
+        "streamablehttp",
+        "https://developers.openai.com/mcp"
+      ]
+    }
+  }
+}
+```
+
+The `--name` flag is optional. If omitted, a name is automatically derived from the URL hostname (e.g. `developers` for the URL above).
+
+### Options
+
+| Option | Description |
+|---|---|
+| `--name` | Key name for the `mcpServers` entry. Auto-derived from URL if omitted. |
+| `--transport` | Transport type passed to mcp-proxy. Default: `streamablehttp`. |
+| `--force` | Overwrite an existing entry with the same name. |
+| `--write` | Actually write to the config file. Without this flag, only a preview is shown. |

cdcasasagi-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "cdcasasagi"
+version = "0.1.0"
+description = "鵲 - Bridge Claude Desktop to Streamable HTTP MCP servers via mcp-proxy "
+authors = [
+    { name = "ftnext", email = "takuyafjp+develop@gmail.com" }
+]
+license = { file = "LICENSE" }
+readme = "README.md"
+requires-python = ">=3.10"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "typer>=0.9",
+    "mcp-proxy",
+]
+
+[project.scripts]
+cdcasasagi = "cdcasasagi:main"
+
+[build-system]
+requires = ["uv_build>=0.11.2,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=7",
+]

cdcasasagi-0.1.0/src/cdcasasagi/__init__.py

@@ -0,0 +1,5 @@
+from .cli import app
+
+
+def main() -> None:
+    app()

cdcasasagi-0.1.0/src/cdcasasagi/cli.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from urllib.parse import urlparse
+
+import typer
+
+from . import desktop_config, mcp_proxy, output, server_name
+
+app = typer.Typer(pretty_exceptions_enable=False)
+
+
+@app.callback()
+def _callback() -> None:
+    pass
+
+
+def _validate_url(url: str) -> None:
+    parsed = urlparse(url)
+    if parsed.scheme not in ("http", "https"):
+        typer.echo("Please specify a valid HTTP(S) URL", err=True)
+        raise typer.Exit(code=1)
+    if not parsed.hostname:
+        typer.echo("Invalid URL format", err=True)
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def add(
+    url: str = typer.Argument(..., help="URL of the MCP server"),
+    name: str | None = typer.Option(None, help="Key name for mcpServers"),
+    transport: str = typer.Option(
+        "streamablehttp", help="Transport type passed to mcp-proxy"
+    ),
+    force: bool = typer.Option(False, help="Overwrite existing entry"),
+    write: bool = typer.Option(False, help="Actually write to the file"),
+) -> None:
+    _validate_url(url)
+
+    name_was_derived = name is None
+    if name is None:
+        try:
+            name = server_name.derive_server_name(url)
+        except server_name.NameDerivationError as e:
+            typer.echo(str(e), err=True)
+            raise typer.Exit(code=1)
+
+    try:
+        proxy_path = mcp_proxy.resolve_path()
+    except mcp_proxy.McpProxyNotFoundError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)
+
+    cfg_path = desktop_config.config_path()
+
+    try:
+        current_config = desktop_config.load_config(cfg_path)
+    except desktop_config.ConfigError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)
+
+    entry = desktop_config.build_entry(proxy_path, transport, url)
+
+    try:
+        merged = desktop_config.merge_entry(current_config, name, entry, force)
+    except desktop_config.EntryExistsError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)
+
+    file_existed = cfg_path.exists()
+
+    if not write:
+        original = None if not file_existed else current_config
+        diff_text = output.format_diff(original, merged)
+        msg = output.preview_message(name, name_was_derived, cfg_path, diff_text)
+        typer.echo(msg)
+    else:
+        desktop_config.write_config(cfg_path, merged)
+        msg = output.write_message(name, name_was_derived, cfg_path, file_existed)
+        typer.echo(msg)

cdcasasagi-0.1.0/src/cdcasasagi/desktop_config.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import json
+import os
+import platform
+import shutil
+import tempfile
+from pathlib import Path
+from typing import Any
+
+
+class ConfigError(Exception):
+    pass
+
+
+class EntryExistsError(Exception):
+    pass
+
+
+def config_path() -> Path:
+    env = os.environ.get("CLAUDE_DESKTOP_CONFIG")
+    if env:
+        return Path(env)
+    if platform.system() == "Windows":
+        appdata = os.environ.get("APPDATA", "")
+        return Path(appdata) / "Claude" / "claude_desktop_config.json"
+    return (
+        Path.home()
+        / "Library"
+        / "Application Support"
+        / "Claude"
+        / "claude_desktop_config.json"
+    )
+
+
+def load_config(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {"mcpServers": {}}
+    try:
+        text = path.read_text(encoding="utf-8")
+        return json.loads(text)
+    except (json.JSONDecodeError, ValueError) as e:
+        raise ConfigError(
+            f"Failed to parse JSON config file: {path}\nPlease check the file: {e}"
+        ) from e
+
+
+def build_entry(mcp_proxy_path: Path, transport: str, url: str) -> dict[str, Any]:
+    return {
+        "command": str(mcp_proxy_path),
+        "args": ["--transport", transport, url],
+    }
+
+
+def merge_entry(
+    config: dict[str, Any],
+    name: str,
+    entry: dict[str, Any],
+    force: bool,
+) -> dict[str, Any]:
+    config = json.loads(json.dumps(config))  # deep copy
+    if "mcpServers" not in config:
+        config["mcpServers"] = {}
+
+    if name in config["mcpServers"] and not force:
+        raise EntryExistsError(f'"{name}" already exists. Use --force to overwrite')
+
+    config["mcpServers"][name] = entry
+    return config
+
+
+def serialize_config(config: dict[str, Any]) -> str:
+    return json.dumps(config, indent=2, ensure_ascii=False) + "\n"
+
+
+def write_config(path: Path, config: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    if path.exists():
+        backup = path.with_suffix(path.suffix + ".bak")
+        shutil.copy2(path, backup)
+
+    content = serialize_config(config)
+    dir_ = path.parent
+    fd, tmp = tempfile.mkstemp(dir=dir_, suffix=".tmp")
+    fd_closed = False
+    try:
+        os.write(fd, content.encode("utf-8"))
+        os.close(fd)
+        fd_closed = True
+        os.replace(tmp, path)
+    except BaseException:
+        if not fd_closed:
+            os.close(fd)
+        if os.path.exists(tmp):
+            os.unlink(tmp)
+        raise

cdcasasagi-0.1.0/src/cdcasasagi/mcp_proxy.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+
+class McpProxyNotFoundError(Exception):
+    pass
+
+
+def resolve_path() -> Path:
+    bin_dir = Path(sys.executable).parent
+    name = "mcp-proxy.exe" if os.name == "nt" else "mcp-proxy"
+    candidate = bin_dir / name
+    if candidate.exists() and candidate.is_file():
+        return candidate
+    raise McpProxyNotFoundError(
+        "mcp-proxy not found. "
+        "Please install this tool via 'uv tool install cdcasasagi'. "
+        "Temporary execution with uvx will not persist the path written to the config file."
+    )

cdcasasagi-0.1.0/src/cdcasasagi/output.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import difflib
+from pathlib import Path
+from typing import Any
+
+from . import desktop_config
+
+
+def format_diff(
+    current_config: dict[str, Any] | None,
+    proposed_config: dict[str, Any],
+) -> str:
+    if current_config is None:
+        current_lines: list[str] = []
+        header = "--- (file does not exist; will be created)\n+++ proposed\n"
+    else:
+        current_text = desktop_config.serialize_config(current_config)
+        current_lines = current_text.splitlines(keepends=True)
+        header = ""
+
+    proposed_text = desktop_config.serialize_config(proposed_config)
+    proposed_lines = proposed_text.splitlines(keepends=True)
+
+    diff = difflib.unified_diff(
+        current_lines,
+        proposed_lines,
+        fromfile="current",
+        tofile="proposed",
+    )
+    if header:
+        diff_lines = list(diff)
+        # Drop the default --- / +++ lines from unified_diff
+        content = "".join(
+            line
+            for line in diff_lines
+            if not line.startswith("--- ") and not line.startswith("+++ ")
+        )
+        return header + content
+    return "".join(diff)
+
+
+def preview_message(
+    name: str,
+    name_was_derived: bool,
+    config_path: Path,
+    diff_text: str,
+) -> str:
+    lines: list[str] = []
+    if name_was_derived:
+        lines.append(f'Derived name from URL: "{name}"')
+    lines.append(f"Target: {config_path}")
+    lines.append("")
+    lines.append(diff_text.rstrip())
+    lines.append("")
+    lines.append("This is a preview. Re-run with --write to apply.")
+    lines.append("To use a different name: --name <your-name>")
+    return "\n".join(lines)
+
+
+def write_message(
+    name: str,
+    name_was_derived: bool,
+    config_path: Path,
+    file_existed: bool,
+) -> str:
+    lines: list[str] = []
+    if name_was_derived:
+        lines.append(f'Derived name from URL: "{name}"')
+    if file_existed:
+        backup = config_path.with_suffix(config_path.suffix + ".bak")
+        lines.append(f"Backup: {backup}")
+    lines.append(f"Wrote:  {config_path}")
+    lines.append("")
+    lines.append(f'Added "{name}". Restart Claude Desktop to take effect.')
+    return "\n".join(lines)

cdcasasagi-0.1.0/src/cdcasasagi/server_name.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import ipaddress
+from urllib.parse import urlparse
+
+_GENERIC_SUBDOMAINS = {"mcp", "api", "app", "www"}
+_MCP_API_FRAGMENTS = {"mcp", "api"}
+
+
+class NameDerivationError(Exception):
+    pass
+
+
+def derive_server_name(url: str) -> str:
+    hostname = urlparse(url).hostname
+    if hostname is None:
+        raise NameDerivationError("Invalid URL format")
+
+    if hostname == "localhost" or _is_ip(hostname):
+        raise NameDerivationError(
+            "Cannot derive a name from the hostname. Please specify --name explicitly"
+        )
+
+    labels = hostname.split(".")
+    if len(labels) < 2:
+        raise NameDerivationError(
+            "Cannot derive a name from the hostname. Please specify --name explicitly"
+        )
+
+    sld = labels[-2]
+    head = labels[0]
+
+    if (
+        head != sld
+        and head not in _GENERIC_SUBDOMAINS
+        and not any(frag in head for frag in _MCP_API_FRAGMENTS)
+    ):
+        candidate = head
+    else:
+        candidate = sld
+
+    candidate = candidate.lower()
+
+    if not candidate or len(candidate) == 1 or candidate.isdigit():
+        raise NameDerivationError(
+            "Cannot derive a name from the hostname. Please specify --name explicitly"
+        )
+
+    return candidate
+
+
+def _is_ip(hostname: str) -> bool:
+    try:
+        ipaddress.ip_address(hostname)
+    except ValueError:
+        return False
+    return True