# shared-url-mcp

An MCP server with one job: read a shared AI conversation link and write the
whole thing to Markdown.

It exists because ordinary web-fetch tools fail on these links, and they each
fail for a different reason:

| Share link | What a normal fetch gets | What this does instead |
| --- | --- | --- |
| `claude.ai/share/...` | a 4 KB Cloudflare challenge shell with no conversation in it | reads `claude.ai/api/chat_snapshots/<id>`, which returns clean JSON |
| `chatgpt.com/share/...` | 500 KB of HTML with the messages buried in an index-deduplicated string table | reads `chatgpt.com/backend-api/share/<id>`, which returns clean JSON |
| `gemini.google.com/share/...` | an Angular shell containing zero conversation text | renders the page and waits for the transcript to arrive |
| `chat.deepseek.com/share/...` | HTTP 202 with an empty body, from AWS WAF bot protection | retries in a real browser window, which the challenge lets through |

Works with any MCP-capable agent CLI: Claude Code, Codex, OpenCode, Cursor,
Cline, Windsurf, Zed, and anything else that speaks MCP over stdio. Runs on
Windows, macOS and Linux.

## Install

```bash
git clone https://github.com/AbdoKnbGit/shared_url_mcp.git
cd shared_url_mcp
npm run setup
```

That is the whole install. `npm run setup` installs dependencies, builds, sorts
out a browser, and registers the server with every agent CLI it finds:

```
3. Wiring agent CLIs
  ✓ Claude Code: registered (all projects)
  ✓ Codex: registered in ~/.codex/config.toml
  ✓ OpenCode: registered in ~/.config/opencode/opencode.json
  ✓ Cursor: registered in ~/.cursor/mcp.json
  · Windsurf: not installed, skipped
```

Restart your CLI afterwards, since MCP servers are loaded at startup. Then paste
a link:

> read this: `https://chatgpt.com/share/<id>`

Preview without changing anything:

```bash
npm run setup -- --list
```

### Browsers are handled for you

Most links never need one. For the pages that do, the server drives an installed
Chrome or Edge if you have either, and downloads Chromium by itself the first
time it needs to otherwise. There is nothing to install by hand.

## Updating

```bash
npm run update
```

That pulls, reinstalls, and rebuilds in place. Every client you wired points at
the same `dist/index.js`, so they all pick up the new version the next time they
start. No reconfiguration, and no need to re-run `setup`.

Re-run `npm run setup` only when you want to wire a CLI you installed later.

## Tools

Two, deliberately.

### `read_shared_link`

Fetches the link, saves the full conversation, and hands the agent a skeleton
rather than the transcript: the title, the message count, and an outline of every
turn with its line number.

```
# Predict Admission Status

16 messages from Gemini, model 3.1 Pro, 43,138 characters.

## Outline
  1. line    24  User      please construct the full text from these images
  2. line    31  Assistant Here is the complete text reconstructed from the...
  3. line   142  User      here's the continuation
```

So the agent knows what the conversation is and where everything sits, then
reads only what a question actually needs: those exact lines, a search for one
term, or the whole file. Nothing is truncated. The complete session is in
`conversation.md`; the skeleton just lets the agent read it on demand instead of
swallowing it whole.

### `inspect_shared_link`

Read-only check: which provider, where the link redirects, whether it is still
reachable, and whether a browser is needed. Use it to diagnose a link that
failed instead of retrying a full extraction.

## Output

```
shared-url/
└── gemini-predict-admission-status/
    ├── conversation.md
    └── metadata.json
```

`conversation.md` holds YAML front matter and the full transcript, one `##`
section per message, with reasoning in collapsed blocks and code in fenced
blocks. `metadata.json` holds the same facts in structured form plus an outline
mapping every message to its line number.