# 技術仕様書 (Architecture Design Document)
## テクノロジースタック
### 言語・ランタイム
| 技術 | バージョン | 選定理由 |
|------|-----------|----------|
| Node.js | v24.11.0 | TypeScriptのトランスパイルとWranglerの実行環境として使用。devcontainerで固定 |
| TypeScript | 5.x | 型安全性により実装ミスを防止。MCPライブラリの型定義を活用 |
| npm | 11.x | Node.js v24.11.0に標準搭載。npxでWranglerを簡単に実行可能 |
### フレームワーク・ライブラリ
| 技術 | バージョン | 用途 | 選定理由 |
|------|-----------|------|----------|
| Hono | 最新 | Webフレームワーク | Cloudflare Workers向けに最適化。軽量で高速。MCPサポート |
| @hono/mcp | 最新 | MCPプロトコル実装 | HonoとMCPの統合を簡単に実現 |
| @modelcontextprotocol/sdk | 最新 | MCP SDK | MCPツールの定義に使用 |
### 開発ツール
| 技術 | バージョン | 用途 | 選定理由 |
|------|-----------|------|----------|
| Wrangler | 最新 | Cloudflare CLI | ローカル開発とデプロイを統一管理。ホットリロード対応 |
| @cloudflare/workers-types | 最新 | 型定義 | Cloudflare Workers APIの型サポート |
## アーキテクチャパターン
### シングルレイヤーアーキテクチャ
本プロジェクトは**最小限のサンプルアプリケーション**であるため、
複雑なレイヤー分離は行わず、シンプルな構造を採用します。
```
┌─────────────────────────────────────┐
│ Cloudflare Workers │
│ ┌─────────────────────────────┐ │
│ │ Hono + MCP Server │ │
│ │ ┌───────────────────────┐ │ │
│ │ │ factorize ツール │ │ │
│ │ └───────────────────────┘ │ │
│ └─────────────────────────────┘ │
└─────────────────────────────────────┘
```
### 設計判断の理由
- **単一ファイル構成**: 学習用サンプルとして、すべてのコードを1ファイルで完結
- **レイヤー分離なし**: 機能が単純（素因数分解のみ）のため、抽象化は不要
- **ステートレス**: データ永続化なし、リクエスト単位で完結
## データ永続化戦略
### ストレージ方式
**該当なし** - 本アプリケーションはステートレスです。
| データ種別 | ストレージ | 理由 |
|-----------|----------|------|
| 入力値 | なし（メモリ内処理） | リクエストごとに計算、保存不要 |
| 計算結果 | なし（レスポンスで返却） | 永続化の必要なし |
### バックアップ戦略
**該当なし** - 永続化データがないため、バックアップ不要。
## パフォーマンス要件
### レスポンスタイム
| 操作 | 目標時間 | 測定環境 |
|------|---------|---------|
| 素因数分解（6桁以下） | < 10ms | Cloudflare Workers |
| 素因数分解（7-8桁） | < 50ms | Cloudflare Workers |
| 素因数分解（9-10桁） | < 100ms | Cloudflare Workers |
| 素因数分解（11-15桁） | < 1s | Cloudflare Workers |
| tools/list | < 10ms | Cloudflare Workers |
### リソース使用量
| リソース | 上限 | 理由 |
|---------|------|------|
| メモリ | 128MB | Cloudflare Workers Free planの制限 |
| CPU時間 | 10ms | Cloudflare Workers Free planの制限（リクエストあたり） |
| スクリプトサイズ | 1MB | Cloudflare Workers Free planの制限 |
### Cloudflare Workers制限への対応
- **CPU時間制限**: 15桁制限により、素因数分解の計算量を抑制
- **メモリ制限**: 素因数リストは最大でも数十要素のため問題なし
- **スクリプトサイズ**: 依存ライブラリを最小限に抑えて対応
## セキュリティアーキテクチャ
### 認証・認可
**意図的に省略** - 本アプリケーションはサンプル用途のため、認証機能を実装しません。
> **注意**: 本番環境で使用する場合は、Bearer Token認証やOAuthなどの実装を推奨します。
### 入力検証
```typescript
// すべての入力値を検証
function validateInput(input: unknown): FactorizeInput | Error {
// 1. 型チェック
if (typeof input !== 'object' || input === null) {
return new Error('正の整数を入力してください');
}
const num = (input as any).number;
// 2. 数値型チェック
if (typeof num !== 'number' || !Number.isInteger(num)) {
return new Error('正の整数を入力してください');
}
// 3. 正の整数チェック
if (num < 1) {
return new Error('正の整数を入力してください');
}
// 4. 上限チェック（DoS対策）
if (num > 999999999999999) {
return new Error('入力値が上限（15桁）を超えています');
}
return { number: num };
}
```
### セキュリティ対策一覧
| 脅威 | 対策 |
|------|------|
| DoS攻撃（計算リソース消費） | 入力値を15桁以下に制限 |
| 不正な入力値 | 厳密な型チェックとバリデーション |
| インジェクション | 入力は数値のみ、文字列処理なし |
## スケーラビリティ設計
### Cloudflare Workersによる自動スケーリング
Cloudflare Workersはエッジコンピューティングプラットフォームであり、
以下の特性を持ちます：
- **自動スケーリング**: リクエスト数に応じて自動的にインスタンス数が調整される
- **グローバル分散**: 世界中のエッジロケーションで実行される
- **ゼロコンフィグ**: スケーリングのための設定は不要
### 機能拡張性
本アプリケーションはサンプルのため、機能拡張性は考慮していません。
将来的に機能を追加する場合の指針：
- 新しいツールを追加する場合、別の関数として定義
- 複数ツールになった場合、ファイル分割を検討
## テスト戦略
### ユニットテスト（実装済み）
- **フレームワーク**: Vitest
- **対象**: 素因数分解関数（`factorize`）
- **テストファイル**: `tests/factorize.test.ts`
- **テスト数**: 13テスト
```bash
# テスト実行
npm test
```
### 統合テスト
- **方法**: Wrangler経由でローカルサーバーを起動し、HTTPリクエストでテスト
- **対象**: MCPエンドポイント（tools/list, tools/call）
### E2Eテスト
- **ツール**: Claude Desktop または Claude Code
- **シナリオ**: 実際のMCPクライアントから接続して動作確認
## 技術的制約
### 環境要件
| 項目 | 要件 |
|------|------|
| Node.js | v18以上（Wrangler実行用） |
| OS | Windows / macOS / Linux |
| ネットワーク | インターネット接続必須（Cloudflareデプロイ用） |
| Cloudflareアカウント | 無料プランで利用可能 |
### Cloudflare Workers制約
| 制約 | 値 | 影響 |
|------|-----|------|
| CPU時間/リクエスト | 10ms（Free plan） | 計算量の多い処理は不可 |
| メモリ | 128MB | 大量データの保持は不可 |
| スクリプトサイズ | 1MB | 依存ライブラリを最小限に |
| リクエストサイズ | 100MB | 問題なし |
| サブリクエスト数 | 50/リクエスト | 外部API呼び出しに制限 |
### パフォーマンス制約
- 15桁を超える数値の素因数分解はCPU時間制限を超える可能性があるため、入力を制限
## 依存関係管理
### 本番依存（dependencies）
| ライブラリ | 用途 | バージョン管理方針 |
|-----------|------|-------------------|
| hono | Webフレームワーク | ^（マイナーバージョンまで許可） |
| @hono/mcp | MCP統合 | ^（マイナーバージョンまで許可） |
| @modelcontextprotocol/sdk | MCP SDK | ^（マイナーバージョンまで許可） |
### 開発依存（devDependencies）
| ライブラリ | 用途 | バージョン管理方針 |
|-----------|------|-------------------|
| wrangler | Cloudflare CLI | ^（マイナーバージョンまで許可） |
| typescript | 型チェック・トランスパイル | ~（パッチバージョンのみ許可） |
| @cloudflare/workers-types | 型定義 | ^（マイナーバージョンまで許可） |
| vitest | テストフレームワーク | ^（マイナーバージョンまで許可） |
### バージョン管理方針
```json
{
"dependencies": {
"hono": "^4.0.0",
"@hono/mcp": "^0.1.0",
"@modelcontextprotocol/sdk": "^1.0.0"
},
"devDependencies": {
"wrangler": "^4.0.0",
"typescript": "~5.7.0",
"@cloudflare/workers-types": "^4.0.0",
"vitest": "^3.0.0"
}
}
```
**方針**:
- 安定版ライブラリは `^` でマイナーバージョンまで自動更新
- TypeScriptは破壊的変更のリスクがあるため `~` でパッチのみ
- 定期的に `npm outdated` で更新を確認
