本项目是一个 Model Context Protocol (MCP) 服务器，专门设计用于与 Quip 电子表格进行交互。它允许通过标准化的 MCP 接口，让大型语言模型 (LLM) 客户端访问 Quip 电子表格数据，并提供读取电子表格内容的工具。

主要功能点

读取电子表格数据： 提供工具能够从指定的 Quip 文档（电子表格类型）中读取数据。
多种数据格式支持： 读取的电子表格内容主要以 CSV 格式返回。
灵活的存储选项： 支持将完整的电子表格数据存储到本地文件系统或 Amazon S3，方便后续通过资源 URI 访问。
资源 URI 提供： 对于大型电子表格，初始返回的 CSV 内容可能被截断，但会提供一个资源 URI，允许 LLM 客户端通过 MCP 的资源读取机制获取完整的原始数据。
会话管理与能力声明： 符合 MCP 标准，能向客户端声明自身提供的工具和资源能力。
多种传输协议： 支持 Stdio (用于客户端子进程启动) 和 HTTP (用于独立服务部署) 两种传输方式。
模拟模式： 提供无需真实 Quip API Token 的模拟模式，便于开发和测试。
错误处理： 实现了详细的错误类型和处理机制，向客户端返回清晰的错误信息。

安装步骤

要安装并运行 Quip MCP 服务器，您需要 Node.js 环境。

使用 npm 安装 (推荐): 您可以将服务器安装为全局工具或本地依赖。
- 全局安装：在终端运行 'npm install -g @zxkane/quip-mcp-server'
- 本地安装：在您的项目中运行 'npm install @zxkane/quip-mcp-server'
从源码安装: 如果您需要修改或贡献代码，可以从 GitHub 仓库克隆源码并构建。
- 克隆仓库：'git clone https://github.com/zxkane/quip-mcp-server-typescript.git'
- 进入目录：'cd quip-mcp-server-typescript'
- 安装依赖：'npm install'
- 构建项目：'npm run build'
配置环境变量: 服务器需要您的 Quip API Token 来访问 Quip 数据（除非在模拟模式下）。建议创建一个 '.env' 文件在项目根目录（或运行命令的目录下）来管理配置。
- 'QUIP_TOKEN': 您的 Quip API Token (必填，除非使用模拟模式)
- 'QUIP_BASE_URL': Quip API 基础 URL (可选，默认为 'https://platform.quip.com')
- 'STORAGE_TYPE': 数据存储类型 ('local' 或 's3'，可选，默认为 'local')
- 'QUIP_STORAGE_PATH': 本地存储路径 (仅当 'STORAGE_TYPE=local' 时相关，可选，默认为用户主目录下的特定路径)
- 'S3_BUCKET', 'S3_REGION', 'S3_PREFIX', 'S3_URL_EXPIRATION': S3 存储相关配置 (仅当 'STORAGE_TYPE=s3' 时相关)
- 'MCP_PORT': 服务器监听的 HTTP 端口 (仅当使用 HTTP 传输时相关，可选，默认为 3000)
- 'QUIP_MOCK': 设置为 'true' 启用模拟模式 (可选)

MCP 客户端配置

MCP 客户端（如支持 MCP 的 LLM 应用）需要知道如何启动并连接到此服务器。配置信息通常以 JSON 格式提供给客户端，包含服务器的启动命令和参数。以下是配置示例及其说明，请根据您的实际安装路径和需求进行调整：

"mcpServers": {
  "quip": {
    "command": "node",
    "args": [
      "/path/to/your/quip-mcp-server-typescript/dist/index.js", // 替换为服务器主程序的实际路径
      "--storage-path", "/path/to/your/preferred/storage", // 配置数据存储路径
      "--file-protocol" // 可选：如果希望资源URI使用 file:// 协议
      // 更多可选参数： --mock (启用模拟模式), --debug (启用调试日志), --json (日志输出为JSON)
    ],
    "env": {
      "QUIP_TOKEN": "your_quip_api_token" // 将您的 Quip API Token 放在这里
      // 可选的环境变量： "QUIP_BASE_URL": "..."
    }
  }
}

'command': 指定启动服务器的命令，通常是 'node'。
'args': 一个字符串数组，包含传递给 'command' 的参数。第一个参数是服务器的主程序文件路径（例如 '/path/to/your/quip-mcp-server-typescript/dist/index.js'），后续参数是配置服务器行为的命令行选项，例如 '--storage-path' 指定数据存储位置，'--file-protocol' 改变资源 URI 的格式。
'env': 一个键值对对象，用于设置服务器进程的环境变量，例如传递 'QUIP_TOKEN'。

如果您希望以 HTTP 模式运行服务器并让客户端连接，您需要在启动服务器时配置端口（通过环境变量 'PORT' 或命令行参数 '--port'），并在客户端配置中指定连接到该端口的 HTTP URL。

基本使用方法

一旦 MCP 服务器被客户端启动并连接成功，LLM 客户端就可以调用其提供的工具和访问资源。

列出可用工具： 客户端可以发送 'tools/list' 请求获取服务器提供的工具列表。本项目主要提供 'quip_read_spreadsheet' 工具。
调用 'quip_read_spreadsheet' 工具： 客户端发送 'tools/call' 请求来执行此工具，参数包括：
- 'name': '"quip_read_spreadsheet"'
- 'arguments': 一个包含工具所需参数的对象：
  - 'threadId' (必填): 要读取的 Quip 电子表格的线程 ID。
  - 'sheetName' (可选): 要读取的特定工作表名称。如果省略，默认为第一个工作表。
服务器会返回一个 JSON 结果，其中包含 'csv_content' (可能被截断的 CSV 数据预览) 和 'metadata' (包括总行数、总大小、是否截断以及 'resource_uri')。
访问完整资源： 如果 'quip_read_spreadsheet' 返回的 'metadata.is_truncated' 为 'true'，并且 'metadata.resource_uri' 提供了 URI，客户端可以发送 'resources/read' 请求并带上这个 URI 来获取完整的电子表格 CSV 数据。

例如，如果 'quip_read_spreadsheet' 返回的元数据中包含 'resource_uri: "quip://AbCdEfGhIjKl?sheet=Sheet1"'，客户端可以发送 'resources/read' 请求，参数为 '{ "uri": "quip://AbCdEfGhIjKl?sheet=Sheet1" }' 来获取完整的 CSV 内容。如果配置了文件协议或 S3 存储，URI 格式会有所不同。

关键词

主要功能点

安装步骤

MCP 客户端配置

基本使用方法

信息