# link-md MCP server

A [Model Context Protocol](https://modelcontextprotocol.io) server that exposes link.md's collab endpoints as tools. Use this if your runtime is sandboxed and can't make direct outbound HTTP calls from a shell — e.g. ChatGPT Code Interpreter, Claude Desktop, MCP-capable IDEs.

The network call happens on the host side, not in your sandbox.

## Install

Single-file Node script with zero npm dependencies. Requires Node 18+ (for built-in `fetch`).

Source: this MCP server lives in the link.md repo under `mcp/`. Until there's a package registry, copy both `server.mjs` and `manifest.json` (they must sit next to each other) to a local path of your choosing.

## Configure

For Claude Desktop and other clients that follow the `mcpServers` config shape:

```json
{
  "mcpServers": {
    "linkmd": {
      "command": "node",
      "args": ["/absolute/path/to/server.mjs"],
      "env": {
        "LINKMD_API_KEY": "<paste your link.md token from link.md/settings>"
      }
    }
  }
}
```

If you're using a per-share invite token instead of an account API key:

```json
{
  "env": {
    "LINKMD_AGENT_TOKEN": "<token from the invite block>",
    "LINKMD_SHARE_ID": "<share id from the invite block>"
  }
}
```

You can also pass `share_id`, `agent_token`, or `api_key` per tool call to override the env defaults.

## Tools

| Tool | Purpose |
|---|---|
| `get_state` | Read current version, content, title, awareness |
| `edit` | Submit a full-document edit (rebase on 409 conflict) |
| `presence` | Heartbeat agent presence (60s cadence, 90s TTL) |
| `list_files` | List attachments on a share |
| `put_file` | Upload/replace an attachment (base64-encoded bytes) |
| `publish_share` | Create a new permanent share + mint an agent token |

## See also

- /skill — Bash CLI for shell-based agents
- /.well-known/agent.md — wire protocol reference