# amp-mcp

`amp-mcp` lets MCP-compatible coding harnesses read Amp threads referenced in commit messages, pull requests, and source code.

It exposes one tool, `read_amp_thread`. The server is deliberately read-only: it cannot create, continue, rename, share, archive, or delete threads.

## How it works

The server runs locally over stdio and calls the authenticated Amp CLI:

```text
MCP host → read_amp_thread → amp threads markdown → Amp
```

It does not read, copy, or store Amp credentials. A thread is available only when `amp threads markdown <thread-id>` allows the signed-in user to read it.

## Requirements

- Node.js 20 or later
- The [Amp CLI](https://ampcode.com/manual) installed and signed in

Verify Amp before configuring the MCP server:

```sh
amp --version
amp threads markdown T-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
```

## Install from this checkout

```sh
npm install
npm run build
```

Configure your coding harness to launch the built server. Most MCP hosts accept this shape:

```json
{
  "mcpServers": {
    "amp-threads": {
      "command": "node",
      "args": ["/absolute/path/to/amp-mcp/dist/index.js"]
    }
  }
}
```

If the host cannot find `amp` (common when a desktop app has a restricted `PATH`), set its absolute location:

```json
{
  "mcpServers": {
    "amp-threads": {
      "command": "node",
      "args": ["/absolute/path/to/amp-mcp/dist/index.js"],
      "env": {
        "AMP_CLI_PATH": "/absolute/path/to/amp"
      }
    }
  }
}
```

Find that path with `command -v amp` on macOS/Linux or `where amp` on Windows.

After this package is published, hosts can instead launch it with `npx`:

```json
{
  "mcpServers": {
    "amp-threads": {
      "command": "npx",
      "args": ["-y", "amp-mcp"]
    }
  }
}
```

## Tool

### `read_amp_thread`

Reads a thread as Markdown. `thread` accepts all common reference forms:

- `T-019fcd6f-9212-7238-aaf7-3f08ffee3c7f`
- `@T-019fcd6f-9212-7238-aaf7-3f08ffee3c7f`
- `https://ampcode.com/threads/T-019fcd6f-9212-7238-aaf7-3f08ffee3c7f`

Long threads are returned in pages. The optional arguments are:

| Argument | Default | Description |
| --- | ---: | --- |
| `offset` | `0` | Character offset at which to read; negative values count from the end |
| `limit` | `100000` | Maximum characters to return, up to `500000` |
| `include_tool_outputs` | `true` | Set to `false` to replace raw tool results with omission markers |
| `max_tool_output_length` | — | Truncate each tool result to this many characters |
| `mode` | `full` | Set to `metadata` for thread metadata and the latest conversation message |

Filtering is applied before offsets and character counts, so pagination offsets always refer to
the selected representation. When more content exists, the result gives the exact `offset` for
the next call. For example, `offset: -100000` reads the final 100,000 characters without first
fetching the beginning of the thread.

Metadata mode returns the title, creation time, agent mode, readable status, user-turn count,
original and filtered character lengths, and the latest non-tool-result conversation message.
The Amp Markdown export does not expose live execution status, which is called out in the result.

## Development

```sh
npm run check
```

To exercise the server interactively with the MCP Inspector:

```sh
npx @modelcontextprotocol/inspector node dist/index.js
```

Copyright © [Archestra AI](http://archestra.ai/)