Quip MCP Server

如需同时支持 stdio 和 http 传输，请查看 Quip MCP Server (TypeScript) 仓库。

Quip MCP 服务

用于与 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 使用 file 协议：

"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

以 CSV 格式获取 Quip 电子表格的内容。

参数：

• threadId（必填）：Quip 文档的 thread 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"
  }
}

错误处理：

• 如果该 thread 不是电子表格，则会返回错误。
• 如果找不到指定的工作表，则会返回错误。

资源 URI

该服务提供用于访问完整电子表格内容的资源 URI。这些 URI 可与 MCP 资源访问机制配合使用。

默认情况下，该服务使用 quip:// 协议作为资源 URI。不过，你可以使用 --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 内容。

工作原理

该服务使用两种方法提取电子表格数据：

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 使用文件协议（而不是 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 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. 在 src/tools.py 中将工具添加到 get_quip_tools() 函数。
2. 实现该工具的处理函数。
3. 在 src/server.py 中将处理函数添加到 call_tool() 函数，以完成注册。

许可证

MIT 许可证