Quip MCP Server (TypeScript)

Quip MCP サーバー（TypeScript）

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

🚀 AWS 従量課金制サーバーレスデプロイ

インフラストラクチャ管理なしで AWS にデプロイし、使用した分だけお支払いいただけます！

⚡ AWS Agent Core Runtime（推奨）

• 🔧 SSE サポート：リアルタイムストリーミング用の Server-Sent Events を内蔵
• ⏱️ 長時間実行：最大 8 時間の実行時間
• 📦 大容量ペイロード：100MB のペイロードをサポート
• 🔐 認証機能を内蔵：OAuth と ID 管理を統合
• 💰 使用量に応じた課金：実際の実行時間分のみお支払いいただけます

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 の設定
  • コマンドライン引数
  • Server-Sent Events（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）に対応した構造化ログ
• HTTP サーバーを保護するためのAPI キー認証
• 頻繁にアクセスされるリソースのパフォーマンスを向上させるキャッシュ機構
• サーバーの状態を監視するためのヘルスチェックエンドポイント

インストール

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

環境変数

ルートディレクトリに Quip API トークンを記載した .env ファイルを作成します。

# 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

サーバーは、次の 2 つのトランスポートプロトコルをサポートしています。

1. stdio トランスポート（デフォルト）：Claude.app などのツールのサブプロセスとして実行する場合に使用します。
2. HTTP トランスポート：サーバーを HTTP 経由で公開する場合に使用します。開発時や、スタンドアロンサービスとして実行する場合に便利です。

HTTP トランスポートを使用するには、PORT 環境変数を設定してください（必要に応じて HOST も設定します）。

トランスポートのオプション、設定、セキュリティ上の考慮事項、環境別の使用例について詳しくは、トランスポートのドキュメントを参照してください。

トランスポートのドキュメント

Quip MCP サーバーは、2 種類のトランスポートをサポートしています。

• 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 は、text/event-stream コンテンツタイプを使用して、1 つの HTTP 接続経由でサーバーからクライアントへデータをプッシュできるウェブ標準です。

SSE の使用場面：

• ストリーミングレスポンスが必要なリアルタイムアプリケーション
• 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

エラーレスポンスを含め、すべての MCP プロトコルメソッドが SSE 形式でサポートされています。基盤となる MCP の機能に変更はありません。

AWS Lambda + API Gateway へのデプロイ

Quip MCP サーバーは、AWS Lambda と API Gateway にデプロイすることで、サーバーレスでスケーラブルな HTTP エンドポイントを作成できます。この構成は本番環境に最適で、次のような利点があります。

• サーバーレス運用：サーバーを管理する必要はありません
• 自動スケーリング：負荷の変動に自動で対応します
• 高可用性：複数のアベイラビリティーゾーンに分散されます
• コスト効率：使用した分だけお支払いいただきます
• ストリーミング可能な HTTP インターフェース：HTTP MCP サーバーに対応したツールで利用できます

詳しいデプロイ手順については、クラウドへのデプロイ セクションをご覧ください。

利用可能なツール

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

レスポンス例（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=..."
  }
}

エラー処理：

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

リソース 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

これは 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 コンテンツがリソースから返されます。

動作の仕組み

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

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 ドキュメントにアクセスすることなく、さまざまなデータ形式に対するアプリケーションの処理をテストできます。実際の API 認証情報を使いたくない開発環境や CI/CD パイプラインで特に便利です。

構造化ログ

サーバーでは、ログレベルを分けた構造化ログを実装しています。

• DEBUG：詳細なデバッグ情報
• INFO：サーバーの動作に関する一般情報
• WARN：警告メッセージ
• ERROR：エラーメッセージ

ログはプレーンテキスト形式または JSON 形式で出力できます。JSON ログを有効にするには、コマンドライン引数 --json を使用するか、環境変数 JSON_LOGS を true に設定します。

構造化ログシステムでは、ログの書式が統一され、各ログエントリーにコンテキスト情報が含まれるため、ログのフィルタリングや分析が容易になります。JSON ログを有効にすると、ログ管理システムで簡単に解析でき、高度な監視やアラートに活用できます。

認証

サーバーは、HTTP サーバーを保護するための API キー認証に対応しています。有効にすると、クライアントはリクエストヘッダーに API キーを含める必要があります。

認証を有効にするには、コマンドライン引数 --auth を使用するか、環境変数 MCP_AUTH_ENABLED を true に設定します。API キーは、引数 --api-key または環境変数 MCP_API_KEY で指定できます。指定されていない場合は、ランダムな API キーが生成され、ログに表示されます。

API キーのヘッダー名は、引数 --api-key-header または環境変数 MCP_API_KEY_HEADER でカスタマイズできます。デフォルトのヘッダー名は X-API-Key です。

認証は HTTP トランスポートモードにのみ適用されます。通常、より管理された環境で使用される stdio トランスポートには影響しません。

キャッシュ

サーバーでは、頻繁にアクセスされるリソース向けのキャッシュ機構を実装しています。ディスクの読み取りや API 呼び出しの回数を減らし、パフォーマンスを向上させます。

次の 2 種類のキャッシュを使用します。

• csvCache：CSV コンテンツのキャッシュ（TTL は 10 分）
• metadataCache：メタデータのキャッシュ（TTL は 30 分）

キャッシュシステムは、TTL（有効期限）に基づくキャッシュの無効化を自動的に処理します。また、多数のリソースを扱う際のメモリの問題を防ぐため、シンプルな LRU（最も長く使われていないものを優先して削除）方式を実装しています。これにより、メモリ使用量を適切に保ちながら、最適なパフォーマンスを実現します。

ストレージのオプション

サーバーは、次の 2 つのストレージオプションに対応しています。

ローカルストレージ

デフォルトでは、サーバーは 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 ストレージを使用できます。これにより、S3 バケットに CSV ファイルを保存できます。

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：S3 リソースに直接アクセスするための署名付き HTTPS URL を生成するには、"true" に設定します

署名付き S3 URL： USE_PRESIGNED_URLS を "true" に設定すると、サーバーはリソース URI として s3:// URI の代わりに署名付き HTTPS URL を生成します。これにより、AWS 認証情報や専用の S3 クライアントライブラリがなくても、リソースに直接アクセスできます。署名付き URL は一時的なもので、S3_URL_EXPIRATION で指定した時間（デフォルト：3600 秒）が経過すると有効期限が切れます。

AWS 認証： S3 ストレージの実装では AWS 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 デプロイガイドを参照してください。

デプロイ後、デプロイした MCP サーバーに Claude.app を接続するには、以下を 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 サーバーは、AI エージェントおよび MCP サーバー向けの高度な機能を提供する AWS Agent Core Runtime にデプロイすることもできます。

主なメリット：

• 実行時間の延長：最大 8 時間（Lambda の 15 分制限に対し）
• 大きなペイロードに対応：100 MB のペイロード（Lambda の 6 MB 制限に対し）
• セッションの分離：ユーザーセッションごとに専用のマイクロ VM を割り当て
• 組み込みの認証：OAuth と ID 管理を統合
• 強化された可観測性：エージェントの操作に特化したトレース
• 使用量に応じた料金体系：実際のランタイム使用量に対してのみ課金

このプロジェクトには、Agent Core Runtime のデプロイに必要な CDK インフラストラクチャのセットアップが一式含まれています。

• Docker buildx を使用した ARM64 コンテナのデプロイ
• イメージの自動ビルドに対応した ECR リポジトリ
• Agent Core Runtime 向けの AWS ドキュメント記載の権限を備えた IAM ロール
• Agent Core Runtime API 呼び出し用の AwsCustomResource
• データストレージ用の S3 統合
• 認証情報用の Secrets Manager 統合

IAM 権限一式： デプロイ時に、AWS のドキュメントに従って必要な権限をすべて備えた実行ロールが自動的に作成されます。

• ECR イメージへのアクセスと認証
• ランタイムのログ記録用の CloudWatch Logs
• X-Ray 分散トレース
• CloudWatch メトリクスの発行
• Agent Core Runtime のワークロード ID
• 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 インスペクターを使用してサーバーをデバッグできます。

# 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. リポジトリをフォークします
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 ライセンス