linkedin-relay-mcp 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,205 @@
1
+ ---
2
+ name: linkedin-relay
3
+ description: Research LinkedIn from the user's own account — search people/companies/jobs, read profiles, read the chronological feed. Use when finding or evaluating people, companies or roles on LinkedIn, or reading what the user's network is posting. Not for posting, messaging, or connection requests — those are CLI-only and require the human.
4
+ ---
5
+
6
+ # linkedin-relay
7
+
8
+ **"Research LinkedIn, not browse LinkedIn."** A CLI (`lnrelay`) + this read-only MCP surface, running
9
+ on the user's own logged-in session against LinkedIn's private Voyager API. No paid API, no browser
10
+ in the request path.
11
+
12
+ ## Three things to know before you call anything
13
+
14
+ 1. **Every call spends a budget that cannot be topped up.** Caps are deliberately low (30 profile
15
+ reads a day, 25 searches, 250 requests total) because LinkedIn restricts accounts for *read*
16
+ velocity alone — several documented restrictions involved no automation and no writes, just fast
17
+ browsing. Check `meta.budget.remaining`; when it's low, tell the user and stop rather than
18
+ spending the rest.
19
+
20
+ 2. **An empty result is not the same as a failed fetch, and you must tell them apart.** Read
21
+ `meta.state` and the counts on every collection. Getting this wrong means telling the user
22
+ "there's nothing there" when the truth is "we failed to read it" — the single most damaging thing
23
+ this tool can do.
24
+
25
+ 3. **Nothing is ever retried.** If a call fails with `RATE_LIMITED`, `REQUEST_DENIED`,
26
+ `CHALLENGE_DETECTED` or `COOLDOWN_ACTIVE`, a cross-process cooldown has opened and every
27
+ subsequent call will refuse until it lifts. **Do not loop.** Report it to the user and stop.
28
+
29
+ ## The funnel
30
+
31
+ ```
32
+ search cheap — cast wide, rank on the returned headline/location
33
+ ↓ pick 2-3 finalists from the search rows alone, not by reading each one
34
+ profile mid — deep-read ONLY the finalists
35
+ feed mid — what the user's network is posting right now
36
+ ↓ feed rows carry likes/comments counts — rank on those before reading a thread
37
+ post exp — a post's comment thread
38
+ reactions mid — who engaged with a post
39
+ whoami cheap — who we are authenticated as
40
+ risk / budget free — check standing BEFORE spending
41
+ ```
42
+
43
+ Search rows already carry name, headline, location and URL. **Rank on those.** Calling `profile` on
44
+ every search result is how a day's budget disappears in one request.
45
+
46
+ ## Commands
47
+
48
+ ### `search` — cheap. The net.
49
+ ```
50
+ search kind:people|companies|jobs query:"<terms>" [limit:1-25]
51
+ ```
52
+ Returns `{items, meta}`. Each item: `name`, `headline`, `location`, `url`, `urn`.
53
+
54
+ `meta.claimedCount` is LinkedIn's total for the query (often millions) — it is **not** how many you
55
+ got. `meta.state` is always `unknown` here: this is one page of many and we never claim exhaustion.
56
+
57
+ Out-of-network people come back as `name: "LinkedIn Member"` with a `/headless` URL. That is real
58
+ LinkedIn behaviour, not a bug — LinkedIn will not name them to this account. Say so rather than
59
+ presenting it as a data problem.
60
+
61
+ ### `profile` — mid. Read only the finalists.
62
+ ```
63
+ profile id:"<public-id|urn|linkedin.com/in/… URL>"
64
+ ```
65
+ Returns `headline`, `location`, `title`, `company`, `school`, `urn`.
66
+
67
+ **Known limit: no name.** None of LinkedIn's profile projections returns first/last name, so a
68
+ looked-up profile has a headline but no name attached. You supplied the identifier, so use that.
69
+ Don't tell the user the profile is empty — it isn't.
70
+
71
+ ### `feed` — mid. What the network is posting.
72
+ ```
73
+ feed [limit:1-20]
74
+ ```
75
+ Returns posts with `author`, `posted`, `text`, `url`, plus `likes`, `comments` and `threadUrn`.
76
+ Promoted posts are dropped and counted in `meta.excludedCount`, so `returnedCount` being lower than
77
+ `limit` is usually ads, not failure.
78
+
79
+ **Use the engagement counts to decide what to read.** A post with 601 comments and one with 3 cost
80
+ the same to fetch but are worth very different amounts. `threadUrn` is what `post` and `reactions`
81
+ take — pass it straight through rather than reconstructing it.
82
+
83
+ ### `post` — expensive. The full read.
84
+ ```
85
+ post urn:"<activity-urn | feed-update URL>" [limit:1-100]
86
+ ```
87
+ The comment thread on a post. Accepts a bare `urn:li:activity:…`, a
88
+ `urn:li:ugcPost:…`, or a `linkedin.com/feed/update/…` URL — no prior lookup needed.
89
+
90
+ Returns comments with `author`, `headline`, `text`, `postedAt`, `url`. `meta.state` is `unknown`:
91
+ this is the first page and pagination is not followed yet, so **never report a comment count as
92
+ complete**. Nested replies are not supported — a comment with replies does not carry them.
93
+
94
+ Read only the finalists. Feed and search rows already tell you how many comments a post has; use
95
+ that to decide whether the thread is worth a call.
96
+
97
+ ### `reactions` — medium. Who engaged.
98
+ ```
99
+ reactions urn:"<activity-urn | feed-update URL>" [limit:1-100]
100
+ ```
101
+ Who reacted and with which reaction type. Returns `name`, `headline`, `reaction`, `url`. Useful for
102
+ mapping who is paying attention to a topic — often more informative than the comments.
103
+
104
+ Same pagination caveat: `meta.state` is `unknown`.
105
+
106
+ ### `whoami` — cheap. Who we are.
107
+ Confirms the session works and which account it is. Good first call in a fresh session.
108
+
109
+ ### `local` — free. The default path after a research session.
110
+ ```
111
+ local query:"<terms>" [source:connections,my-posts,third-party] [since:YYYY-MM-DD] [limit:N]
112
+ ```
113
+ Offline search over whatever has been retained. **Costs nothing and spends no budget**, so prefer it
114
+ before reaching for a live command — if the answer is already cached, use it.
115
+
116
+ The cache only fills when a live read is run with `--retain` (CLI). If `meta.cachedTotal` is 0, the
117
+ cache is empty — that is not the same as LinkedIn having nothing, and the response says so.
118
+
119
+ ### `connections` / `my-posts` — free. Cache-backed.
120
+ ```
121
+ connections [query] [limit:N]
122
+ my-posts [query] [limit:N]
123
+ ```
124
+ The user's own graph and posts, read from the local cache. **Free — no network call.** If they come
125
+ back empty, the cache has not been filled: tell the user to run `lnrelay sync connections` (or
126
+ `sync my-posts`) rather than reporting that they have none.
127
+
128
+ ### `sync` — CLI-only. Fills the cache.
129
+ ```
130
+ lnrelay sync my-posts | lnrelay sync connections [--limit N] [--force]
131
+ ```
132
+ Not on this surface — the user runs it. Worth knowing it exists, because after a sync the `local`
133
+ tool can answer questions about their own posts and connections for free.
134
+
135
+ Connections refuse to re-sync more than once a week without `--force`: it is the most expensive read
136
+ in the tool and connections change slowly. Removals are only applied when the snapshot is complete —
137
+ if LinkedIn claims more connections than were retrieved, none are reported as removed, because they
138
+ were never looked at.
139
+
140
+ ### `cache-status` — free.
141
+ What is cached per source, sync checkpoints, and the retention policy. Third-party records expire 30
142
+ days after capture: the body is deleted and an identity stub remains, so a re-fetch is a visible
143
+ choice rather than a silent budget charge. Owner data never expires.
144
+
145
+ ### `risk` / `budget` — free, no network.
146
+ `risk` reports the circuit breaker. **Call it before a research session** rather than discovering a
147
+ lockout one wasted call at a time. `budget` reports spend per class with each cap's provenance.
148
+
149
+ ### `doctor` — free with offline.
150
+ Diagnoses setup end to end. The first thing to run when anything behaves oddly.
151
+
152
+ ## Reading `meta` — the part that matters
153
+
154
+ Every collection carries:
155
+
156
+ | field | meaning |
157
+ |---|---|
158
+ | `state: complete` | every reference resolved; an empty `items` here genuinely means none |
159
+ | `state: partial` | **some references failed to resolve** — the record is incomplete, not small |
160
+ | `state: unknown` | we stopped at the limit and cannot prove exhaustion (all searches) |
161
+ | `returnedCount` vs `claimedCount` | `claimed > 0` with `returned === 0` is a **failed fetch**, never "no results" |
162
+ | `excludedCount` | ads and UI chrome deliberately dropped |
163
+ | `unknownCount` / `unknownTypes` | **LinkedIn shipped a shape we don't recognise.** Data is still returned, but the parser is behind. Worth telling the user. |
164
+ | `unresolved` | URNs LinkedIn referenced but did not send |
165
+
166
+ If `unknownTypes` is non-empty, say so — it means LinkedIn changed something and the tool needs
167
+ re-capturing.
168
+
169
+ ## Errors, and what to do
170
+
171
+ | code | what it means | what you do |
172
+ |---|---|---|
173
+ | `AUTH_FAILED` | session expired (usually just old cookies, not detection) | tell the user to run `lnrelay login` |
174
+ | `COOLDOWN_ACTIVE` | a previous call tripped the breaker | **stop.** Report when it lifts. |
175
+ | `RATE_LIMITED` / `REQUEST_DENIED` | LinkedIn throttled or blocked us | **stop.** Do not retry. |
176
+ | `CHALLENGE_DETECTED` | LinkedIn wants to see a human | stop; only the user can clear it, in a browser |
177
+ | `BUDGET_EXHAUSTED` | our own cap, not LinkedIn's | tell the user what's left and stop |
178
+ | `SCHEMA_DRIFT` | the endpoint changed shape or moved | report it; this needs a maintainer, not a retry |
179
+ | `NOT_IMPLEMENTED` | designed but not built yet | say so plainly |
180
+
181
+ **None of these is retryable.** A `retryAfterMs` is information for the human, not permission to
182
+ call again.
183
+
184
+ ## What this tool will not do
185
+
186
+ Writes — posting, commenting, reacting — are **not on this surface at all**. They exist as CLI
187
+ commands (`lnrelay share`, `comment`, `react`) and go over LinkedIn's own official OAuth scope, not
188
+ the private API. Each stops at an interactive terminal, shows exactly what it will send, states the
189
+ ToS breach, and requires the user to type a token derived from the content.
190
+
191
+ **Without a terminal there is no write and no network call.** That is deliberate and there is no
192
+ flag that changes it: a flag an agent could set would not be confirming anything. If the user asks
193
+ you to post or comment, tell them the exact command to run themselves. Do not look for a way around
194
+ it, and do not offer one.
195
+
196
+ Connecting and messaging do not exist at all, in any surface. They are the actions where the
197
+ enforcement reports cluster, and an agent bug there is visible to a third party and unrecoverable.
198
+
199
+ Also absent by design: inbox reading, notifications, nested comment replies, and bulk sweeps.
200
+
201
+ ## Honest risk
202
+
203
+ This uses LinkedIn's private API with the user's own session. It **breaches LinkedIn's User
204
+ Agreement §8.2** and the account can be restricted or permanently banned. The tool never claims
205
+ otherwise, and neither should you. If the user seems unaware, say it once, plainly.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Tamás Gábor
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,98 @@
1
+ # linkedin-relay
2
+
3
+ Deep research over LinkedIn from your own account — a TypeScript CLI (`lnrelay`), a read-only MCP
4
+ server, and a Claude Code skill. No paid API.
5
+
6
+ Sibling to [`x-relay`](../x-relay), [`github-relay`](../github-relay) and
7
+ [`youtube-context`](../youtube-context); same stack, same shape, same philosophy.
8
+
9
+ ```bash
10
+ npm i -g linkedin-relay-mcp
11
+ lnrelay login # mint a session from your own Chrome
12
+ lnrelay search people "rust developer" # ranked rows: name, headline, location, url
13
+ lnrelay feed --compact # your feed, with engagement counts
14
+ lnrelay post <activity-urn> # a post's comment thread
15
+ lnrelay sync connections
16
+ lnrelay local "rust" # then search it offline, free
17
+ ```
18
+
19
+ ## As an MCP server
20
+
21
+ Thirteen read-only tools, so an agent does the reading. Writes are not on that surface at any price.
22
+
23
+ ```bash
24
+ claude mcp add linkedin-relay -s user -- bun "$(npm root -g)/linkedin-relay-mcp/dist/mcp-shim.js"
25
+ ```
26
+
27
+ ## Commands
28
+
29
+ | | |
30
+ |---|---|
31
+ | `search` · `profile` · `feed` | the research surface — people, companies, jobs |
32
+ | `post` · `reactions` | a post's comment thread, and who engaged |
33
+ | `sync` · `local` · `connections` · `my-posts` | fill a local cache, then query it for free |
34
+ | `whoami` · `doctor` · `risk` · `budget` · `cache-status` | session, standing and spend |
35
+ | `share` · `comment` · `react` | writes, over LinkedIn's official OAuth scope |
36
+ | `purge` | delete cached data |
37
+
38
+ Every command prints a JSON envelope on stdout. `--compact` and `--fields a,b` trim the output;
39
+ `--raw` keeps the original Voyager node for when a shape has drifted.
40
+
41
+ ## Design in one screen
42
+
43
+ - **Browserless raw HTTP** to LinkedIn's Voyager API. A real browser mints cookies once, via CDP, and
44
+ is never in the hot path.
45
+ - **Zero automatic retry.** A 429 is a warning shot, not a suggestion to wait and try again.
46
+ Cooldowns are a *file*, so the breaker survives across processes.
47
+ - **Reads are paced as conservatively as writes** — restrictions get triggered by fast browsing with
48
+ no automation involved at all.
49
+ - **Budget as a type.** The client cannot be called without a `Permit` whose only producer is the
50
+ ledger. An unaccounted network call is a compile error.
51
+ - **Parse by exclusion, never by an accept-list** — and report unknown types in the envelope. A scar
52
+ carried from `x-relay`, where an accept-list silently dropped every reply in every thread and 34 of
53
+ 77 posts per feed page while still returning `ok: true`.
54
+ - **Empty is never confused with failed.** Every collection reports `state`, `returnedCount` and
55
+ `claimedCount`; a claimed-but-empty response is an error, not "no results".
56
+ - **Third-party data is not cached by default.** When retained, a 30-day TTL swept on the read path;
57
+ on expiry the body dies and only an identity stub survives.
58
+ - **Writes need a human at a terminal.** No TTY, no write — and no network call on that path.
59
+ - **Single account by construction** — multi-account isn't disallowed, it's unrepresentable.
60
+
61
+ Full reasoning: **[docs/DESIGN.md](docs/DESIGN.md)** · Engine internals:
62
+ **[docs/ENGINE-RESEARCH.md](docs/ENGINE-RESEARCH.md)** · Build order: **[docs/PLAN.md](docs/PLAN.md)**
63
+
64
+ ## Risk
65
+
66
+ LinkedIn does not offer individual developers a sanctioned read API, so this uses their private
67
+ Voyager surface with your own session. That is against LinkedIn's User Agreement, and any account it
68
+ touches can be restricted. Most of the design above exists to keep that risk low — conservative
69
+ pacing, no retries, a breaker that stops on the first signal — but it cannot be eliminated. Use an
70
+ account you would not mind losing.
71
+
72
+ `lnrelay risk` reports current standing; `lnrelay budget` reports what has been spent.
73
+
74
+ ## Non-goals
75
+
76
+ Mass lead harvesting · multi-account operation or farms · proxy rotation · CAPTCHA solving ·
77
+ anti-detection tooling · reselling or sharing scraped data · outreach automation · anything that
78
+ touches another person's session.
79
+
80
+ ## How this was built
81
+
82
+ Five parallel research lanes fed a three-model design panel — GPT-5.6-Sol, Grok-4.5 and Fable 5 —
83
+ who each wrote an independent proposal, then read and attacked each other's. All three changed
84
+ position under argument. The convergence and the full disagreement record are in
85
+ [docs/DESIGN.md](docs/DESIGN.md); the raw proposals are in `.orchestrate/panel/` and the research in
86
+ [docs/research/](docs/research/).
87
+
88
+ ## Development
89
+
90
+ ```bash
91
+ bun run check # typecheck + lint + 273 tests
92
+ bun run build
93
+ bun run dev -- <command>
94
+ ```
95
+
96
+ ## License
97
+
98
+ MIT