pline-api

# pline.ai API — Agent skill and MCP

Use the hosted pline.ai API from an agent skill or an MCP client. Both integrations use your own
API key and call the same hosted scraping API. The scraping backend is not part of this repository.

| Integration | Contents | Requirements |
|---|---|---|
| [pline-api skill](skills/pline-api/SKILL.md) | Agent instructions, API reference, Python CLI for scrape, batch, crawl, map, and search | Python 3.10+; no pip dependencies |
| [MCP server](mcp-server/README.md) | Ten tools over local stdio; embedded usage guide and API reference | `npx -y pline-api` (Node.js 18+); also a Docker image, prebuilt binaries, or a Cargo source build |

**Fastest setup:** run `npx -y pline-api@latest init` and enter your API key. It configures every
supported MCP client on your machine and installs the skill; see [Quick install](#quick-install).

For remote agents, the MCP server also supports Streamable HTTP with Pline OAuth. Users sign in,
choose a workspace API key, and connect at the hosted `/mcp` URL; see
[`mcp-server/docs/oauth-hosting.md`](mcp-server/docs/oauth-hosting.md) for setup.

## Quick install

### One command: `init`

Needs Node.js 18+. Run it in a terminal:

```sh
npx -y pline-api@latest init
```

`init` finds the MCP clients on your machine, shows what it will change, asks you to confirm, and
asks for your pline.ai API key (input hidden; or set `PLINE_API_KEY` first). Then it:

| Client | What `init` does | Where the key is kept |
|---|---|---|
| Claude Code | `claude mcp add pline-ai --scope user …` | Claude Code's user config |
| Codex | `codex mcp add pline-api …` | `~/.codex/config.toml` |
| Cursor | adds `pline.ai` to `~/.cursor/mcp.json` | that file |
| VS Code | adds `pline.ai` to your user `mcp.json` | not stored; VS Code asks on first start |
| Claude Desktop | adds `pline.ai` to `claude_desktop_config.json` (macOS, Windows) | that file |
| Windsurf | adds `pline.ai` to `~/.codeium/windsurf/mcp_config.json` | that file |

It also installs the [agent skill](#skill-setup) for those agents with skills.sh. Existing config
files are merged, never replaced: other servers stay, a `*.pline-backup-<time>` copy is written first,
and files that are not plain JSON (for example with comments) are left alone and reported. Restart
your clients afterwards.

| Option | Effect |
|---|---|
| `--agent <id>` | Only this client; repeat for several: `claude-code`, `codex`, `cursor`, `vscode`, `claude-desktop`, `windsurf` |
| `--mcp-only` / `--skill-only` | Set up just the MCP server, or just the skill |
| `--dry-run` | Show what would change without changing anything |
| `--yes` | Skip the confirmation (needed when not running in a terminal) |
| `--base-url <url>` | Use another API base URL (default `https://apix.pline.ai/v1`) |

```sh
npx -y pline-api@latest init --agent cursor --agent claude-code   # only these clients
npx -y pline-api@latest init --dry-run                            # preview, change nothing
PLINE_API_KEY=your-key npx -y pline-api@latest init --yes         # non-interactive (scripts, CI)
```

Run `init` again at any time to change the key or add a newly installed client; it updates the
existing `pline` entries in place. To remove pline.ai, delete the `pline.ai` / `pline-ai` /
`pline-api` entry from each client (`claude mcp remove pline-ai --scope user`,
`codex mcp remove pline-api`) and run `npx skills remove pline-api -g`.

`npx -y pline-api` on its own is the MCP server, not the installer: run by hand it only waits for an
MCP client. Use `init` to set things up.

### Install separately

To set up the two integrations by hand instead, use either or both of the following.

**Agent skill** (instructions plus a Python CLI the agent runs):

```sh
npx skills add grepsr/pline-api
```

This copies [`skills/pline-api`](skills/pline-api/SKILL.md) from this GitHub repository into your
agent's skills folder (Claude Code, Cursor, Codex, and more). `skills` is the
[skills.sh](https://skills.sh) installer, not a pline package; the skill is not published to npm.
Running it needs Python 3.10+ and `PLINE_API_KEY` in the agent's environment (`PLINE_BASE_URL`
defaults to `https://apix.pline.ai/v1`); see
[Skill setup](#skill-setup).

**MCP server** (ten tools for any MCP client):

```sh
npx -y pline-api
```

You do not run this yourself: add it to your MCP client's configuration below and the client starts
it. It needs Node.js 18+ (or Docker).

The MCP server is the [`pline-api`](https://www.npmjs.com/package/pline-api) npm package, listed in the
[official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.grepsr/pline-api)
as `io.github.grepsr/pline-api`, and also shipped as the `ghcr.io/grepsr/pline-mcp` image.
Every MCP client takes the same configuration:

```json
{
  "mcpServers": {
    "pline.ai": {
      "command": "npx",
      "args": ["-y", "pline-api"],
      "env": {
        "PLINE_BASE_URL": "https://apix.pline.ai/v1",
        "PLINE_API_KEY": "your-own-api-key"
      }
    }
  }
}
```

| Client | One step |
|---|---|
| Claude Code | `claude mcp add pline-ai -e PLINE_BASE_URL=https://apix.pline.ai/v1 -e PLINE_API_KEY=your-own-api-key -- npx -y pline-api` |
| Claude Code plugin (skill + hosted server) | `claude plugin marketplace add grepsr/pline-api` then `claude plugin install pline-ai@pline-ai`; sign in with your pline.ai account on first use |
| Cursor | [![Add pline.ai to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=pline.ai&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInBsaW5lLWFwaSJdLCJlbnYiOnsiUExJTkVfQkFTRV9VUkwiOiJodHRwczovL2FwaXgucGxpbmUuYWkvdjEiLCJQTElORV9BUElfS0VZIjoieW91ci1vd24tYXBpLWtleSJ9fQ==) then replace `your-own-api-key` in Cursor's MCP settings |
| VS Code | [![Install pline.ai in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22pline.ai%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22pline-api%22%5D%2C%22env%22%3A%7B%22PLINE_BASE_URL%22%3A%22%24%7Binput%3Apline-base-url%7D%22%2C%22PLINE_API_KEY%22%3A%22%24%7Binput%3Apline-api-key%7D%22%7D%2C%22inputs%22%3A%5B%7B%22id%22%3A%22pline-base-url%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22pline.ai%20API%20base%20URL%22%2C%22default%22%3A%22https%3A%2F%2Fapix.pline.ai%2Fv1%22%7D%2C%7B%22id%22%3A%22pline-api-key%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22pline.ai%20API%20key%22%2C%22password%22%3Atrue%7D%5D%7D) [![Install pline.ai in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders:mcp/install?%7B%22name%22%3A%22pline.ai%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22pline-api%22%5D%2C%22env%22%3A%7B%22PLINE_BASE_URL%22%3A%22%24%7Binput%3Apline-base-url%7D%22%2C%22PLINE_API_KEY%22%3A%22%24%7Binput%3Apline-api-key%7D%22%7D%2C%22inputs%22%3A%5B%7B%22id%22%3A%22pline-base-url%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22pline.ai%20API%20base%20URL%22%2C%22default%22%3A%22https%3A%2F%2Fapix.pline.ai%2Fv1%22%7D%2C%7B%22id%22%3A%22pline-api-key%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22pline.ai%20API%20key%22%2C%22password%22%3Atrue%7D%5D%7D); VS Code prompts for the URL and key |
| Codex (CLI, IDE extension, app) | `codex mcp add pline-api --env PLINE_BASE_URL=https://apix.pline.ai/v1 --env PLINE_API_KEY=your-own-api-key -- npx -y pline-api`; see [Codex](#codex-1) to keep the key out of the config file |
| Windsurf, Claude Desktop, others | Paste the JSON above into the client's MCP configuration; see [MCP setup](#mcp-setup) for each file's location |

Opening this repository as a workspace configures the server automatically through
[`.cursor/mcp.json`](.cursor/mcp.json) and [`.vscode/mcp.json`](.vscode/mcp.json).
[PUBLISHING.md](PUBLISHING.md) tracks every registry and directory listing.

## Clone and configure for source builds or skills

```sh
git clone https://github.com/grepsr/pline-api.git
cd pline-api
cp .env.example .env
```

Edit `.env`: keep `PLINE_BASE_URL=https://apix.pline.ai/v1` (the public pline.ai API) and set
`PLINE_API_KEY` to your own key.

Load them before launching your agent or MCP client (POSIX shells):

```sh
set -a
. ./.env
set +a
```

Neither client loads `.env` automatically. On other platforms, set the same variables in your
shell or client settings. Git ignores `.env`, local session files, and build output.

## Skill setup

The `pline-api` skill teaches an agent how to choose an API operation, reuse scrape sessions,
extract structured data, poll background jobs, and save results. It uses connected pline.ai MCP
tools when available; otherwise it runs the bundled Python client. A skill-only installation
requires **Python 3.10+, Git, and a pline.ai API key**; the API base URL is `https://apix.pline.ai/v1`. It does not
require Rust, a compiled MCP binary, or pip packages.

`npx -y pline-api@latest init` installs the skill together with the MCP server
(`--skill-only` for just the skill). To install the skill on its own, use the
[`skills`](https://skills.sh) CLI, which copies the skill from this GitHub
repository (not from npm) into the right folder for each agent it detects (add `-g` for a user-wide
install, `-a cursor` to pick agents):

```sh
npx skills add grepsr/pline-api
```

To install by hand, copy the **whole directory**, not just `SKILL.md`:

```text
pline-api/
├── SKILL.md                 # Instructions and when to use the skill
├── scripts/pline.py         # Python client
├── references/endpoints.md  # API fields, examples, and limits
└── agents/openai.yaml       # Codex display metadata
```

The agent needs permission to execute Python, reach your pline.ai API over HTTPS, and write to
any output directory