Quip MCP Server

stdio と http の両方のトランスポートに対応した Quip MCP Server (TypeScript) リポジトリもご覧ください。

Quip MCP Server

Quip のスプレッドシートを操作するための Model Context Protocol（MCP）サーバーです。このサーバーは、Quip ドキュメントからスプレッドシートのデータを読み取り、CSV 形式で返すツールを提供します。

機能

• Quip ドキュメントからスプレッドシートの内容を取得します
• 名前を指定してシートを選択できます
• メタデータとともにデータを CSV 形式で返します
• Quip API トークンを使用した認証に対応しています
• スプレッドシートではないドキュメントに対して、適切なエラーメッセージを返します
• 必要に応じて内容を切り詰め、大きなスプレッドシートを自動的に処理します
• 効率的にアクセスできるよう、スプレッドシートの内容をローカルに保存します
• スプレッドシートの完全な内容にアクセスするためのリソース URI を提供します

インストール

uvx を使用する（推奨）

uv を使用する場合、特別なインストールは不要です。サーバーを直接実行するために uvx を使用します。

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Run the server directly with uvx
uvx quip-mcp-server

pip を使用する

または、pip でパッケージをインストールできます。

pip install quip-mcp-server

インストール後、スクリプトとして実行できます。

python -m src.server

環境変数を設定する

必要な環境変数を設定します。

export QUIP_TOKEN=your_quip_api_token
export QUIP_BASE_URL=https://platform.quip.com  # Optional, defaults to this value
export QUIP_STORAGE_PATH=/path/to/storage       # Optional, defaults to ~/.quip-mcp-server/storage

Alternatively, create a `.env` file in the root directory:

QUIP_TOKEN=your_quip_api_token QUIP_BASE_URL=https://platform.quip.com QUIP_STORAGE_PATH=/path/to/storage

## Usage

### Configure for Claude.app

Add to your Claude settings:

```json
"mcpServers": {
  "quip": {
    "command": "uvx",
    "args": ["quip-mcp-server", "--storage-path", "/path/to/storage"],
    "env": {
      "QUIP_TOKEN": "your_quip_api_token"
    }
  }
}

リソース URI にファイルプロトコルを使用する場合は、次のようにします。

"mcpServers": {
  "quip": {
    "command": "uvx",
    "args": ["quip-mcp-server", "--storage-path", "/path/to/storage", "--file-protocol"],
    "env": {
      "QUIP_TOKEN": "your_quip_api_token"
    }
  }
}

サーバーを手動で実行する

サーバーを直接実行します。

# Using uvx (recommended)
uvx quip-mcp-server --storage-path /path/to/storage

# Using python (if installed via pip)
python -m src.server --storage-path /path/to/storage

# With file protocol for resource URIs
uvx quip-mcp-server --storage-path /path/to/storage --file-protocol

# With debug logging enabled
uvx quip-mcp-server --storage-path /path/to/storage --debug

利用可能なツール

quip_read_spreadsheet

Quip のスプレッドシートの内容を CSV として取得します。

パラメーター：

• threadId（必須）：Quip ドキュメントのスレッド ID
• sheetName（任意）：抽出するシートの名前。指定しない場合は、最初のシートが使用されます。

例：

{
  "threadId": "AbCdEfGhIjKl",
  "sheetName": "Sheet1"
}

応答： このツールは、次の内容を含む JSON オブジェクトを返します。

• csv_content：CSV 形式のスプレッドシートの内容（大きすぎる場合は切り詰められます）
• metadata：スプレッドシートに関する追加情報：
  • total_rows：スプレッドシートの合計行数
  • total_size：CSV コンテンツの合計サイズ（バイト単位）
  • is_truncated：内容が切り詰められているかどうかを示すブール値
  • resource_uri：スプレッドシートの完全な内容にアクセスするための URI

応答の例（デフォルトのプロトコル）：

{
  "csv_content": "header1,header2\nvalue1,value2\n...",
  "metadata": {
    "total_rows": 1000,
    "total_size": 52840,
    "is_truncated": true,
    "resource_uri": "quip://AbCdEfGhIjKl?sheet=Sheet1"
  }
}

応答の例（--file-protocol を指定した場合）：

{
  "csv_content": "header1,header2\nvalue1,value2\n...",
  "metadata": {
    "total_rows": 1000,
    "total_size": 52840,
    "is_truncated": true,
    "resource_uri": "file:///path/to/storage/AbCdEfGhIjKl-Sheet1.csv"
  }
}

エラー処理：

• スレッドがスプレッドシートではない場合、エラーが返されます。
• 指定したシートが見つからない場合、エラーが返されます。

リソース URI

サーバーは、スプレッドシートの完全な内容にアクセスするためのリソース URI を提供します。これらの URI は、MCP のリソースアクセス機構で使用できます。

デフォルトでは、サーバーはリソース URI に quip:// プロトコルを使用します。ただし、--file-protocol オプションを使用すると、代わりに file:// プロトコルを使用できます。このプロトコルは、ローカルの CSV ファイルを直接指します。

デフォルトのプロトコル（quip://）

URI 形式：

quip://{threadId}?sheet={sheetName}

例：

quip://AbCdEfGhIjKl?sheet=Sheet1

ファイルプロトコル（--file-protocol オプションを指定）

URI 形式：

file://{storage_path}/{threadId}-{sheetName}.csv

例：

file:///home/user/.quip-mcp-server/storage/AbCdEfGhIjKl-Sheet1.csv

アクセスすると、サイズにかかわらず、リソースはスプレッドシートの完全な CSV コンテンツを返します。

仕組み

このサーバーは、スプレッドシートのデータを抽出するために、次の 2 つの方法を使用します。

1. 主な方法：Quip API を使用してスプレッドシートを XLSX 形式でエクスポートし、その後 CSV に変換します。
2. フォールバック方法：主な方法が失敗した場合、ドキュメントの HTML コンテンツを解析して表のデータを抽出します。

大きなスプレッドシートの場合、サーバーは次の処理を行います。

1. CSV コンテンツ全体をローカルストレージに保存します
2. メタデータとともに、切り詰めた内容（最大 10KB）を返します
3. 完全な内容にアクセスするためのリソース URI を提供します

コマンドライン引数

サーバーでは、次のコマンドライン引数を使用できます。

• --storage-path：CSV ファイルの保存先パス（デフォルトは、環境変数 QUIP_STORAGE_PATH の値、または ~/.quip-mcp-server/storage です）
• --file-protocol：リソース URI に file プロトコルを使用します（quip:// プロトコルの代わり）
• --debug：デバッグログを有効にします

例：

uvx quip-mcp-server --storage-path /path/to/storage

開発

プロジェクト構成

quip-mcp-server/
├── src/
│   ├── __init__.py
│   ├── server.py       # Main MCP server implementation
│   ├── quip_client.py  # Quip API client
│   ├── tools.py        # Tool definitions and handlers
│   └── storage.py      # Storage abstraction and implementations
├── tests/
│   ├── __init__.py
│   ├── test_server.py  # Unit tests for the server
│   ├── test_storage.py # Unit tests for the storage module
│   └── e2e/            # End-to-end tests
│       ├── __init__.py
│       ├── conftest.py # Test fixtures for e2e tests
│       └── test_quip_integration.py # Integration tests with Quip API
├── .uv/
│   └── config.toml     # uv configuration settings
├── pyproject.toml      # Project metadata and dependencies (includes pytest config)
├── uvproject.yaml      # uv-specific project configuration
├── uv.lock             # Locked dependencies
├── .python-version     # Python version specification
├── .env.example        # Example environment variables
├── LICENSE             # MIT License
└── README.md           # Documentation

uv を使った開発

このプロジェクトでは、依存関係の管理に uv を使用しています。uv は高速な Python パッケージインストーラー兼リゾルバーで、pip と virtualenv の代わりに使用できます。

設定ファイル

• pyproject.toml：標準的な Python パッケージ設定
• uvproject.yaml：uv 固有のプロジェクト設定
• .uv/config.toml：uv の設定
• .python-version：プロジェクトの Python バージョンとして Python 3.12 を指定します（pyenv などのバージョンマネージャーで使用されます）

開発環境のセットアップ

開発環境をセットアップするには、次の手順を実行します。

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create a virtual environment and install dependencies
uv venv
uv pip install -e .

# Install development dependencies
uv pip install pytest black isort mypy

または、uvproject.yaml ファイルを使用することもできます。

# Install dependencies from uvproject.yaml
uv pip sync

uv でサーバーを実行する

# Using uvx (recommended for development)
uvx quip-mcp-server

# Or, if you're using a virtual environment:
# Activate the virtual environment (if not auto-activated)
source .venv/bin/activate

# Run the server
python -m src.server

テストの実行

このプロジェクトでは、テストに pytest を使用しています。テストを実行するには、次のコマンドを実行します。

# Install development dependencies
uv pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=src

# Run only e2e tests
pytest tests/e2e

# Run a specific e2e test
pytest tests/e2e/test_quip_integration.py::test_connection

エンドツーエンド（e2e）テスト

このプロジェクトには、実際の Quip API との統合を検証するエンドツーエンドテストが含まれています。これらのテストを実行するには、次の手順を実行します。

1. プロジェクトのルートに、テスト設定を記述した .env.local ファイルを作成します。

   # Quip API token (required)
   QUIP_TOKEN=your_actual_quip_token_here
   
   # Test configuration
   TEST_THREAD_ID=your_test_spreadsheet_thread_id
   TEST_SHEET_NAME=Sheet1  # Optional: specific sheet name to test
   

2. e2e テストを実行します。

   # Run all e2e tests
   pytest tests/e2e
   
   # Run with verbose output
   pytest -v tests/e2e
   

注：.env.local がない場合、または必要な環境変数が設定されていない場合、e2e テストは自動的にスキップされます。

#### Debugging

You can use the MCP inspector to debug the server:

```bash
# For uvx installations
npx @modelcontextprotocol/inspector uvx quip-mcp-server

# Or if you're developing locally
cd /path/to/quip-mcp-server
npx @modelcontextprotocol/inspector uv run src.server

新しいツールの追加

新しいツールを追加するには、次の手順を実行します。

1. get_quip_tools() 関数に追加して、src/tools.py でツールを定義します。
2. ツールのハンドラー関数を実装します。
3. call_tool() 関数に追加して、src/server.py でハンドラーを登録します。

ライセンス

MIT ライセンス