desklink 0.3.0__py3-none-any.whl

desklink/__init__.py

@@ -0,0 +1,3 @@
+"""DeskLink: Turn your local computer into a remotely accessible MCP endpoint."""
+
+__version__ = "0.3.0"

desklink/auth/__init__.py

@@ -0,0 +1,48 @@
+"""Authentication helpers for DeskLink.
+
+Currently provides a simple static Bearer token verifier.
+Designed so OAuth / Protected Resource Metadata can be added later.
+"""
+
+import secrets
+from pathlib import Path
+from typing import Optional
+
+from mcp.server.auth.provider import AccessToken, TokenVerifier
+
+
+def generate_token() -> str:
+    """Generate a cryptographically strong random token."""
+    return secrets.token_urlsafe(32)
+
+
+def load_or_create_token(token_file: Path) -> str:
+    """Load an existing token or create a new one with restricted permissions."""
+    token_file = Path(token_file)
+    token_file.parent.mkdir(parents=True, exist_ok=True)
+    if token_file.exists():
+        return token_file.read_text().strip()
+    token = generate_token()
+    token_file.write_text(token + "\n")
+    try:
+        token_file.chmod(0o600)
+    except Exception:
+        pass  # Windows or restricted FS
+    return token
+
+
+class DeskLinkTokenVerifier(TokenVerifier):
+    """Minimal TokenVerifier that accepts a single static Bearer token."""
+
+    def __init__(self, token: str):
+        self.token = token
+
+    async def verify_token(self, token: str) -> Optional[AccessToken]:
+        if token == self.token:
+            return AccessToken(
+                token=token,
+                client_id="desklink-local",
+                scopes=["mcp"],
+                expires_at=None,
+            )
+        return None

desklink/bridge.py

@@ -0,0 +1,211 @@
+"""Bridge that proxies tools from local STDIO MCP servers.
+
+DeskLink connects to configured STDIO servers (from mcp.json), discovers their
+tools, and exposes them through a single Streamable HTTP endpoint.
+"""
+
+import asyncio
+import json
+import logging
+import time
+from typing import Any, Dict, List, Optional
+
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+from mcp.server.fastmcp import FastMCP
+from mcp.server.transport_security import TransportSecuritySettings
+
+from desklink.config import DeskLinkConfig
+
+logger = logging.getLogger(__name__)
+
+
+class ToolProxy:
+    """Handles a single tool call with approval and tracing."""
+
+    def __init__(self, config: DeskLinkConfig, sessions: Dict[str, ClientSession]):
+        self.config = config
+        self.sessions = sessions
+
+    def _should_approve(self, tool_name: str) -> bool:
+        policy = self.config.settings.approvals.tools.get(
+            tool_name, self.config.settings.approvals.default
+        )
+        if policy == "auto":
+            return True
+        # Simple console prompt for MVP
+        try:
+            resp = input(f"\n[DeskLink] Approve tool call '{tool_name}'? [y/N] ").strip().lower()
+            return resp in ("y", "yes")
+        except EOFError:
+            return False
+
+    def _trace(
+        self,
+        tool: str,
+        args: dict,
+        result: Any,
+        duration_ms: float,
+        error: Optional[str] = None,
+    ) -> None:
+        if not self.config.settings.tracing.enabled or self.config.settings.tracing.level == "none":
+            return
+        level = self.config.settings.tracing.level
+        entry = {
+            "tool": tool,
+            "duration_ms": round(duration_ms, 1),
+            "error": error,
+        }
+        if level == "full":
+            if self.config.settings.tracing.redact_sensitive:
+                sensitive = {"password", "token", "secret", "key", "authorization"}
+                safe_args = {
+                    k: ("***" if k.lower() in sensitive else v) for k, v in args.items()
+                }
+            else:
+                safe_args = args
+            entry["args"] = safe_args
+            entry["result"] = str(result)[:500] if result else None
+        logger.info("TRACE %s", json.dumps(entry, default=str))
+
+    async def call(self, namespaced_name: str, arguments: dict) -> Any:
+        """Route a namespaced tool call to the correct STDIO session."""
+        if "__" not in namespaced_name:
+            raise ValueError(f"Invalid tool name: {namespaced_name}")
+        server_name, tool_name = namespaced_name.split("__", 1)
+        session = self.sessions.get(server_name)
+        if not session:
+            raise RuntimeError(f"No session for server '{server_name}'")
+
+        if not self._should_approve(namespaced_name):
+            raise PermissionError(f"Tool call '{namespaced_name}' denied by user")
+
+        start = time.perf_counter()
+        error = None
+        result = None
+        try:
+            result = await session.call_tool(tool_name, arguments)
+            return result
+        except Exception as e:
+            error = str(e)
+            raise
+        finally:
+            duration = (time.perf_counter() - start) * 1000
+            self._trace(namespaced_name, arguments, result, duration, error)
+
+
+class McpBridge:
+    """Manages STDIO MCP client sessions and builds a proxy FastMCP server."""
+
+    def __init__(self, config: DeskLinkConfig):
+        self.config = config
+        self.sessions: Dict[str, ClientSession] = {}
+        self.tools: List[Dict[str, Any]] = []
+        self._contexts: List[Any] = []
+
+    async def start_servers(self) -> None:
+        """Connect to all configured STDIO servers and discover tools."""
+        for name, srv in self.config.mcp.mcpServers.items():
+            params = StdioServerParameters(
+                command=srv.command,
+                args=srv.args,
+                env=srv.env,
+                cwd=srv.cwd,
+            )
+            try:
+                stdio_ctx = stdio_client(params)
+                read, write = await stdio_ctx.__aenter__()
+                session = ClientSession(read, write)
+                await session.__aenter__()
+                await session.initialize()
+                self.sessions[name] = session
+                self._contexts.append((stdio_ctx, session))
+
+                tools_result = await session.list_tools()
+                for t in tools_result.tools:
+                    self.tools.append(
+                        {
+                            "server": name,
+                            "name": t.name,
+                            "namespaced": f"{name}__{t.name}",
+                            "description": t.description or "",
+                            "inputSchema": t.inputSchema,
+                        }
+                    )
+                logger.info(
+                    "Connected to MCP server '%s' (%d tools)", name, len(tools_result.tools)
+                )
+            except Exception as e:
+                logger.error("Failed to start MCP server '%s': %s", name, e)
+
+    def build_proxy_server(self) -> FastMCP:
+        """Create a FastMCP that proxies all discovered tools.
+
+        Each proxy tool is registered with a signature that matches the original
+        MCP tool's inputSchema (not a synthetic kwargs wrapper). This makes the
+        advertised schema and the call path consistent.
+        """
+        import inspect
+
+        mcp = FastMCP(
+            "DeskLink Bridge",
+            transport_security=TransportSecuritySettings(
+                enable_dns_rebinding_protection=False,
+            ),
+        )
+        proxy = ToolProxy(self.config, self.sessions)
+
+        for tool in self.tools:
+            ns_name = tool["namespaced"]
+            desc = tool["description"] or f"Proxied tool from {tool['server']}"
+            original_schema = tool.get("inputSchema") or {"type": "object", "properties": {}}
+
+            props = (original_schema or {}).get("properties") or {}
+            required = set((original_schema or {}).get("required") or [])
+
+            # Build a real signature so FastMCP generates the correct parameter schema.
+            # Only include properties that exist in the original schema.
+            # A synthetic "kwargs" parameter is never added unless the upstream tool defines one.
+            params = []
+            for pname in props:
+                if pname in required:
+                    params.append(inspect.Parameter(pname, inspect.Parameter.POSITIONAL_OR_KEYWORD))
+                else:
+                    params.append(
+                        inspect.Parameter(pname, inspect.Parameter.POSITIONAL_OR_KEYWORD, default=None)
+                    )
+            sig = inspect.Signature(params)
+
+            def make_handler(name: str, signature: inspect.Signature, req: set):
+                async def handler(*args: Any, **kwargs: Any) -> Any:
+                    bound = signature.bind(*args, **kwargs)
+                    bound.apply_defaults()
+                    # Drop unset optionals; keep required values even if None
+                    arguments = {
+                        k: v for k, v in bound.arguments.items() if v is not None or k in req
+                    }
+                    return await proxy.call(name, arguments)
+
+                handler.__signature__ = signature
+                # Safe function name (MCP tool names can contain __)
+                handler.__name__ = name.replace("__", "_")
+                return handler
+
+            handler = make_handler(ns_name, sig, required)
+            mcp.tool(name=ns_name, description=desc)(handler)
+
+            # Ensure the advertised schema is exactly the original one
+            # (FastMCP may still rewrite some details from the signature).
+            registered = mcp._tool_manager._tools.get(ns_name)
+            if registered is not None and original_schema:
+                registered.parameters = original_schema
+
+        return mcp
+
+    async def close(self) -> None:
+        for stdio_ctx, session in self._contexts:
+            try:
+                await session.__aexit__(None, None, None)
+                await stdio_ctx.__aexit__(None, None, None)
+            except Exception:
+                pass

desklink/cli/__init__.py

@@ -0,0 +1,4 @@
+"""DeskLink CLI package."""
+from .main import app
+
+__all__ = ["app"]

desklink/cli/main.py

@@ -0,0 +1,133 @@
+"""DeskLink CLI.
+
+Primary command: desklink start
+
+Supports mcp.json for local STDIO servers and desklink.config.json for settings.
+Also provides tools listing and direct tool invocation for testing.
+"""
+
+import asyncio
+import json
+import logging
+import signal
+import sys
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from desklink import __version__
+from desklink.auth import load_or_create_token
+from desklink.bridge import McpBridge
+from desklink.config import ensure_default_filesystem, load_config
+from desklink.oauth import (
+    PRESETS,
+    OAuthApp,
+    OAuthStore,
+    generate_client_id,
+    generate_client_secret,
+    _hash,
+)
+from desklink.server import DeskLinkServer
+
+app = typer.Typer(help="Turn your local computer into a remote MCP endpoint.")
+console = Console()
+
+
+def setup_logging(verbose: bool = False, level: Optional[str] = None) -> None:
+    log_level = logging.DEBUG if verbose else getattr(logging, (level or "INFO").upper(), logging.INFO)
+    logging.basicConfig(level=log_level, format="%(asctime)s [%(levelname)s] %(name)s: %(message)s", datefmt="%H:%M:%S")
+
+
+def _load_cfg(config, mcp_config, allowed_dirs):
+    cfg = load_config(config_path=config, mcp_path=mcp_config)
+    if allowed_dirs:
+        dirs = [Path(d).resolve() for d in allowed_dirs]
+        cfg = ensure_default_filesystem(cfg, dirs)
+    else:
+        cfg = ensure_default_filesystem(cfg)
+    return cfg
+
+
+@app.command()
+def start(
+    mcp_config: Optional[Path] = typer.Option(None, "--mcp-config"),
+    config: Optional[Path] = typer.Option(None, "--config"),
+    allowed_dirs: Optional[list[str]] = typer.Option(None, "--dir", "-d"),
+    port: Optional[int] = typer.Option(None, "--port", "-p"),
+    tunnel: Optional[str] = typer.Option(None, "--tunnel"),
+    token: Optional[str] = typer.Option(None, "--token"),
+    verbose: bool = typer.Option(False, "--verbose", "-v"),
+):
+    """Start the MCP bridge and tunnel."""
+    cfg = _load_cfg(config, mcp_config, allowed_dirs)
+    if port: cfg.settings.server.port = port
+    if tunnel: cfg.settings.tunnel.provider = tunnel
+    if token: cfg.settings.auth.token = token
+    elif cfg.settings.auth.enabled and not cfg.settings.auth.token:
+        cfg.settings.auth.token = load_or_create_token(cfg.settings.auth.token_file)
+    setup_logging(verbose, cfg.settings.logging.level)
+    console.print(Panel(f"DeskLink v{__version__}", style="bold cyan"))
+    server = DeskLinkServer(cfg)
+    async def _run():
+        local = await server.start_http_server()
+        public = server.start_tunnel()
+        console.print("[green]MCP bridge started[/green]")
+        console.print(f"Local: {local}")
+        console.print(f"Remote: {public}")
+        if cfg.settings.auth.token:
+            console.print(f"Auth token: {cfg.settings.auth.token}")
+        await server._shutdown_event.wait()
+    try:
+        asyncio.run(_run())
+    except KeyboardInterrupt:
+        pass
+    finally:
+        asyncio.run(server.shutdown())
+
+
+@app.command()
+def create(
+    kind: str = typer.Argument(..., help="What to create, e.g. oauth-app"),
+    preset: str = typer.Argument("custom", help="Agent preset: claude, chatgpt, manus, cursor, custom"),
+    name: Optional[str] = typer.Option(None, "--name"),
+    public: bool = typer.Option(False, "--public/--confidential", help="Public client (no secret). Default is confidential with a secret."),
+):
+    """Create an OAuth application. Always generates Client ID + Client Secret unless --public."""
+    if kind != "oauth-app":
+        console.print(f"[red]Unknown create target:[/red] {kind}")
+        raise typer.Exit(1)
+    preset = preset.lower()
+    meta = PRESETS.get(preset, PRESETS["custom"])
+    display = name or meta["name"]
+    scopes = meta["scopes"]
+    client_id = generate_client_id()
+    secret = None
+    secret_hash = None
+    if not public:
+        secret = generate_client_secret()
+        secret_hash = _hash(secret)
+    OAuthStore().save_app(OAuthApp(client_id=client_id, name=display, preset=preset, scopes=scopes, public=public, client_secret_hash=secret_hash, description=meta.get("description", "")))
+    console.print(Panel(f"OAuth app created: {display}", style="bold green"))
+    console.print(f"[cyan]Client ID:[/cyan] {client_id}")
+    if secret:
+        console.print(f"[cyan]Client Secret:[/cyan] {secret}")
+    else:
+        console.print("[dim]Public client (no secret). Use PKCE.[/dim]")
+    console.print(f"[cyan]Scopes:[/cyan] {', '.join(scopes)}")
+    console.print("\nEndpoints (when DeskLink is running):")
+    console.print("  Authorization:  http://127.0.0.1:8765/oauth/authorize")
+    console.print("  Token:          http://127.0.0.1:8765/oauth/token")
+    console.print("  MCP:            http://127.0.0.1:8765/mcp")
+    console.print("  Dashboard:      http://127.0.0.1:8765/dashboard")
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

desklink/config/__init__.py

@@ -0,0 +1,152 @@
+"""Configuration loading for DeskLink.
+
+Supports:
+- desklink.config.json (DeskLink settings: auth, tracing, approvals, server, tunnel)
+- mcp.json (standard MCP server definitions, STDIO by default)
+- Environment variables and CLI overrides
+"""
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class ServerConfig(BaseModel):
+    host: str = "127.0.0.1"
+    port: int = 8765
+    mcp_path: str = "/mcp"
+
+
+class TunnelConfig(BaseModel):
+    provider: str = "ngrok"
+    authtoken: Optional[str] = None
+
+
+class AuthConfig(BaseModel):
+    enabled: bool = True
+    token: Optional[str] = None
+    token_file: Path = Path.home() / ".desklink" / "token"
+
+
+class TracingConfig(BaseModel):
+    enabled: bool = True
+    level: str = "basic"  # none | basic | full
+    redact_sensitive: bool = True
+    log_file: Optional[Path] = None
+
+
+class ApprovalsConfig(BaseModel):
+    default: str = "auto"  # auto | prompt
+    tools: Dict[str, str] = Field(default_factory=dict)  # tool_name -> auto|prompt
+
+
+class LoggingConfig(BaseModel):
+    level: str = "info"
+
+
+class DeskLinkSettings(BaseModel):
+    logging: LoggingConfig = Field(default_factory=LoggingConfig)
+    tracing: TracingConfig = Field(default_factory=TracingConfig)
+    auth: AuthConfig = Field(default_factory=AuthConfig)
+    approvals: ApprovalsConfig = Field(default_factory=ApprovalsConfig)
+    server: ServerConfig = Field(default_factory=ServerConfig)
+    tunnel: TunnelConfig = Field(default_factory=TunnelConfig)
+
+
+class McpServerConfig(BaseModel):
+    command: str
+    args: List[str] = Field(default_factory=list)
+    env: Optional[Dict[str, str]] = None
+    cwd: Optional[str] = None
+
+
+class McpConfig(BaseModel):
+    mcpServers: Dict[str, McpServerConfig] = Field(default_factory=dict)
+
+
+class DeskLinkConfig(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="DESKLINK_", env_nested_delimiter="__")
+
+    settings: DeskLinkSettings = Field(default_factory=DeskLinkSettings)
+    mcp: McpConfig = Field(default_factory=McpConfig)
+
+    def model_post_init(self, __context: Any) -> None:
+        if not self.settings.tunnel.authtoken:
+            self.settings.tunnel.authtoken = os.getenv("NGROK_AUTHTOKEN")
+
+
+def _load_json(path: Path) -> dict:
+    if not path.exists():
+        return {}
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+
+
+def load_config(
+    config_path: Optional[Path] = None,
+    mcp_path: Optional[Path] = None,
+) -> DeskLinkConfig:
+    """Load DeskLink settings and mcp.json.
+
+    Search order for desklink.config.json:
+    - explicit path
+    - ./desklink.config.json
+    - ~/.desklink/config.json
+
+    Search order for mcp.json:
+    - explicit path
+    - ./mcp.json
+    - ~/.desklink/mcp.json
+    """
+    home = Path.home()
+    candidates_config = [
+        config_path,
+        Path.cwd() / "desklink.config.json",
+        home / ".desklink" / "config.json",
+    ]
+    candidates_mcp = [
+        mcp_path,
+        Path.cwd() / "mcp.json",
+        home / ".desklink" / "mcp.json",
+    ]
+
+    settings_data = {}
+    for p in candidates_config:
+        if p and p.exists():
+            settings_data = _load_json(p)
+            break
+
+    mcp_data = {}
+    for p in candidates_mcp:
+        if p and p.exists():
+            mcp_data = _load_json(p)
+            break
+
+    settings = DeskLinkSettings.model_validate(settings_data) if settings_data else DeskLinkSettings()
+    mcp = McpConfig.model_validate(mcp_data) if mcp_data else McpConfig()
+
+    cfg = DeskLinkConfig(settings=settings, mcp=mcp)
+    return cfg
+
+
+def ensure_default_filesystem(cfg: DeskLinkConfig, dirs: Optional[List[Path]] = None) -> DeskLinkConfig:
+    """If no MCP servers are configured, inject the official filesystem server.
+
+    Uses npx @modelcontextprotocol/server-filesystem with the given directories
+    (or home as fallback). This preserves the previous single-filesystem UX.
+    """
+    if cfg.mcp.mcpServers:
+        return cfg
+
+    allowed = [str(d) for d in (dirs or [Path.home()])]
+    cfg.mcp.mcpServers["filesystem"] = McpServerConfig(
+        command="npx",
+        args=["-y", "@modelcontextprotocol/server-filesystem"] + allowed,
+    )
+    return cfg

desklink/models/__init__.py

@@ -0,0 +1,27 @@
+"""Shared data models for DeskLink."""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List, Optional
+
+
+@dataclass
+class TunnelInfo:
+    """Information about an established tunnel."""
+
+    provider: str
+    public_url: str
+    local_url: str
+    tunnel_id: Optional[str] = None
+
+
+@dataclass
+class ServerStatus:
+    """Runtime status of DeskLink."""
+
+    running: bool = False
+    local_url: Optional[str] = None
+    public_url: Optional[str] = None
+    tools_count: int = 0
+    auth_enabled: bool = True
+    allowed_directories: List[Path] = field(default_factory=list)