# linkforyou-mcp

[![CI](https://github.com/AdamCejpa/linkforyou-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/AdamCejpa/linkforyou-mcp/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/linkforyou-mcp)](https://www.npmjs.com/package/linkforyou-mcp)
[![license](https://img.shields.io/npm/l/linkforyou-mcp)](./LICENSE)

An [MCP](https://modelcontextprotocol.io) server for [linkfor.you](https://linkfor.you) — create and manage
short links from Claude, Cursor, or any other MCP client.

> "Shorten this changelog URL as `/aug-release` and point the QR code we printed at the new docs page."

linkfor.you is a link shortener with **cookieless, GDPR-safe analytics**, custom domains, and EU hosting —
so an agent can create trackable links without dropping a tracking cookie on anyone.

## What the agent can do

| Tool | Description |
| --- | --- |
| `get_account` | The account the API key belongs to. Useful as a first call to confirm the key works. |
| `list_links` | The account's links, newest first, cursor-paginated. |
| `get_link` | One link by id. |
| `create_link` | Create a short link, with an optional custom slug and title. |
| `update_link` | Change destination, slug, title or status. Repointing `dest` also repoints an already-printed QR code. |
| `delete_link` | Permanently delete a link. Marked destructive, so well-behaved clients confirm first. |

Tool definitions are served by linkfor.you itself and forwarded verbatim, so this list is whatever the
account's plan currently exposes — the package does not need updating when a tool changes.

## Requirements

- A [linkfor.you](https://linkfor.you) account.
- **A paid plan.** API and MCP access is a paid feature; on the free plan every call returns a `403` that
  says so. Write tools additionally require a verified email address.
- Node.js 18.17 or newer.

## Get an API key

1. Sign in at [linkfor.you/login](https://linkfor.you/login).
2. Open **Settings → API keys**: [linkfor.you/dashboard/settings#sec-api](https://linkfor.you/dashboard/settings#sec-api).
3. Create a key. **It is shown once** — if it is lost it must be reset, not recovered.

A key carries the full rights of its owner over that owner's links: read, create, update and delete. There
are no scopes and no read-only keys. Treat it as a secret.

## Setup

### Claude Code

```bash
claude mcp add linkfor --env LINKFOR_API_KEY=lfy_your_key -- npx -y linkforyou-mcp
```

### Claude Desktop

Add to `claude_desktop_config.json` (**Settings → Developer → Edit Config**):

```json
{
  "mcpServers": {
    "linkfor": {
      "command": "npx",
      "args": ["-y", "linkforyou-mcp"],
      "env": {
        "LINKFOR_API_KEY": "lfy_your_key"
      }
    }
  }
}
```

### Cursor

Add the same block to `.cursor/mcp.json` in your project, or to `~/.cursor/mcp.json` globally.

### Any other stdio client

Run `npx -y linkforyou-mcp` with `LINKFOR_API_KEY` in the environment. The process speaks newline-delimited
JSON-RPC on stdin/stdout; stdout carries protocol messages only, and everything human-readable goes to stderr.

### Clients that speak remote MCP directly

You do not need this package. linkfor.you hosts a Streamable HTTP MCP endpoint — point the client at it:

```
https://linkfor.you/api/mcp     Authorization: Bearer lfy_your_key
```

There is a [server card](https://linkfor.you/.well-known/mcp/server-card.json) describing it. This package
exists for the many clients that only launch local stdio processes, or that cannot attach a custom header.

## Configuration

| Variable | Default | Purpose |
| --- | --- | --- |
| `LINKFOR_API_KEY` | — | **Required.** Your API key. |
| `LINKFOR_BASE_URL` | `https://linkfor.you` | Override the host. Mainly for development. |
| `LINKFOR_TIMEOUT_MS` | `20000` | Per-request timeout, clamped to 1 000–120 000. |

## How it works

The package is a transparent JSON-RPC proxy — roughly 300 lines, **no runtime dependencies**. It reads a
line from stdin, adds one `Authorization` header, POSTs it to `https://linkfor.you/api/mcp`, and writes the
reply back as a line.

It deliberately does not reimplement the tools. Names, schemas, descriptions, validation and error text all
live on the server, which means the two surfaces cannot drift, and a tool added or reworded server-side
reaches every installed copy without a release.

The one piece of real logic is failure translation. A stdio client that receives no line for an id waits
forever, so every transport failure — an HTTP error, a timeout, an unreachable host, a non-JSON body — comes
back as a JSON-RPC error carrying the server's own explanation. Notifications, which have no id, are never
answered.

## Security

- The key is read from the environment and sent as a Bearer header. It is never logged, and never written
  to stdout.
- Keep it out of your repository. In Claude Desktop and Cursor the config file holding it is outside the
  project; for project-scoped config, prefer an environment variable over a literal.
- `delete_link` is irreversible and is annotated `destructiveHint`, which is a client's cue to confirm with
  you first. To take a link out of service reversibly, ask for `update_link` with status `paused` instead.

## Development

```bash
npm install
npm run typecheck
npm test
npm run build
```

Smoke-test the built server by hand:

```bash
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | LINKFOR_API_KEY=lfy_your_key node dist/index.js
```

## Links

- [linkfor.you](https://linkfor.you) · [API docs](https://linkfor.you/docs) · [Authentication](https://linkfor.you/auth.md)
- [Model Context Protocol](https://modelcontextprotocol.io)

## License

MIT