feat(search_people): add network and current_company filters (#248)

[mvanhorn]

Summary

• Add two optional params to search_people: network (1st / 2nd / 3rd degree filter, tokens "F" / "S" / "O") and current_company (current-employer filter, accepts a company name or URN id).
• Threaded through tools/person.py and scraping/extractor.py onto the existing LinkedIn search URL. Encodes the two facets as network=%5B%22F%22%5D and currentCompany=%5B%22Weber+Inc%22%5D via a small list-facet helper.
• Invalid network tokens raise ValueError at the extractor boundary.
• 6 new extractor tests, 1 new tool test, README and manifest.json updated.

Closes #248 (company-filter half; the industry filter from the second half is a natural follow-up PR once this shape is accepted).

Motivation

Concrete user story that motivated this: a user has Jennifer Bonuso (President Americas at Weber Inc) as a 1st-degree connection, but search_people("Weber Inc") returns only 2nd-degree results and omits her. After this PR, search_people(keywords="Weber Inc", network=["F"]) constrains the results page to 1st-degree.

Before:

https://www.linkedin.com/search/results/people/?keywords=Weber+Inc

After (with the new params):

https://www.linkedin.com/search/results/people/?keywords=Weber+Inc&network=%5B%22F%22%5D&currentCompany=%5B%22Weber+Inc%22%5D

Prior Art

Inspired by:

• feat: add search_people tool with 1st degree connection support #152 (@danmunz) - "feat: add search_people tool with 1st degree connection support". Maintainer comment: "Would love to merge this feature!" Draft stale against current main after the scraper inlining.
• feat: add structured filters to search_people #320 (@arwinsoetanto) - "feat: add structured filters to search_people". 121 files, sprawl.
• Add search_people_with_past_company tool for advanced people filtering #205 (@guykwan) - "Add search_people_with_past_company tool". Different approach (separate tool).

This PR delivers the core of #152 and part of #320 as a minimal, current-main-aligned diff that follows the search_jobs filter pattern already in extractor.py.

Testing

• uv run pytest - 395 passed locally, including 6 new extractor tests and 1 new tool test covering single-degree, multi-degree, current_company, invalid token, and combined-filter URL construction.
• uv run ruff check . - clean
• uv run ruff format . - clean
• uv run ty check - clean
• uv run pre-commit run --all-files - clean

Tests exercise URL construction only. Live verification against LinkedIn's rendered page is not included in this PR since it requires an authenticated browser session; happy to add notes from a manual live run if you want that before merge.

Out of scope

• Industry filter from the second half of [FEATURE] What connections do I have at <company>? #248 (follow-up PR).
• Past-company filter (spirit of Add search_people_with_past_company tool for advanced people filtering #205; separate PR).
• Pagination beyond page 1.

Synthetic prompt

Add two optional params to search_people in linkedin_mcp_server/tools/person.py and linkedin_mcp_server/scraping/extractor.py: network: list[str] | None (tokens "F" / "S" / "O" for 1st / 2nd / 3rd degree) and current_company: str | None. Validate network tokens at the extractor; invalid tokens raise ValueError. Encode both as URL-encoded JSON list facets (network=%5B%22F%22%5D, currentCompany=%5B%22Weber+Inc%22%5D) via a small helper. Update manifest.json tool description and the README tool table. Add extractor tests for single-degree, multi-degree, current_company, invalid token, and combined-filter URL construction, plus a tool test that forwards kwargs. Keep the diff under ~150 core-source lines and follow the search_jobs filter pattern.

Generated with Claude Opus 4.7 (1M context)

[stickerdaniel]

Thanks! Let me know when it's ready for review

[mvanhorn]

Ready for review @stickerdaniel - all CI green (lint-and-check, test, Socket Security). Thanks!

[greptile-apps]

Greptile Summary

This PR adds two optional filter parameters — network (connection-degree, tokens "F" / "S" / "O") and current_company (numeric URN only) — to search_people, following the existing search_jobs filter pattern throughout the stack.

• extractor.py introduces _encode_list_facet (using json.dumps), a FilterValidationError subclass of ValueError, ASCII-only URN validation via re.fullmatch, and threads both params onto the LinkedIn search URL.
• person.py forwards the new params, catches FilterValidationError and re-raises it as ToolError so the actionable message reaches the MCP client instead of being masked, and adds except ToolError: raise to prevent the generic handler from swallowing already-formatted errors.
• Eight extractor tests and two tool tests cover single/multi-degree network filters, URN validation (including Unicode-digit rejection), empty-string noop, combined filters, and the FilterValidationError → ToolError promotion path.

Confidence Score: 5/5

Safe to merge — the change is additive, all new params are optional with None defaults, validation is strict and tested, and the error-promotion path from extractor to MCP client is correctly guarded.

All new parameters default to None, leaving existing callers unaffected. Validation (network token allow-list, ASCII-only URN regex) is exercised by 8 targeted tests including Unicode-digit edge cases. The FilterValidationError → ToolError promotion and the bare except ToolError: raise guard are both covered by dedicated tool tests. No regressions are introduced to the existing search_people call path.

No files require special attention.

Important Files Changed

Filename	Overview
linkedin_mcp_server/scraping/extractor.py	Adds network and current_company params to search_people, with a FilterValidationError subclass, ASCII-only URN validation via re.fullmatch, and _encode_list_facet helper using json.dumps. Logic is tight and consistent with the existing search_jobs pattern.
linkedin_mcp_server/tools/person.py	Threads new params through the MCP tool, catches FilterValidationError and re-raises as ToolError, and adds a bare except ToolError: raise to prevent the generic error handler from swallowing already-formatted client errors.
tests/test_scraping.py	Adds 8 new extractor tests covering single-degree, multi-degree, current_company URN, invalid token, Unicode-digit rejection, empty-string noop, and combined-filter URL construction. Good edge-case coverage.
tests/test_tools.py	Adds 2 new tool tests: one verifying kwarg forwarding and one confirming FilterValidationError surfaces as ToolError with the original message intact.
manifest.json	Tool description updated to mention connection degree and current company filters — straightforward doc update.
README.md	README tool table updated to reflect new filter capabilities — accurate and consistent with the implementation.

Sequence Diagram

sequenceDiagram
    participant Client as MCP Client
    participant Tool as person.py (search_people)
    participant Extractor as extractor.py (search_people)
    participant LinkedIn as LinkedIn Search URL

    Client->>Tool: search_people(keywords, network, current_company)
    Tool->>Extractor: "extractor.search_people(keywords, location, network=, current_company=)"

    alt network tokens invalid
        Extractor-->>Tool: raise FilterValidationError
        Tool-->>Client: raise ToolError (message preserved)
    else current_company not numeric URN
        Extractor-->>Tool: raise FilterValidationError
        Tool-->>Client: raise ToolError (message preserved)
    else params valid
        Extractor->>Extractor: build params + network + currentCompany
        Extractor->>LinkedIn: extract_page(url)
        LinkedIn-->>Extractor: page content
        Extractor-->>Tool: "{url, sections}"
        Tool-->>Client: "{url, sections}"
    end

Loading

_{Reviews (4): Last reviewed commit: "fix(search_people): reject non-numeric c..." | Re-trigger Greptile}

[stickerdaniel]

Live-tested all three network tokens against my account. F/S/O filter
cleanly, URL encoding matches what LinkedIn's UI generates, combinations
work. Network half is good.

current_company doesn't actually filter on plain text though. Compared
"SAP" and "Anthropic" against the same keyword set, LinkedIn returns
the same unfiltered result set for both. Only the numeric URN id ("1115"
for SAP) hits the facet. With that, 8/10 results were SAP employees as
expected. The Weber Inc example in the PR body wouldn't filter in practice.

Two things before merge:

• Description + README: current_company takes a numeric LinkedIn
  company URN id, not a name. Plain text is silently dropped by LinkedIn.
• Validation: non-numeric current_company should raise ValueError
  pointing at get_company_profile for the URN.

Validation depends on get_company_profile exposing the URN, which it
doesn't yet. Opened #430 for that, I'll take it.

[stickerdaniel]

@mvanhorn #430 merged. URN now in get_company_profile.references[about].

[mvanhorn]

Pushed a327845:

• _encode_list_facet now uses json.dumps with compact separators, so quotes/backslashes in values escape cleanly (greptile P2 from the inline review). Existing URL-encoding tests still pass.
• current_company docstrings (extractor + tool) flipped to make the URN-only requirement clear. Plain names are accepted by the URL but won't filter; URN can be pulled from get_company_profile.references["about"] now that [FEATURE] Surface company URN id in get_company_profile references #430 has shipped. Thanks for the live-test confirmation.