linkedin-mcp-zero 0.3.0__py3-none-any.whl

linkedin_mcp_zero/__init__.py

@@ -0,0 +1,3 @@
+"""LinkedIn MCP Zero package."""
+
+__version__ = "0.3.0"

linkedin_mcp_zero/__main__.py

@@ -0,0 +1,4 @@
+from linkedin_mcp_zero.main import cli
+
+if __name__ == "__main__":
+    cli()

linkedin_mcp_zero/cache/__init__.py

@@ -0,0 +1,3 @@
+from linkedin_mcp_zero.cache.ttl_cache import TTLCache
+
+__all__ = ["TTLCache"]

linkedin_mcp_zero/cache/ttl_cache.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import time
+from collections import OrderedDict
+from collections.abc import Hashable
+from dataclasses import dataclass
+from typing import Generic, TypeVar
+
+T = TypeVar("T")
+
+
+@dataclass
+class CacheEntry(Generic[T]):
+    value: T
+    expires_at: float
+
+
+class TTLCache(Generic[T]):
+    def __init__(self, ttl_seconds: int, max_entries: int = 200) -> None:
+        self.ttl_seconds = ttl_seconds
+        self.max_entries = max_entries
+        self._items: OrderedDict[Hashable, CacheEntry[T]] = OrderedDict()
+
+    def get(self, key: Hashable) -> T | None:
+        entry = self._items.get(key)
+        if entry is None:
+            return None
+        if entry.expires_at < time.monotonic():
+            self._items.pop(key, None)
+            return None
+        self._items.move_to_end(key)
+        return entry.value
+
+    def set(self, key: Hashable, value: T) -> None:
+        self._items[key] = CacheEntry(value=value, expires_at=time.monotonic() + self.ttl_seconds)
+        self._items.move_to_end(key)
+        while len(self._items) > self.max_entries:
+            self._items.popitem(last=False)
+
+    def stats(self) -> dict[str, int]:
+        return {"entries": len(self._items), "max": self.max_entries, "ttl": self.ttl_seconds}

linkedin_mcp_zero/config/__init__.py

@@ -0,0 +1,3 @@
+from linkedin_mcp_zero.config.settings import Settings
+
+__all__ = ["Settings"]

linkedin_mcp_zero/config/autodetect.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+import sys
+from dataclasses import asdict, dataclass
+from importlib.util import find_spec
+from pathlib import Path
+
+from platformdirs import user_data_dir
+
+from linkedin_mcp_zero.config.defaults import DATA_DIR_NAME
+
+
+@dataclass(frozen=True)
+class RuntimeStatus:
+    os: str
+    python: str
+    python_ok: bool
+    executable: str
+    cpu_count: int | None
+    ram_total_mb: int | None
+    ram_available_mb: int | None
+    disk_free_mb: int | None
+    data_dir: str
+    chrome: str | None
+    cdp_url: str
+    cdp_env_hint: bool
+    docker: bool
+    display: bool
+    optional: dict[str, bool]
+    mode: str
+    notes: list[str]
+
+
+def detect_chrome() -> str | None:
+    candidates = [
+        "google-chrome",
+        "google-chrome-stable",
+        "chromium",
+        "chromium-browser",
+        "brave-browser",
+        "microsoft-edge",
+    ]
+    for name in candidates:
+        path = shutil.which(name)
+        if path:
+            return path
+    return None
+
+
+def detect_runtime(data_dir: str | None = None) -> dict[str, object]:
+    ram_total, ram_available = _memory_mb()
+    disk_free = _disk_free_mb(data_dir)
+    optional = {
+        "jobspy": _has_module("jobspy"),
+        "pymupdf": _has_module("fitz"),
+        "playwright": _has_module("playwright.async_api"),
+        "patchright": _has_module("patchright.async_api"),
+    }
+    mode, notes = _recommend_mode(ram_available, disk_free, optional)
+    status = RuntimeStatus(
+        os=platform.system(),
+        python=platform.python_version(),
+        python_ok=sys.version_info >= (3, 10),
+        executable=sys.executable,
+        cpu_count=os.cpu_count(),
+        ram_total_mb=ram_total,
+        ram_available_mb=ram_available,
+        disk_free_mb=disk_free,
+        data_dir=str(_data_dir(data_dir)),
+        chrome=detect_chrome(),
+        cdp_url=os.environ.get("LINKEDIN_MCP_CDP_URL", "http://127.0.0.1:9222"),
+        cdp_env_hint="LINKEDIN_MCP_CDP_URL" in os.environ,
+        docker=os.path.exists("/.dockerenv"),
+        display=bool(os.environ.get("DISPLAY") or os.environ.get("WAYLAND_DISPLAY")),
+        optional=optional,
+        mode=mode,
+        notes=notes,
+    )
+    return asdict(status)
+
+
+def _data_dir(data_dir: str | None = None) -> Path:
+    return Path(data_dir or user_data_dir(DATA_DIR_NAME)).expanduser()
+
+
+def _has_module(name: str) -> bool:
+    try:
+        return find_spec(name) is not None
+    except ModuleNotFoundError:
+        return False
+
+
+def _disk_free_mb(data_dir: str | None = None) -> int | None:
+    try:
+        path = _data_dir(data_dir)
+        path.mkdir(parents=True, exist_ok=True)
+        usage = shutil.disk_usage(path)
+        return round(usage.free / 1024 / 1024)
+    except OSError:
+        return None
+
+
+def _memory_mb() -> tuple[int | None, int | None]:
+    if platform.system() == "Linux":
+        try:
+            values: dict[str, int] = {}
+            for line in Path("/proc/meminfo").read_text(encoding="utf-8").splitlines():
+                key, raw = line.split(":", 1)
+                values[key] = int(raw.strip().split()[0])
+            total = round(values["MemTotal"] / 1024)
+            available = round(values.get("MemAvailable", values["MemFree"]) / 1024)
+            return total, available
+        except (OSError, KeyError, ValueError):
+            return None, None
+    if hasattr(os, "sysconf"):
+        try:
+            pages = os.sysconf("SC_PHYS_PAGES")
+            page_size = os.sysconf("SC_PAGE_SIZE")
+            return round(pages * page_size / 1024 / 1024), None
+        except (OSError, ValueError):
+            return None, None
+    return None, None
+
+
+def _recommend_mode(
+    ram_available_mb: int | None,
+    disk_free_mb: int | None,
+    optional: dict[str, bool],
+) -> tuple[str, list[str]]:
+    notes: list[str] = []
+    mode = "full"
+    if ram_available_mb is not None and ram_available_mb < 700:
+        mode = "lean"
+        notes.append("Low available RAM: keep Engine 2 browser closed until needed.")
+    elif ram_available_mb is not None and ram_available_mb < 1500:
+        mode = "balanced"
+        notes.append("Moderate available RAM: Engine 1/local tools are preferred by default.")
+    if disk_free_mb is not None and disk_free_mb < 512:
+        mode = "lean"
+        notes.append("Low disk space: avoid large exports and browser profiles.")
+    if not optional["playwright"]:
+        notes.append("Browser tools need `uv sync --extra browser`.")
+    if not optional["jobspy"]:
+        notes.append("Multi-board search needs `uv sync --extra multi`.")
+    if not optional["pymupdf"]:
+        notes.append("PDF resume parsing needs `uv sync --extra pdf`.")
+    if not notes:
+        notes.append("System looks ready for local and public no-login workflow.")
+    return mode, notes

linkedin_mcp_zero/config/defaults.py

@@ -0,0 +1,7 @@
+DEFAULT_LIMIT = 10
+MAX_LIMIT = 50
+CACHE_TTL_SECONDS = 300
+CACHE_MAX_ENTRIES = 200
+GUEST_API_BASE = "https://www.linkedin.com/jobs-guest/jobs/api"
+DATA_DIR_NAME = "linkedin-mcp-zero"
+USER_AGENT = "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0 Safari/537.36"

linkedin_mcp_zero/config/install.py

@@ -0,0 +1,412 @@
+from __future__ import annotations
+
+import json
+import os
+import platform
+import shutil
+import subprocess
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Literal
+
+ClientName = Literal["claude-desktop", "claude-code", "cursor", "vscode"]
+PackageSource = Literal["pypi", "github"]
+PackageExtra = Literal["browser", "multi", "pdf"]
+
+
+@dataclass(frozen=True)
+class InstallResult:
+    client: str
+    path: str | None
+    changed: bool
+    backup: str | None
+    server: str
+    command: list[str] | None = None
+    message: str = ""
+
+
+@dataclass(frozen=True)
+class VerifyResult:
+    client: str
+    ok: bool
+    path: str | None
+    checks: list[dict[str, object]]
+    repair_hint: str
+
+
+SERVER_NAME = "linkedin-zero"
+GITHUB_URL = "git+https://github.com/SanthaKumar-K-2004/linkedin-mcp-zero"
+FILE_CLIENTS: dict[str, dict[str, str]] = {
+    "claude-desktop": {"key": "mcpServers"},
+    "cursor": {"key": "mcpServers"},
+    "vscode": {"key": "servers"},
+}
+
+
+def config_path(client: ClientName, cwd: Path | None = None) -> Path:
+    system = platform.system()
+    home = Path.home()
+    if client == "cursor":
+        base = cwd or Path.cwd()
+        return base / ".cursor" / "mcp.json"
+    if client == "vscode":
+        if _is_wsl():
+            return home / ".vscode-server" / "data" / "User" / "mcp.json"
+        if system == "Darwin":
+            return home / "Library" / "Application Support" / "Code" / "User" / "mcp.json"
+        if system == "Windows":
+            return home / "AppData" / "Roaming" / "Code" / "User" / "mcp.json"
+        return home / ".config" / "Code" / "User" / "mcp.json"
+    if client == "claude-code":
+        return home / ".claude.json"
+    if system == "Darwin":
+        return home / "Library" / "Application Support" / "Claude" / "claude_desktop_config.json"
+    if system == "Windows":
+        return home / "AppData" / "Roaming" / "Claude" / "claude_desktop_config.json"
+    return home / ".config" / "Claude" / "claude_desktop_config.json"
+
+
+def install_client_config(
+    client: ClientName,
+    *,
+    path: str | None = None,
+    cwd: Path | None = None,
+    source: PackageSource = "pypi",
+    extras: list[PackageExtra] | None = None,
+    enable_browser: bool = False,
+) -> InstallResult:
+    enable_browser = enable_browser or "browser" in (extras or [])
+    if client == "claude-code":
+        return _install_claude_code(source, extras=extras, enable_browser=enable_browser)
+
+    target = Path(path).expanduser() if path else config_path(client, cwd)
+    config_key = _config_key(client)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    data = _load_json(target)
+    servers = data.setdefault(config_key, {})
+    if not isinstance(servers, dict):
+        raise ValueError(f"Existing config has non-object `{config_key}`; refusing to overwrite.")
+
+    server_config = server_config_for(source, extras=extras, enable_browser=enable_browser)
+    old = servers.get(SERVER_NAME)
+    if old == server_config:
+        return InstallResult(
+            client,
+            str(target),
+            False,
+            None,
+            SERVER_NAME,
+            None,
+            "Already current.",
+        )
+
+    backup = _backup(target) if target.exists() else None
+    servers[SERVER_NAME] = server_config
+    _atomic_write_json(target, data)
+    return InstallResult(client, str(target), True, backup, SERVER_NAME, None, "Config updated.")
+
+
+def verify_client_config(
+    client: ClientName,
+    *,
+    path: str | None = None,
+    cwd: Path | None = None,
+) -> VerifyResult:
+    if client == "claude-code":
+        claude = shutil.which("claude")
+        list_ok = False
+        list_detail = "not checked"
+        if claude:
+            completed = subprocess.run(
+                [claude, "mcp", "list"],
+                check=False,
+                capture_output=True,
+                text=True,
+            )
+            output = (completed.stdout or completed.stderr or "").strip()
+            list_ok = completed.returncode == 0 and SERVER_NAME in output
+            list_detail = output or f"exit {completed.returncode}"
+        claude_checks = [
+            {"name": "claude_cli_found", "ok": bool(claude), "detail": claude or "not found"},
+            {
+                "name": "claude_mcp_list_contains_linkedin_zero",
+                "ok": list_ok,
+                "detail": list_detail,
+            },
+        ]
+        return VerifyResult(
+            client=client,
+            ok=all(bool(check["ok"]) for check in claude_checks),
+            path=None,
+            checks=claude_checks,
+            repair_hint=("Install Claude Code CLI, then run `linkedin-mcp-zero --install-client claude-code`."),
+        )
+
+    target = Path(path).expanduser() if path else config_path(client, cwd)
+    config_key = _config_key(client)
+    checks: list[dict[str, object]] = []
+    data: dict[str, Any] = {}
+    try:
+        data = _load_json(target)
+        checks.append({"name": "valid_json", "ok": True, "detail": str(target)})
+    except Exception as exc:
+        checks.append({"name": "valid_json", "ok": False, "detail": str(exc)})
+
+    servers = data.get(config_key) if data else None
+    checks.append(
+        {
+            "name": f"{config_key}.{SERVER_NAME}",
+            "ok": isinstance(servers, dict) and SERVER_NAME in servers,
+            "detail": "server entry present" if isinstance(servers, dict) else "server map missing",
+        }
+    )
+    entry = servers.get(SERVER_NAME) if isinstance(servers, dict) else {}
+    command = str(entry.get("command", "")) if isinstance(entry, dict) else ""
+    command_ok = bool(command and (Path(command).exists() or shutil.which(command)))
+    checks.append({"name": "command_resolves", "ok": command_ok, "detail": command or "missing"})
+    args = entry.get("args", []) if isinstance(entry, dict) else []
+    args_ok = isinstance(args, list) and bool(args)
+    checks.append({"name": "args_present", "ok": args_ok, "detail": args if args_ok else "missing"})
+    if command_ok and args_ok:
+        checks.append(_check_server_doctor(command, args))
+    if client == "vscode":
+        checks.append(
+            {
+                "name": "vscode_uses_servers_key",
+                "ok": "servers" in data and "mcpServers" not in data,
+                "detail": "VS Code requires top-level `servers`.",
+            }
+        )
+    ok = all(bool(item["ok"]) for item in checks)
+    return VerifyResult(
+        client=client,
+        ok=ok,
+        path=str(target),
+        checks=checks,
+        repair_hint=f"Run `linkedin-mcp-zero --install-client {client}` to repair this config.",
+    )
+
+
+def _check_server_doctor(command: str, args: object) -> dict[str, object]:
+    if not isinstance(args, list) or not args:
+        return {"name": "server_doctor_runs", "ok": False, "detail": "missing args"}
+    doctor_args = [str(part) for part in args] + ["--doctor", "--json"]
+    try:
+        completed = subprocess.run(
+            [command, *doctor_args],
+            check=False,
+            capture_output=True,
+            text=True,
+            timeout=45,
+        )
+    except Exception as exc:
+        return {"name": "server_doctor_runs", "ok": False, "detail": str(exc)}
+    detail = (completed.stderr or completed.stdout or "").strip()
+    return {
+        "name": "server_doctor_runs",
+        "ok": completed.returncode == 0,
+        "detail": detail[:500] if detail else f"exit {completed.returncode}",
+    }
+
+
+def preview_config(
+    source: PackageSource = "pypi",
+    *,
+    client: ClientName = "claude-desktop",
+    extras: list[PackageExtra] | None = None,
+    enable_browser: bool = False,
+) -> dict[str, Any]:
+    enable_browser = enable_browser or "browser" in (extras or [])
+    if client == "claude-code":
+        return {
+            "command": claude_code_command(
+                source,
+                extras=extras,
+                enable_browser=enable_browser,
+            )
+        }
+    return {
+        _config_key(client): {
+            SERVER_NAME: server_config_for(
+                source,
+                extras=extras,
+                enable_browser=enable_browser,
+            )
+        }
+    }
+
+
+def server_config_for(
+    source: PackageSource = "pypi",
+    *,
+    extras: list[PackageExtra] | None = None,
+    enable_browser: bool = False,
+) -> dict[str, Any]:
+    command = shutil.which("uvx") or "uvx"
+    env = {
+        "PATH": _merged_path(command),
+        "HOME": str(Path.home()),
+    }
+    args = _uvx_args(source, extras=extras)
+    if enable_browser:
+        args.append("--enable-browser")
+        env["LINKEDIN_MCP_ENABLE_BROWSER"] = "true"
+    return {"command": command, "args": args, "env": env}
+
+
+def claude_code_command(
+    source: PackageSource = "pypi",
+    *,
+    extras: list[PackageExtra] | None = None,
+    enable_browser: bool = False,
+) -> list[str]:
+    config = server_config_for(source, extras=extras, enable_browser=enable_browser)
+    return [
+        "claude",
+        "mcp",
+        "add-json",
+        SERVER_NAME,
+        json.dumps(config, ensure_ascii=True),
+        "-s",
+        "user",
+    ]
+
+
+def _install_claude_code(
+    source: PackageSource,
+    *,
+    extras: list[PackageExtra] | None,
+    enable_browser: bool,
+) -> InstallResult:
+    command = claude_code_command(source, extras=extras, enable_browser=enable_browser)
+    if not shutil.which("claude"):
+        return InstallResult(
+            "claude-code",
+            None,
+            False,
+            None,
+            SERVER_NAME,
+            command,
+            "Claude Code CLI not found. Run the returned command after installing Claude Code.",
+        )
+    completed = subprocess.run(command, check=False, capture_output=True, text=True)
+    if completed.returncode != 0:
+        return InstallResult(
+            "claude-code",
+            None,
+            False,
+            None,
+            SERVER_NAME,
+            command,
+            (completed.stderr or completed.stdout or "Claude Code install failed.").strip(),
+        )
+    return InstallResult(
+        "claude-code",
+        None,
+        True,
+        None,
+        SERVER_NAME,
+        command,
+        "Claude Code MCP added.",
+    )
+
+
+def _uvx_args(
+    source: PackageSource = "pypi",
+    *,
+    extras: list[PackageExtra] | None = None,
+) -> list[str]:
+    if source == "github":
+        return ["--from", _github_requirement(extras), "mcp-server-linkedin-zero"]
+    if extras:
+        return ["--from", _package_requirement(extras), "mcp-server-linkedin-zero"]
+    return ["mcp-server-linkedin-zero"]
+
+
+def _config_key(client: ClientName) -> str:
+    if client not in FILE_CLIENTS:
+        raise ValueError(f"{client} does not use a direct JSON config file.")
+    return FILE_CLIENTS[client]["key"]
+
+
+def _package_requirement(extras: list[PackageExtra] | None = None) -> str:
+    clean = _clean_extras(extras)
+    if not clean:
+        return "mcp-server-linkedin-zero"
+    return f"mcp-server-linkedin-zero[{','.join(clean)}]"
+
+
+def _github_requirement(extras: list[PackageExtra] | None = None) -> str:
+    clean = _clean_extras(extras)
+    if not clean:
+        return GITHUB_URL
+    return f"mcp-server-linkedin-zero[{','.join(clean)}] @ {GITHUB_URL}"
+
+
+def _clean_extras(extras: list[PackageExtra] | None = None) -> list[str]:
+    allowed = {"browser", "multi", "pdf"}
+    return sorted({extra for extra in extras or [] if extra in allowed})
+
+
+def _merged_path(command: str) -> str:
+    paths = [str(Path(command).parent)] if "/" in command else []
+    paths.extend([str(Path.home() / ".local" / "bin"), "/usr/local/bin", "/usr/bin", "/bin"])
+    existing = os.environ.get("PATH", "")
+    paths.extend(part for part in existing.split(":") if part)
+    return ":".join(dict.fromkeys(paths))
+
+
+def _load_json(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    text = path.read_text(encoding="utf-8").strip()
+    if not text:
+        return {}
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError as exc:
+        corrupt = path.with_suffix(f"{path.suffix}.invalid.{datetime.now():%Y%m%d%H%M%S}.bak")
+        shutil.copy2(path, corrupt)
+        recovered = _load_latest_valid_backup(path)
+        if recovered is None:
+            raise ValueError(
+                f"Config JSON is invalid at {path}: {exc}. A copy was saved to {corrupt}. Fix the JSON and rerun."
+            ) from exc
+        return recovered
+    if not isinstance(data, dict):
+        raise ValueError("Existing config root must be a JSON object.")
+    return data
+
+
+def _load_latest_valid_backup(path: Path) -> dict[str, Any] | None:
+    backups = sorted(path.parent.glob(f"{path.name}*.bak"), key=lambda item: item.stat().st_mtime)
+    for backup in reversed(backups):
+        try:
+            data = json.loads(backup.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            continue
+        if isinstance(data, dict):
+            return data
+    return None
+
+
+def _backup(path: Path) -> str:
+    stamp = datetime.now().strftime("%Y%m%d%H%M%S")
+    backup = path.with_suffix(f"{path.suffix}.{stamp}.bak")
+    shutil.copy2(path, backup)
+    return str(backup)
+
+
+def _atomic_write_json(path: Path, data: dict[str, Any]) -> None:
+    tmp = path.with_suffix(f"{path.suffix}.tmp")
+    tmp.write_text(json.dumps(data, indent=2, ensure_ascii=True) + "\n", encoding="utf-8")
+    tmp.replace(path)
+
+
+def _is_wsl() -> bool:
+    try:
+        release = Path("/proc/sys/kernel/osrelease").read_text(encoding="utf-8").lower()
+    except OSError:
+        return False
+    return "microsoft" in release or "wsl" in release

linkedin_mcp_zero/config/settings.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from linkedin_mcp_zero.config.defaults import CACHE_TTL_SECONDS
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_prefix="LINKEDIN_MCP_",
+        env_file=(".env",),
+        extra="ignore",
+        populate_by_name=True,
+    )
+
+    transport: str = "stdio"
+    host: str = "127.0.0.1"
+    port: int = 8000
+    log_level: str = "INFO"
+    timeout_seconds: float = 15
+    cache_ttl_seconds: int = CACHE_TTL_SECONDS
+    enable_voyager: bool = False
+    http_proxy: str | None = Field(default=None, validation_alias="HTTP_PROXY")
+    https_proxy: str | None = Field(default=None, validation_alias="HTTPS_PROXY")
+    data_dir: str | None = None
+    allowed_resume_dirs: list[str] | None = None
+    cdp_url: str = "http://127.0.0.1:9222"
+    browser_idle_seconds: int = 300
+    enable_browser: bool = False
+    enable_patchright_fallback: bool = False
+    browser_user_data_dir: str | None = None
+    exact_token_count: bool = False
+    token_count_model: str = "claude-sonnet-4-5"
+    anthropic_api_key: str | None = Field(default=None, validation_alias="ANTHROPIC_API_KEY")
+    li_at: str | None = Field(default=None, validation_alias="LI_AT")
+    api_key: str | None = Field(default=None, validation_alias="API_KEY")
+    cors_allowed_origins: list[str] = Field(default=["*"], validation_alias="CORS_ALLOWED_ORIGINS")
+    rate_limit_per_minute: int = Field(default=60, validation_alias="RATE_LIMIT_PER_MINUTE")
+    oauth_metadata_url: str | None = None
+    oauth_client_id: str | None = None
+    oauth_client_secret: str | None = None
+    oauth_server_url: str | None = None

linkedin_mcp_zero/engines/__init__.py

@@ -0,0 +1,3 @@
+from linkedin_mcp_zero.engines.public_api import PublicAPIEngine
+
+__all__ = ["PublicAPIEngine"]