Development Commands

CLAUDE.md

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

Development Commands

Environment Setup:

• Use uv for dependency management: uv sync (installs all dependencies)
• Development dependencies: uv sync --group dev
• Bump version: uv version --bump minor (or major, patch) - git tag is created automatically by release workflow. Once Docker image and PyPI package are published, manually file a PR in the MCP registry to update the version.
• Run server locally: uv run -m linkedin_mcp_server --no-headless
• Run via uvx (PyPI): uvx linkedin-scraper-mcp
• Run in Docker: docker run -it --rm -v ~/.linkedin-mcp:/home/pwuser/.linkedin-mcp stickerdaniel/linkedin-mcp-server:latest

Code Quality:

• 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 hooks: uv run pre-commit install then uv run pre-commit run --all-files

Docker Commands:

• Build: docker build -t linkedin-mcp-server .
• Get session: Use uvx locally first: uvx linkedin-scraper-mcp --get-session

Architecture Overview

This is a LinkedIn MCP (Model Context Protocol) Server that enables AI assistants to interact with LinkedIn through web scraping. The codebase follows a two-phase startup pattern:

1. Authentication Phase (authentication.py) - Validates LinkedIn session file exists
2. Server Runtime Phase (server.py) - Runs FastMCP server with tool registration

Core Components:

• cli_main.py - Entry point with CLI argument parsing and orchestration
• server.py - FastMCP server setup and tool registration
• tools/ - LinkedIn scraping tools (person, company, job profiles)
• drivers/browser.py - Playwright browser management with session handling
• config/ - Configuration management (schema, loaders)
• authentication.py - LinkedIn session management

Tool Categories:

• Person Tools (tools/person.py) - Profile scraping with contacts, interests, experiences, education
• Company Tools (tools/company.py) - Company profile and posts extraction
• Job Tools (tools/job.py) - Job posting details and search functionality

Available MCP Tools:

Authentication Flow:

• Uses session files stored at ~/.linkedin-mcp/session.json
• Run with --get-session to create a session via browser login

Transport Modes:

• stdio (default) - Standard I/O for CLI MCP clients
• streamable-http - HTTP server mode for web-based MCP clients

Development Notes

• Python Version: Requires Python 3.12+
• Package Manager: Uses uv for fast dependency resolution
• Browser: Uses Playwright with Chromium for browser automation
• Logging: Configurable levels, JSON format for non-interactive mode
• Error Handling: Comprehensive exception handling for LinkedIn rate limits, captchas, etc.

Key Dependencies:

• fastmcp - MCP server framework
• linkedin_scraper - LinkedIn web scraping (v3 with Playwright)
• playwright - Browser automation

Configuration:

• CLI arguments with comprehensive help (--help)
• Session stored at ~/.linkedin-mcp/session.json

Commit Message Format:

• Follow conventional commits: type(scope): subject
• Types: feat, fix, docs, style, refactor, test, chore, perf, ci
• Keep subject <50 chars, imperative mood

Commit Message Guidelines

Commit Message Rules:

• Always use the commit message format type(scope): subject
• Types: feat, fix, docs, style, refactor, test, chore, perf, ci
• Keep subject <50 chars, imperative mood

Important Development Notes

Development Workflow

• Never sign a PR or commit with Claude Code
• When implementing a new feature/fix, follow this process:
  1. Check open issues. If no issue exists for the feature, create one that follows the feature issue template.
  2. Create a new branch from main and name it feature/issue-number-short-description
  3. Implement the feature
  4. Test the feature
  5. Make sure the README.md, docs/docker-hub.md and AGENTS.md is updated with the new feature
  6. Create a PR with a short description of the feature/fix
  7. First review the PR with ai agents.
  8. Manually review the PR and merge it if it's approved. Do not squash the commits.
  9. Delete the branch after the PR is merged.

btca

When you need up-to-date information about technologies used in this project, use btca to query source repositories directly.

Available resources: fastmcp, linkedinScraper, playwright, pytest, ruff, ty, uv, inquirer, pythonDotenv, pyperclip, preCommit

Usage

btca ask -r <resource> -q "<question>"

Use multiple -r flags to query multiple resources at once:

btca ask -r fastmcp -r playwright -q "How do I set up browser context with FastMCP tools?"