linkedin-mcp-server: Instructions file for Codex

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands

• Use uv for dependency management: uv sync (dev: uv sync --group dev)
• Lint: uv run ruff check . (auto-fix with --fix)
• Format: uv run ruff format .
• Type check: uv run ty check (using ty, not mypy)
• Tests: uv run pytest (with coverage: uv run pytest --cov)
• Pre-commit: uv run pre-commit install then uv run pre-commit run --all-files
• Run server locally: uv run -m linkedin_mcp_server --no-headless
• Run via uvx (PyPI/package verification only): uvx mcp-server-linkedin
• Docker build: docker build -t linkedin-mcp-server .
• Install browser: uv run patchright install chromium

Scraping Rules

• One section = one navigation. Each entry in PERSON_SECTIONS / COMPANY_SECTIONS (scraping/fields.py) maps to exactly one page navigation. Never combine multiple URLs behind a single section.
• Minimize DOM dependence. Prefer innerText and URL navigation over DOM selectors. When DOM access is unavoidable, use minimal generic selectors (a[href*="/jobs/view/"]) — never class names tied to LinkedIn's layout.
• Detection must be locale-independent. Classification logic — connection state, action availability, button identity — must rely on URL patterns (/preload/custom-invite/?vanityName=USER, /in/USER/edit/intro/, /messaging/compose/), attribute presence (aria-label exists, aria-expanded exists, aria-disabled exists), or structural counts — never on text values like "Connect", "Follow", "Message", "1st", "Pending". The verb in an aria-label is locale-dependent; whether the attribute exists is not. Where text is genuinely the only signal, guard it behind an explicit per-locale table and document the limitation in code.

Tool Return Format

All scraping tools return: {url, sections: {name: raw_text}}.

Optional additional keys:

• references: {section_name: [{kind, url, text?, context?, value?}]} — LinkedIn URLs are relative paths; value carries non-URL identifiers (e.g. company URN id for kind: "company_urn")
• section_errors: {section_name: {error_type, error_message, issue_template_path, runtime, ...}}
• unknown_sections: [name, ...]
• job_ids: [id, ...] (search_jobs only)
• references["feed"] (get_feed only) — every entry is kind: "feed_post"; non-post anchors (sidebar profiles, employer logos) are filtered. URLs may carry either /feed/update/<urn>/ (DOM-anchor-derived) or /posts/<slug> (SDUI-derived) form; both are valid LinkedIn permalinks. Cap is 50 entries, matching get_feed's num_posts ceiling.