Quip MCP Server (TypeScript)

Quip MCP 服务（TypeScript）

一个用于与 Quip 电子表格交互的模型上下文协议（MCP）服务，使用 TypeScript 实现。此服务提供工具，用于读取 Quip 文档中的电子表格数据，并以 CSV 格式返回内容。

🚀 AWS 按需付费的无服务器部署

部署到 AWS，无需管理基础设施，只需为实际用量付费！

⚡ AWS Agent Core Runtime（推荐）

• 🔧 SSE 支持：内置服务器发送事件，实现实时流式传输
• ⏱️ 延长运行时间：最长可运行 8 小时
• 📦 大型负载：支持 100MB 负载
• 🔐 内置身份验证：集成 OAuth 和身份管理
• 💰 按用量计费：仅为实际运行用量付费

cd infrastructure/agent-core
./deploy.sh --agent-name my-quip-mcp --secret-arn arn:aws:secretsmanager:...

🌐 AWS Lambda + API Gateway

• 📈 自动扩展：自动处理不同的负载
• 🌍 全球部署：分布于多个可用区
• 💸 经济实惠：按请求付费，并提供丰厚的免费额度
• 🔌 HTTP 接口：适用于任何 HTTP MCP 客户端

cd infrastructure/api-gateway-lambda
./deploy.sh --secret-arn arn:aws:secretsmanager:...

这两种方案都提供企业级无服务器基础设施，无需管理服务器！

目录

• 功能
• 安装
  • 使用 npm
  • 从源代码构建
  • 环境变量
• 用法
  • 运行服务
  • 传输文档
  • 为 Claude.app 配置
  • 命令行参数
  • 服务器发送事件（SSE）支持
  • 部署到 AWS Lambda + API Gateway
• 可用工具
  • quip_read_spreadsheet
• 资源 URI
• 工作原理
  • 错误处理
  • 模拟模式
  • 结构化日志
  • 身份验证
  • 缓存
  • 存储选项
    • 本地存储
    • S3 存储
• 健康检查端点
• 云部署
  • AWS Lambda + API Gateway
  • AWS Agent Core Runtime
• 开发
  • 项目结构
  • 设置开发环境
  • 脚本
  • 运行测试
  • 调试
  • 添加新工具
• 贡献
• 许可证

功能

• 从 Quip 文档中检索电子表格内容
• 支持按名称选择特定工作表
• 以 CSV 格式返回数据及元数据
• 通过 Quip API 令牌进行身份验证
• 为非电子表格文档提供恰当的错误消息
• 必要时自动截断内容，以处理大型电子表格
• 在本地存储电子表格内容，以便高效访问
• 支持多种存储选项，包括本地文件系统和 Amazon S3
• 提供资源 URI，用于访问完整的电子表格内容
• 增强的错误处理，提供详细的错误消息和恰当的错误类型
• 模拟模式，无需真实的 Quip API 令牌即可进行测试
• 结构化日志，支持不同的日志级别（debug、info、warn、error）
• API 密钥身份验证，用于保护 HTTP 服务
• 缓存机制，提升频繁访问资源时的性能
• 健康检查端点，用于监控服务状态

安装

使用 npm

# Install globally
npm install -g @zxkane/quip-mcp-server

# Or install locally in your project
npm install @zxkane/quip-mcp-server

从源代码构建

# Clone the repository
git clone https://github.com/zxkane/quip-mcp-server-typescript.git
cd quip-mcp-server-typescript

# Install dependencies
npm install

# Build the project
npm run build

环境变量

在根目录中创建 .env 文件，并填入 Quip API 令牌：

# Quip API token (required unless in mock mode)
QUIP_TOKEN=your_quip_api_token_here

# Quip API base URL (optional, defaults to https://platform.quip.com)
QUIP_BASE_URL=https://platform.quip.com

# Storage type (optional, defaults to 'local', can be 'local' or 's3')
# STORAGE_TYPE=local

# Storage path for CSV files (optional, defaults to ~/.quip-mcp-server/storage)
QUIP_STORAGE_PATH=/path/to/storage

# S3 storage configuration (required when STORAGE_TYPE=s3)
# S3_BUCKET=your-bucket-name
# S3_REGION=us-east-1
# S3_PREFIX=quip-data/
# S3_URL_EXPIRATION=3600

# MCP server port (optional, defaults to 3000)
MCP_PORT=3000

# Debug mode (optional, set to true to enable debug logging)
# QUIP_DEBUG=true

# Mock mode (optional, set to true to use mock data without a real Quip token)
# QUIP_MOCK=true

# JSON logging (optional, set to true to output logs as JSON)
# JSON_LOGS=true

# Authentication (optional, set to true to enable API key authentication)
# MCP_AUTH_ENABLED=true

# API key for authentication (optional, auto-generated if not provided)
# MCP_API_KEY=your_api_key_here

# API key header name (optional, defaults to X-API-Key)
# MCP_API_KEY_HEADER=X-API-Key

用法

运行服务

# Using npm with stdio transport (default)
npm start

# With command-line arguments
npm start -- --storage-path /path/to/storage --file-protocol --debug

# Using HTTP transport (set PORT and HOST environment variables)
PORT=3000 HOST=localhost npm start

# Using node directly
node dist/index.js --storage-path /path/to/storage

服务支持两种传输协议：

1. stdio 传输（默认）：作为子进程运行时使用，适用于 Claude.app 等工具
2. HTTP 传输：需要通过 HTTP 暴露服务时使用，适用于开发或将服务作为独立服务运行的场景

要使用 HTTP 传输，请设置 PORT 环境变量（也可选择设置 HOST）。

有关传输选项、配置、安全注意事项和特定环境示例的详细信息，请参阅传输文档。

传输文档

Quip MCP 服务支持两种传输类型：

• Stdio 传输：默认传输方式，在服务作为其他应用程序（例如 Claude.app）的子进程运行时使用。
• HTTP 传输：通过 HTTP 暴露服务时使用，允许客户端通过网络连接。

详细传输文档涵盖：

• 传输配置选项
• 各种传输类型的安全注意事项
• 特定环境示例（本地开发、Claude.app 集成、生产部署、Docker/容器使用、CI/CD 集成）
• 常见问题排查
• 传输改进的未来考量

为 Claude.app 配置

将以下内容添加到 Claude 设置中：

"mcpServers": {
  "quip": {
    "command": "node",
    "args": ["dist/index.js", "--storage-path", "/path/to/storage"],
    "env": {
      "QUIP_TOKEN": "your_quip_api_token"
    }
  }
}

如果要对资源 URI 使用 file 协议：

"mcpServers": {
  "quip": {
    "command": "node",
    "args": ["dist/index.js", "--storage-path", "/path/to/storage", "--file-protocol"],
    "env": {
      "QUIP_TOKEN": "your_quip_api_token"
    }
  }
}

命令行参数

服务支持以下命令行参数：

• --storage-type <type>：存储类型（local 或 s3，默认为 'local'）
• --storage-path <path>：存储 CSV 文件的路径（默认为 QUIP_STORAGE_PATH 环境变量的值，或 ~/.quip-mcp-server/storage）
• --file-protocol：对资源 URI 使用 file 协议（而不是 quip:// 协议）
• --s3-bucket <name>：S3 存储桶名称（S3 存储必需）
• --s3-region <region>：S3 区域（S3 存储必需）
• --s3-prefix <prefix>：S3 前缀（S3 存储可选）
• --s3-url-expiration <seconds>：S3 URL 过期时间（秒）（默认值：3600）
• --use-presigned-urls：为 S3 资源生成预签名 HTTPS URL（而不是 s3:// URI）
• --debug：启用调试日志
• --mock：使用模拟模式（无需真实 Quip 令牌）
• --json：以 JSON 格式输出日志
• --auth：启用身份验证
• --api-key <key>：用于身份验证的 API 密钥（若未提供则自动生成）
• --api-key-header <header>：API 密钥标头名称（默认为 X-API-Key）
• --port <port>：监听的 HTTP 端口（默认为 MCP_PORT 环境变量的值，或 3000）
• --sse：启用响应的 SSE（Server-Sent Events）格式（默认为 false）

示例：

node dist/index.js --storage-path /path/to/storage --file-protocol --debug

模拟模式示例：

node dist/index.js --mock --storage-path /path/to/storage

启用身份验证的示例：

node dist/index.js --auth --api-key your_api_key_here

SSE 格式示例：

node dist/index.js --port 3000 --sse --mock

Server-Sent Events（SSE）支持

服务通过 --sse 标志支持 HTTP 响应的 Server-Sent Events（SSE）格式。SSE 是一种 Web 标准，允许服务使用 text/event-stream 内容类型，通过单个 HTTP 连接向客户端推送数据。

适用场景：

• 需要流式响应的实时应用
• 与需要 event-stream 格式的系统集成
• 用于服务端到客户端通信的 WebSocket 替代方案
• 渐进式响应流传输

响应格式差异：

使用 --sse 标志时：

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

data: {"jsonrpc":"2.0","result":{"tools":[...]},"id":1}

不使用 --sse 标志时（默认）：

Content-Type: application/json

{"jsonrpc":"2.0","result":{"tools":[...]},"id":1}

测试 SSE 功能：

# Start SSE server
node dist/index.js --port 3000 --sse --mock &

# Test with curl
curl -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","method":"tools/list","id":1}' \
     http://localhost:3000/mcp

SSE 格式支持所有 MCP 协议方法，包括错误响应。底层 MCP 功能保持不变。

部署到 AWS Lambda + API Gateway

Quip MCP 服务可部署到 AWS Lambda 并搭配 API Gateway，创建无服务器、可扩展的 HTTP 端点。此配置非常适合生产环境，并具有以下优势：

• 无服务器运行：无需管理服务器
• 自动扩缩容：自动应对不同的负载
• 高可用性：分布在多个可用区
• 经济高效：只需为实际使用量付费
• 可流式传输的 HTTP 接口：适用于支持 HTTP MCP 服务的工具

详细的部署说明，请参阅云部署部分。

可用工具

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"
  }
}

响应示例（使用 S3 存储）：

{
  "csv_content": "header1,header2\nvalue1,value2\n...",
  "metadata": {
    "total_rows": 1000,
    "total_size": 52840,
    "is_truncated": true,
    "resource_uri": "s3://my-bucket/quip-data/AbCdEfGhIjKl-Sheet1.csv"
  }
}

响应示例（使用 S3 存储和 --use-presigned-urls）：

{
  "csv_content": "header1,header2\nvalue1,value2\n...",
  "metadata": {
    "total_rows": 1000,
    "total_size": 52840,
    "is_truncated": true,
    "resource_uri": "https://my-bucket.s3.us-east-1.amazonaws.com/quip-data/AbCdEfGhIjKl-Sheet1.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=..."
  }
}

错误处理：

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

资源 URI

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

该服务根据配置支持多种 URI 格式：

默认协议（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

S3 协议（使用 S3 存储时）

URI 格式：

s3://{bucket}/{prefix}/{threadId}-{sheetName}.csv

示例：

s3://my-bucket/quip-data/AbCdEfGhIjKl-Sheet1.csv

预签名 S3 URL（使用 S3 存储且 USE_PRESIGNED_URLS=true 时）

URI 格式：

s3+https://{bucket}/{prefix}/{threadId}-{sheetName}.csv

该 URI 会解析为 HTTPS URL：

https://{bucket}.s3.{region}.amazonaws.com/{prefix}/{threadId}-{sheetName}.csv?{authentication_params}

示例：

https://my-bucket.s3.us-east-1.amazonaws.com/quip-data/AbCdEfGhIjKl-Sheet1.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...

访问该资源时，无论电子表格的大小如何，都会返回完整的 CSV 内容。

工作原理

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

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

对于大型电子表格，该服务会：

1. 将完整的 CSV 内容保存到本地存储
2. 返回截断版本（最多 10KB）以及元数据
3. 提供用于访问完整内容的资源 URI

错误处理

该服务实现了完善的错误处理系统，并定义了以下特定错误类型：

• QuipMCPError：所有服务错误的基础错误类
• InvalidParamsError：请求参数无效时使用
• MethodNotFoundError：方法或工具未知时使用
• ParseError：JSON 解析出错时使用
• AuthenticationError：身份验证失败时使用
• ResourceNotFoundError：找不到资源时使用
• QuipApiError：Quip API 出错时使用
• StorageError：存储相关错误时使用
• TimeoutError：请求超时时使用

每种错误类型都有特定的错误代码，也可包含用于调试的其他数据。这种一致的错误处理方式可确保客户端收到清晰且可操作的错误消息，从而更轻松地诊断和修复问题。

模拟模式

服务器包含一种模拟模式，无需真实的 Quip API 令牌。该模式适用于测试和开发。在模拟模式下，服务器使用预定义的示例数据，而不会实际调用 Quip API。

要启用模拟模式，请使用命令行参数 --mock，或将环境变量 QUIP_MOCK 设为 true。

模拟模式提供了多种具有不同结构和大小的示例电子表格，让你无需访问真实的 Quip 文档，即可测试应用处理各种数据格式的能力。这对于开发环境或 CI/CD 流水线尤其有用，因为在这些场景下，你可能不希望使用真实的 API 凭据。

结构化日志

服务器实现了结构化日志记录，并支持不同的日志级别：

• DEBUG：详细的调试信息
• INFO：服务器运行的一般信息
• WARN：警告消息
• ERROR：错误消息

日志可以纯文本或 JSON 格式输出。要启用 JSON 日志记录，请使用命令行参数 --json，或将环境变量 JSON_LOGS 设为 true。

结构化日志系统采用一致的日志格式，并在每条日志中包含上下文信息，便于筛选和分析日志。启用 JSON 日志记录后，日志可以轻松地由日志管理系统解析，以实现高级监控和告警。

身份验证

服务器支持使用 API 密钥进行身份验证，以保护 HTTP 服务器。启用后，客户端必须在请求头中包含 API 密钥。

要启用身份验证，请使用命令行参数 --auth，或将环境变量 MCP_AUTH_ENABLED 设为 true。你可以使用参数 --api-key 或环境变量 MCP_API_KEY 指定 API 密钥。如果未提供，系统将生成一个随机 API 密钥并显示在日志中。

可以使用参数 --api-key-header 或环境变量 MCP_API_KEY_HEADER 自定义 API 密钥请求头的名称。默认名称为 X-API-Key。

身份验证仅应用于 HTTP 传输模式，不影响通常用于管控更严格环境的 stdio 传输。

缓存

服务器为频繁访问的资源实现了缓存机制。通过减少磁盘读取和 API 调用次数，该机制可以提升性能。

系统使用两种缓存：

• csvCache：用于缓存 CSV 内容（TTL 为 10 分钟）
• metadataCache：用于缓存元数据（TTL 为 30 分钟）

缓存系统会根据 TTL（生存时间）值自动处理缓存失效，并实现简单的 LRU（最近最少使用）策略，以避免处理大量资源时出现内存问题。这既能确保最佳性能，也能维持合理的内存使用量。

存储选项

服务器支持两种存储选项：

本地存储

默认情况下，服务器使用本地文件系统存储 CSV 文件。这适用于大多数用例，并能提供良好的性能。

配置本地存储：

# Using environment variables
STORAGE_TYPE=local QUIP_STORAGE_PATH=/path/to/storage npm start

# Using command line arguments
npm start -- --storage-type local --storage-path /path/to/storage

S3 存储

对于生产部署，或需要在多个实例间共享数据的情况，可以使用 Amazon S3 存储。这样可以将 CSV 文件存储在 S3 存储桶中。

配置 S3 存储：

# Using environment variables
STORAGE_TYPE=s3 S3_BUCKET=your-bucket-name S3_REGION=us-east-1 npm start

# Using command line arguments
npm start -- --storage-type s3 --s3-bucket your-bucket-name --s3-region us-east-1

其他 S3 配置选项：

• S3_PREFIX / --s3-prefix：S3 对象键的前缀（例如 "quip-data/"）
• S3_URL_EXPIRATION / --s3-url-expiration：URL 过期时间，单位为秒（默认值：3600）
• USE_PRESIGNED_URLS：设置为 "true" 可生成预签名 HTTPS URL，以便直接访问 S3 资源

S3 预签名 URL： 当 USE_PRESIGNED_URLS 设置为 "true" 时，服务会为资源 URI 生成预签名 HTTPS URL，而不是 s3:// URI。这样无需 AWS 凭证或专用 S3 客户端库即可直接访问资源。预签名 URL 为临时 URL，会在 S3_URL_EXPIRATION 指定的时间后过期（默认值：3600 秒）。

AWS 身份验证： S3 存储实现使用 AWS SDK，该 SDK 会自动从环境中加载凭证。你可以通过任何标准方式提供 AWS 凭证：

• 环境变量（AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY）
• 共享凭证文件（~/.aws/credentials）
• Amazon EC2 或 ECS 任务的 IAM 角色

有关 AWS 身份验证的更多信息，请参阅 AWS SDK 文档。

健康检查端点

服务在 /health 提供健康检查端点，可用于监控服务状态。使用 HTTP 传输模式运行时，此端点可用。

要访问健康检查端点，请向 /health 发送 GET 请求：

curl http://localhost:3000/health

服务正常运行时，端点会返回一个状态为 "ok" 的简单 JSON 响应：

{
  "status": "ok"
}

监控工具或容器编排系统可以使用此端点检查服务是否健康并已准备好处理请求。

云部署

AWS Lambda + API Gateway

Quip MCP 服务可通过 AWS Lambda 与 API Gateway 部署为无服务器应用。此方案提供可扩展、低维护的部署选项，并支持流式 HTTP 接口。

项目包含一套 AWS CDK 基础设施配置，可自动部署以下内容：

• 使用 Quip MCP 服务的 Lambda 函数
• API Gateway 端点
• 用于存储 CSV 文件的 S3 存储桶
• 用于存储敏感信息的 Secrets Manager

有关详细部署说明、架构概览和使用信息，请参阅基础设施目录中的 AWS Lambda 部署指南。

部署完成后，要将 Claude.app 连接到已部署的 MCP 服务，请在 Claude 设置中添加以下内容：

"mcpServers": {
  "quip-remote": {
    "endpointUrl": "https://your-api-gateway-url/mcp",
    "headers": {
      "X-API-Key": "YOUR_API_KEY_VALUE"
    }
  }
}

AWS Agent Core Runtime

Quip MCP 服务也可以部署到 AWS Agent Core Runtime，该运行时为 AI Agent 和 MCP 服务提供增强功能：

主要优势：

• 更长的执行时间：最长可达 8 小时（而 Lambda 限制为 15 分钟）
• 支持更大的负载：支持 100MB 负载（而 Lambda 限制为 6MB）
• 会话隔离：为每个用户会话提供专用微型虚拟机
• 内置身份验证：集成 OAuth 和身份管理
• 增强的可观测性：为 Agent 操作提供专用追踪
• 按使用量计费：仅为实际运行时用量付费

项目包含完整的 CDK 基础设施配置，可用于部署到 Agent Core Runtime：

• 使用 Docker buildx 部署 ARM64 容器
• 配置 ECR 存储库并自动构建镜像
• 配置具有 AWS 文档所述 Agent Core Runtime 权限的 IAM 角色
• 使用 AwsCustomResource 调用 Agent Core Runtime API
• 集成 S3 以存储数据
• 集成 Secrets Manager 以存储凭据

完整 IAM 权限集： 部署会根据 AWS 文档自动创建具有所有必需权限的执行角色：

• ECR 镜像访问和身份验证
• 用于运行时日志记录的 CloudWatch Logs
• X-Ray 分布式追踪
• CloudWatch 指标发布
• Agent Core Runtime 工作负载身份
• Bedrock 模型调用能力

详细的部署说明，请参阅 Agent Core Runtime 部署指南。

快速部署：

cd infrastructure/agent-core
./deploy.sh --agent-name my-quip-mcp --region us-west-2

如需完整了解如何测试 AgentCore 部署，请参阅 在 AWS AgentCore 上调用托管的 MCP。

开发

项目结构

quip-mcp-server-typescript/
├── src/
│   ├── index.ts                 # Main entry point
│   ├── server.ts                # MCP server implementation
│   ├── cli.ts                   # Command-line argument handling
│   ├── quipClient.ts            # Quip API client
│   ├── mockClient.ts            # Mock Quip client for testing
│   ├── tools.ts                 # Tool definitions and handlers
│   ├── storage.ts               # Storage abstraction and implementations
│   ├── types.ts                 # TypeScript type definitions
│   ├── version.ts               # Version information
│   ├── errors.ts                # Error handling
│   ├── logger.ts                # Structured logging
│   ├── auth.ts                  # Authentication
│   └── cache.ts                 # Caching mechanism
├── tests/
│   ├── unit/                    # Unit tests
│   │   ├── server.test.ts
│   │   ├── quipClient.test.ts
│   │   ├── tools.test.ts
│   │   ├── storage.test.ts
│   │   └── ...
│   └── e2e/                     # End-to-end tests
├── infrastructure/              # AWS deployment resources
│   ├── api-gateway-lambda/      # CDK project for Lambda + API Gateway deployment
│   │   ├── bin/
│   │   │   └── app.ts           # CDK app entry point
│   │   ├── lib/
│   │   │   └── quip-mcp-server-stack.ts  # Main CDK stack
│   │   ├── lambda/              # Lambda function code
│   │   │   ├── run.js           # Lambda handler
│   │   │   └── package.json
│   │   ├── package.json
│   │   ├── tsconfig.json
│   │   └── README.md            # Lambda + API Gateway deployment guide
│   └── README.md                # Overview of deployment options
├── example-client/              # Example MCP client implementation
│   ├── src/
│   │   ├── client-common.ts
│   │   ├── http-client.ts
│   │   ├── stdio-client.ts
│   │   └── index.ts
│   ├── package.json
│   └── README.md
├── dist/                        # Compiled JavaScript output
├── .env.example                 # Example environment variables
├── .gitignore                   # Git ignore file
├── jest.config.js               # Jest configuration
├── tsconfig.json                # TypeScript configuration
├── package.json                 # npm package configuration
└── LICENSE                      # License file

设置开发环境

# Clone the repository
git clone https://github.com/zxkane/quip-mcp-server-typescript.git
cd quip-mcp-server-typescript

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

脚本

• npm run build：构建项目
• npm start：运行服务
• npm run dev：以开发模式运行服务
• npm test：运行测试
• npm run test:watch：以监听模式运行测试
• npm run test:coverage：运行测试并生成覆盖率报告
• npm run test:e2e：运行端到端测试
• npm run lint：检查代码
• npm run format：格式化代码

运行测试

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

# Run end-to-end tests
npm run test:e2e

调试

你可以使用 MCP inspector 调试服务：

# Install the MCP inspector
npm install -g @modelcontextprotocol/inspector

# Debug the server
mcp-inspector node dist/index.js

添加新工具

添加新工具的步骤：

1. 在 src/tools.ts 中将工具添加到 getQuipTools() 函数：

export function getQuipTools(): Tool[] {
  return [
    {
      name: "quip_read_spreadsheet",
      description: "Read the content of a Quip spreadsheet...",
      inputSchema: {
        // Schema definition
      }
    },
    {
      name: "your_new_tool",
      description: "Description of your new tool",
      inputSchema: {
        // Schema definition for your tool
      }
    }
  ];
}

2. 实现该工具的处理函数：

export async function handleYourNewTool(
  args: Record<string, any>,
  storage: StorageInterface
): Promise<(TextContent | ImageContent | EmbeddedResource)[]> {
  // Implement your tool logic here
  return [{ type: "text", text: "Your tool response" }];
}

3. 在 src/server.ts 的 call_tool 处理程序中注册处理函数：

server.call_tool(async (name: string, arguments_: any) => {
  logger.info(`Handling tool call: ${name}`);
  logger.debug(`Tool arguments: ${JSON.stringify(arguments_)}`);
  
  if (!arguments_ || typeof arguments_ !== 'object') {
    logger.error("Invalid arguments: not an object");
    throw new InvalidParamsError("Invalid arguments");
  }
  
  try {
    if (name === "quip_read_spreadsheet") {
      if (!storageInstance) {
        throw new StorageError("Storage not initialized");
      }
      return await handleQuipReadSpreadsheet(arguments_, storageInstance, options.mock);
    } else if (name === "your_new_tool") {
      return await handleYourNewTool(arguments_, storageInstance);
    } else {
      logger.error(`Unknown tool: ${name}`);
      throw new MethodNotFoundError(`Unknown tool: ${name}`);
    }
  } catch (error) {
    if (error instanceof QuipMCPError) {
      throw error;
    }
    const errorMessage = error instanceof Error ? error.message : String(error);
    logger.error(`Tool call failed: ${errorMessage}`);
    throw new QuipApiError(`Tool call failed: ${errorMessage}`);
  }
});

贡献

欢迎贡献！你可以通过以下方式为项目作出贡献：

1. Fork 此存储库
2. 创建新分支（git checkout -b feature/your-feature-name）
3. 进行更改
4. 运行测试，确保一切正常（npm test）
5. 提交更改（git commit -m 'Add some feature'）
6. 将更改推送到分支（git push origin feature/your-feature-name）
7. 发起 Pull Request

请确保代码遵循项目的编码规范，并包含适当的测试。

许可证

MIT 许可证