# Quip MCP Server

[![CI](https://github.com/lzongren/quip-local-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/lzongren/quip-local-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A Model Context Protocol (MCP) server that provides native access to Quip documents from any MCP-compatible AI client (Claude Desktop, Claude Code, or custom integrations). Search, browse, and read Quip documents as clean markdown — enabling powerful workflows like querying interview schedules, reviewing application materials across folders, or generating preparation plans from scattered documents.

## Features

- **Search documents** — Full-text search across your Quip workspace
- **Browse folders** — List folder contents or recursively explore folder trees
- **Read documents** — Fetch document content converted to clean markdown
- **User info** — Get current user profile and root folder IDs

## Tools

| Tool | Description | Parameters |
|------|-------------|------------|
| `quip_get_user` | Get current user info and folder IDs | — |
| `quip_get_folder` | List threads and subfolders in a folder | `folder_id` |
| `quip_get_document` | Fetch document content as markdown | `thread_id`, `max_length?` (default 50k) |
| `quip_search` | Search documents by query | `query`, `count?` (default 20) |
| `quip_browse_folder_tree` | Recursively explore folder hierarchy | `folder_id`, `max_depth?` (default 3) |

## Setup

### Prerequisites

- Node.js 18+
- A Quip API access token ([generate one here](https://quip.com/dev/token))

### Install & Build

```bash
npm install
npm run build
```

### Configure with MCP Clients

#### Claude Code

```bash
claude mcp add -s user \
  -e QUIP_ACCESS_TOKEN="<your-token>" \
  -e QUIP_API_BASE="https://platform.quip.com" \
  quip -- node /path/to/quip-local-mcp/build/index.js
```

#### Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "quip": {
      "command": "node",
      "args": ["/absolute/path/to/quip-local-mcp/build/index.js"],
      "env": {
        "QUIP_ACCESS_TOKEN": "<your-token>",
        "QUIP_API_BASE": "https://platform.quip.com"
      }
    }
  }
}
```

**Note**: For custom Quip domains, change `QUIP_API_BASE` accordingly (e.g., `https://yourcompany.quip.com`).

## Development

```bash
npm run dev          # Watch mode (recompile on changes)
npm run lint         # Type check (tsc --noEmit)
npm test             # Run tests
npm run test:watch   # Run tests in watch mode
npm run test:coverage # Run tests with coverage report
```

## Architecture

```
src/
├── index.ts              # MCP server entry point (stdio transport)
├── quip-client.ts        # Quip REST API client (auth, rate limiting, retries)
├── html-converter.ts     # HTML → Markdown via Turndown with Quip-specific rules
├── types.ts              # TypeScript interfaces for Quip API responses
└── tools/
    ├── get-user.ts       # quip_get_user
    ├── get-folder.ts     # quip_get_folder
    ├── get-document.ts   # quip_get_document
    ├── search.ts         # quip_search
    └── browse-tree.ts    # quip_browse_folder_tree
```

### Key Design Decisions

- **HTML → Markdown via Turndown** — Quip returns HTML; Turndown converts it to clean markdown for LLM consumption with custom rules for Quip-specific elements (checklists, section wrappers, embedded spreadsheets).
- **Client-side rate limiting** — Token bucket at 40 req/min (conservative vs Quip's 50/min limit) with exponential backoff on 429 responses.
- **Errors as text content** — MCP best practice: errors are returned in tool output so the LLM can see and respond to them.
- **Large document truncation** — Default 50k character limit with clear warning to prevent token overflow.

## License

MIT