Quip MCP 服务器

一个用于与 Quip 电子表格交互的模型上下文协议 (MCP) 服务器。此服务器提供从 Quip 文档读取电子表格数据并以 CSV 格式返回内容的工具。

功能

• 从 Quip 文档检索电子表格内容
• 支持按名称选择特定工作表
• 以 CSV 格式返回数据
• 通过 Quip API 令牌处理身份验证
• 为非电子表格文档提供适当的错误消息

安装

使用 uvx (推荐)

当使用 uv 时，无需进行特定安装。我们将使用 uvx 直接运行服务器：

# 如果您没有安装 uv，请安装它
curl -LsSf https://astral.sh/uv/install.sh | sh

# 使用 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  # 可选，默认为此值

或者，在根目录中创建一个 .env 文件：

QUIP_TOKEN=your_quip_api_token
QUIP_BASE_URL=https://platform.quip.com

用法

为 Claude.app 配置

添加到您的 Claude 设置：

"mcpServers": {
  "quip": {
    "command": "uvx",
    "args": ["quip-mcp-server"],
    "env": {
      "QUIP_TOKEN": "your_quip_api_token"
    }
  }
}

手动运行服务器

直接运行服务器：

# 使用 uvx (推荐)
uvx quip-mcp-server

# 使用 python (如果通过 pip 安装)
python -m src.server

可用工具

quip_read_spreadsheet

将 Quip 电子表格的内容检索为 CSV。

参数：

• threadId (必需): Quip 文档线程 ID
• sheetName (可选): 要提取的工作表的名称。如果未提供，将使用第一个工作表。

示例：

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

响应： 该工具以 CSV 格式返回电子表格内容。

错误处理：

• 如果线程不是电子表格，将返回错误。
• 如果找不到指定的工作表，将返回错误。

工作原理

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

1. 主要方法：使用 Quip API 将电子表格导出为 XLSX 格式，然后将其转换为 CSV。
2. 备用方法：如果主要方法失败，它会解析文档的 HTML 内容以提取表格数据。

开发

项目结构

quip-mcp-server/
├── src/
│   ├── __init__.py
│   ├── server.py       # 主要 MCP 服务器实现
│   ├── quip_client.py  # Quip API 客户端
│   └── tools.py        # 工具定义和处理程序
├── tests/
│   ├── __init__.py
│   ├── test_server.py  # 服务器的单元测试
│   └── e2e/            # 端到端测试
│       ├── __init__.py
│       ├── conftest.py # e2e 测试的测试 fixtures
│       └── test_quip_integration.py # 与 Quip API 的集成测试
├── .uv/
│   └── config.toml     # uv 配置设置
├── pyproject.toml      # 项目元数据和依赖项（包括 pytest 配置）
├── uvproject.yaml      # uv 特定的项目配置
├── uv.lock             # 锁定的依赖项
├── .python-version     # Python 版本规范
├── .env.example        # 示例环境变量
├── LICENSE             # MIT 许可证
└── README.md           # 文档

使用 uv 进行开发

本项目使用 uv 进行依赖管理。 uv 是一个快速的 Python 包安装程序和解析器，可以替代 pip 和 virtualenv。

配置文件

• pyproject.toml: 标准 Python 打包配置
• uvproject.yaml: uv 特定的项目配置
• .uv/config.toml: uv 配置设置
• .python-version: 指定 Python 3.12 作为项目的 Python 版本（由 pyenv 和其他版本管理器使用）

设置开发环境

要设置开发环境：

# 如果您没有安装 uv，请安装它
curl -LsSf https://astral.sh/uv/install.sh | sh

# 创建虚拟环境并安装依赖项
uv venv
uv pip install -e .

# 安装开发依赖项
uv pip install pytest black isort mypy

或者，您可以使用 uvproject.yaml 文件：

# 从 uvproject.yaml 安装依赖项
uv pip sync

使用 uv 运行服务器

# 使用 uvx (推荐用于开发)
uvx quip-mcp-server

# 或者，如果您正在使用虚拟环境：
# 激活虚拟环境（如果未自动激活）
source .venv/bin/activate

# 运行服务器
python -m src.server

运行测试

该项目使用 pytest 进行测试。 要运行测试：

# 安装开发依赖项
uv pip install -e ".[dev]"

# 运行测试
pytest

# 运行带有覆盖率的测试
pytest --cov=src

# 仅运行 e2e 测试
pytest tests/e2e

# 运行特定的 e2e 测试
pytest tests/e2e/test_quip_integration.py::test_connection

端到端 (e2e) 测试

该项目包括端到端测试，用于验证与实际 Quip API 的集成。 要运行这些测试：

1. 在项目根目录中创建一个 .env.local 文件，其中包含您的测试配置：

   # Quip API 令牌 (必需)
   QUIP_TOKEN=your_actual_quip_token_here
   
   # 测试配置
   TEST_THREAD_ID=your_test_spreadsheet_thread_id
   TEST_SHEET_NAME=Sheet1  # 可选：要测试的特定工作表名称
   

2. 运行 e2e 测试：

   # 运行所有 e2e 测试
   pytest tests/e2e
   
   # 运行带有详细输出的测试
   pytest -v tests/e2e
   

注意：如果缺少 .env.local 或未设置必需的环境变量，则会自动跳过 e2e 测试。

调试

您可以使用 MCP 检查器来调试服务器：

# 对于 uvx 安装
npx @modelcontextprotocol/inspector uvx quip-mcp-server

# 或者，如果您在本地开发
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 许可证