# 個人データビューワー→MCP化の完全ガイド
このガイドは、Kindle・Kobo・PDF・Booklog・Twitterアーカイブなどの個人データから、HTML Viewer → CLI → MCP Server まで一気通貫で構築した実践記録です。
## 📚 ステップ1:データ収集
### 書籍データの収集
**Kindle**
- Chrome拡張機能を使用してライブラリ情報を抽出
- JSON形式で出力(タイトル、著者、ASIN、取得日など)
**Kobo**
- ローカルのKoboライブラリデータベース(SQLite)から情報抽出
- JSON形式で出力
**PDF**
- Google Driveなどに保存されたPDFファイルのメタデータを抽出
- PDFライブラリやファイル情報から著者・タイトルを取得
**Booklog**
- CSV形式でエクスポート
- 読書状況などの追加情報を含む
### Twitterデータの収集
**アーカイブのダウンロード**
- X(Twitter)の設定からアーカイブをリクエスト
- `tweets.js`などのファイルを含むZIPファイルを取得
## 🎨 ステップ2:HTMLビューワーの作成
### AIへの指示例
```
「以下のJSONデータをもとに、書籍を検索・フィルター・表示できるHTMLビューワーを作ってください:
- kindle.json
- kobo.json
- pdf_books.json
- booklog_utf8.csv
必要な機能:
- キーワード検索(タイトル・著者)
- ソースでフィルター(Kindle/Kobo/PDF/Booklog)
- 読書状況でフィルター(既読/未読)
- ジャンルでフィルター
- ソート機能(取得日順など)
- レスポンシブデザイン
」
```
### AIが生成してくれるもの
✅ HTML CSS JavaScriptの完全なビューワー
✅ データ読み込み処理
✅ フィルタリング・検索ロジック
✅ 見やすいUI(カード形式など)
✅ ダークモード対応(オプション)
### 同様にTwitterビューワーも
```
「tweets_all.jsonをもとに、Twitterアーカイブビューワーを作ってください:
必要な機能:
- キーワード検索
- 日付範囲フィルター
- オリジナル/RT/リプライでフィルター
- スレッド表示
- 画像表示
- ページネーション
」
```
## 💻 ステップ3:CLIツールの作成
### AIへの指示例
```
「先ほど作成したHTMLビューワーと同じ機能を持つCLIツールを作ってください:
/Users/daisukemiyata/aipm_v3/Stock/programs/Tools/projects/book_viewer/
以下のファイル構成で:
- book_cli.py(メインスクリプト)
- bk(ショートカットスクリプト)
必要な機能:
- 引数でキーワード検索(-q, --query)
- 読書状況でフィルター(-r, --read-status)
- ソースでフィルター(-s, --source)
- ジャンルでフィルター(-g, --genre)
- 件数制限(-l, --limit)
- 統計表示(--stats)
」
```
### AIが生成してくれるもの
✅ `argparse`を使った本格的なCLI
✅ HTMLビューワーと同じフィルタリングロジック
✅ 統計情報の集計・表示
✅ カラフルな出力(絵文字など)
## 🔌 ステップ4:MCP Server化(重要!)
### 事前準備:公式ドキュメントを読み込ませる
**重要**: MCPはモデルに知識が少ないため、公式ドキュメントを読み込ませることが必須です。
```
「以下のMCP公式ドキュメントを参考に、MCPサーバーを作成してください:
modelcontextprotocol.io/docs…
spec.modelcontextprotocol.io…
特に以下を重視:
- stdio通信方式
- mcp Python SDKの使い方
- Tool定義の方法
」
```
### AIへの具体的な指示
```
「book_cli.pyをMCPサーバー化してください:
1. mcp Python SDKを使用
2. 以下のツールを提供:
- book_search: 書籍検索
- book_stats: 統計情報表示
3. 仮想環境を作成してmcp SDKをインストール
4.
server.pyを作成
5. .cursor/mcp.jsonに設定を追加
」
```
### MCP化のコツ(重要!)
#### 1. **仮想環境の作成が必須**
```bash
# プロジェクトごとに専用の仮想環境を作る
cd /path/to/project
python3 -m venv venv
./venv/bin/pip install mcp
```
#### 2. **stdio通信を使う**
MCPはHTTPではなく**stdio**(標準入出力)で通信します。
```python
# ❌ NG: http.serverを使う
# ✅ OK: mcp SDKのToolServerを使う
from mcp import Tool, ToolServer, ToolServerConfig
server = ToolServer(config)
server.run() # これがstdio通信を自動で処理
```
#### 3. **mcp.jsonの設定**
```json
{
"mcpServers": {
"book-viewer": {
"command": "/絶対パス/venv/bin/python",
"args": [
"/絶対パス/server.py"
]
}
}
}
```
**重要ポイント**:
- `command`は仮想環境内のPythonの**絶対パス**
- `args`は
server.pyの**絶対パス**
- 相対パスは使わない
#### 4. **Tool定義のパターン**
```python
book_search_tool = Tool(
name="book_search",
description="書籍を検索・フィルターします。",
parameters={
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "検索キーワード"
},
"limit": {
"type": "integer",
"description": "表示件数"
}
}
},
function=lambda query=None, limit=10: {
"results":
cli.search(query, limit)
}
)
```
#### 5. **デバッグ方法**
**ターミナルで直接起動してテスト**:
```bash
cd /path/to/project
./venv/bin/python
server.py
# エラーメッセージを確認
```
**Cursor再起動が必要**:
- mcp.json変更後は必ずCursorを完全再起動
- 設定が反映されないと「NoTools」エラーになる
## 🎯 全体フロー図
```
データ収集
↓
JSON/CSV化
↓
HTMLビューワー作成(AIに丸投げ)
↓
動作確認・改善
↓
CLIツール作成(AIに丸投げ)
↓
動作確認
↓
MCP化(公式ドキュメント読み込ませ必須)
↓
仮想環境作成
↓
server.py作成
↓
mcp.json設定
↓
Cursor再起動
↓
動作確認
```
## 🚀 実際に作成したツール
### Book Viewer
- **データソース**: Kindle、Kobo、PDF、Booklog(計3,938冊)
- **HTML Viewer**: `book_viewer.html`
- **CLI**: `book_cli.py` `bk`
- **MCP Server**: `
server.py`
- **ツール**: `book_search`, `book_stats`
### Twitter Viewer
- **データソース**: Twitterアーカイブ(36,000ツイート)
- **HTML Viewer**: `twitter_viewer.html`
- **CLI**: `twitter_cli.py` `tw`
- **MCP Server**: `
server.py`
- **ツール**: `twitter_search`, `twitter_stats`
## 💡 成功のポイント
### 1. **段階的に進める**
いきなりMCPを作らず、HTML → CLI → MCP の順で進める。各段階で動作確認。
### 2. **AIに丸投げできる部分、できない部分を見極める**
**丸投げOK**:
- HTMLビューワーの実装
- CLIツールの実装
- データ正規化ロジック
**人間の介入が必要**:
- MCP公式ドキュメントの提示
- mcp.jsonの設定確認
- Cursorの再起動
- デバッグ時の問題切り分け
### 3. **公式ドキュメントは必須**
MCPはまだ新しい技術で、モデルの知識が不足している。以下を必ず読み込ませる:
-
modelcontextprotocol.io/
-
spec.modelcontextprotocol.io…
- Python SDK:
github.com/modelcontextproto…
## 📝 AIへの指示のコツ
### HTMLビューワー作成時
```
✅ 「〜の機能を持つビューワーを作って」
✅ データファイルのパスを明示
✅ 必要な機能をリスト形式で列挙
✅ UI/UXの要望があれば具体的に
```
### CLI作成時
```
✅ 「HTMLビューワーと同じ機能のCLIを作って」
✅ ファイル名・保存場所を指定
✅ 引数の仕様を明示(-q, --queryなど)
✅ 出力形式の要望(テーブル、JSON等)
```
### MCP化時
```
✅ 「公式ドキュメントを参考に」と明示
✅ 仮想環境の場所を指定
✅ .cursor/mcp.jsonの場所を明示
✅ Tool名とdescriptionを具体的に指定
```
## 🎯 結論
**HTMLビューワー → CLI → MCP** という段階的アプローチが成功の鍵。
特にMCP化は:
1. **公式ドキュメントを読み込ませる**
2. **仮想環境を必ず使う**
3. **絶対パスで設定**
4. **Cursor再起動を忘れない**
この4点を守れば、AIが9割やってくれます!
---
**作成日**: 2025-10-12
**プロジェクト**: Book Viewer & Twitter Viewer
**技術スタック**: Python, mcp SDK, HTML/CSS/JS