Verge MCP Server
Model Context Protocol (MCP) server for VergeCMS - ChatGPT/ClaudeなどのAIアシスタントから直接ブログを管理
📋 概要
Verge MCP Serverは、VergeCMSをModel Context Protocol (MCP)サーバーとして実装したものです。Claude DesktopやChatGPTなどのAIアシスタントから、ブログの作成・管理、記事の作成・編集・公開を自然言語で行うことができます。
なぜこれが重要か？
AIアシスタントから直接CMS操作: 自然言語でブログや記事を管理
14の強力なツール: 認証、ブログ管理、記事管理の完全なCRUD操作
3ステップ自動認証: ブラウザ起動→ユーザー承認→トークン永続化
型安全なAPI: TypeScript + Zodによる完全な型チェックとバリデーション
TDD開発: 155のテストによる品質保証
✨ 主な機能
ツール構成（14ツール）
認証ツール（3個）
verge_login - ブラウザ自動起動による認証フロー
verge_get_current_user - 現在のユーザー情報取得
verge_update_user - ユーザー情報更新
ブログ管理ツール（5個）
verge_list_blogs - ブログ一覧取得
verge_get_blog - ブログ詳細取得
verge_create_blog - ブログ作成
verge_update_blog - ブログ更新
verge_delete_blog - ブログ削除
記事管理ツール（6個）
verge_list_articles - 記事一覧取得（検索・フィルタリング可能）
verge_get_article - 記事詳細取得
verge_create_article - 記事作成
verge_update_article - 記事更新
verge_publish_article - 記事公開
verge_delete_article - 記事削除
その他の特徴
自動認証フロー: ブラウザが自動起動し、認証後トークンを安全に保存
Zodバリデーション: すべてのAPI入出力を型安全に検証
エラーハンドリング: 詳細なエラー情報とリトライ機能
エクスポネンシャルバックオフ: ネットワークエラー時の賢いリトライ戦略
🚀 クイックスタート
前提条件
インストール
# リポジトリのクローン
git clone https://github.com/tomohirof/verge-mcp-server.git
cd verge-mcp-server
# 依存関係のインストール
npm install
# ビルド
npm run build
環境変数の設定
.env.exampleをコピーして.envを作成:
.envファイルを編集:
# Plume API URL
VERGE_API_URL=https://api.vergecms.io
# 認証情報（オプション: ブラウザ認証を使う場合は不要）
VERGE_EMAIL=your-email@example.com
VERGE_PASSWORD=your-password
注意: 環境変数に認証情報を設定しなくても、初回実行時にブラウザ認証フローが自動的に開始されます。
MCPクライアントでの設定
Claude Desktopの場合
~/Library/Application Support/Claude/claude_desktop_config.jsonに追加:
{
"mcpServers": {
"plume": {
"command": "node",
"args": ["/absolute/path/to/verge-mcp-server/dist/index.js"],
"env": {
"VERGE_API_URL": "https://api.vergecms.io"
}
}
}
}
Claude Desktopを再起動後、以下のようにプロンプトで利用できます:
あなた: "ブログを作成してください。名前は『Tech Blog』です"
→ verge_create_blogツールが実行され、ブログが作成されます
あなた: "先ほど作成したブログに新しい記事を書いてください"
→ verge_create_articleツールが実行され、記事が作成されます
あなた: "記事を公開してください"
→ verge_publish_articleツールが実行され、記事が公開されます
🔐 3ステップ認証フロー
このMCPサーバーは、安全で使いやすい3ステップ認証フローを提供します:
1. ブラウザ自動起動
↓
MCPサーバーが認証用URLでブラウザを自動的に開きます
2. ユーザー承認
↓
ブラウザでVergeCMSにログインし、MCPサーバーへのアクセスを承認
3. トークン永続化
↓
認証トークンが安全にローカルに保存され、次回以降自動的に使用されます
認証の使い方
方法1: ブラウザ認証（推奨）
// Claude Desktopで以下のように実行
"VergeCMSにログインしてください"
// 自動的にブラウザが起動し、認証フローが開始されます
// 一度認証すれば、トークンが保存され、次回以降は自動ログイン
方法2: 環境変数認証
.envファイルに認証情報を設定:
VERGE_EMAIL=your-email@example.com
VERGE_PASSWORD=your-password
📚 ツールリファレンス
認証ツール
verge_login
VergeCMSにログインし、JWTトークンを取得します。
入力パラメータ:
{
email?: string; // メールアドレス（オプション: 省略時はブラウザ認証）
password?: string; // パスワード（オプション）
}
レスポンス例:
{
success: true,
token: "eyJhbGc...",
user: {
id: 1,
email: "user@example.com",
name: "John Doe"
}
}
verge_get_current_user
現在ログイン中のユーザー情報を取得します。
入力パラメータ: なし
レスポンス例:
{
id: 1,
email: "user@example.com",
name: "John Doe",
created_at: "2024-01-01T00:00:00Z"
}
verge_update_user
ユーザー情報を更新します。
入力パラメータ:
{
user_id: number; // ユーザーID
name?: string; // 新しい名前
email?: string; // 新しいメールアドレス
password?: string; // 新しいパスワード
}
ブログ管理ツール
verge_list_blogs
すべてのブログを一覧表示します。
入力パラメータ: なし
レスポンス例:
[
{
id: 1,
name: "Tech Blog",
title: "技術ブログ",
slug: "tech-blog",
description: "技術記事を書くブログ"
}
]
verge_get_blog
特定のブログの詳細情報を取得します。
入力パラメータ:
{
blog_id: number; // ブログID
}
verge_create_blog
新しいブログを作成します。
入力パラメータ:
{
name: string; // ブログ名（必須）
title: string; // タイトル（必須）
slug: string; // URLスラッグ（必須）
description?: string; // 説明（オプション）
}
使用例:
// Claude Desktopでの使用例
"新しいブログを作成してください。
名前: 'My Tech Blog'
タイトル: '技術ブログ'
スラッグ: 'tech-blog'
説明: '最新の技術トレンドを発信するブログ'"
verge_update_blog
既存のブログを更新します。
入力パラメータ:
{
blog_id: number; // ブログID（必須）
name?: string; // 新しい名前
title?: string; // 新しいタイトル
slug?: string; // 新しいスラッグ
description?: string; // 新しい説明
}
verge_delete_blog
ブログを削除します。
入力パラメータ:
{
blog_id: number; // ブログID
}
記事管理ツール
verge_list_articles
記事一覧を取得します（検索・フィルタリング可能）。
入力パラメータ:
{
blog_id: number; // ブログID（必須）
search?: string; // 検索キーワード
status?: 'draft' | 'published'; // ステータスフィルタ
category_ids?: number[]; // カテゴリIDでフィルタ
tag_ids?: number[]; // タグIDでフィルタ
}
使用例:
// 公開済み記事のみを取得
{
blog_id: 1,
status: 'published'
}
// キーワード検索
{
blog_id: 1,
search: 'TypeScript'
}
verge_get_article
記事の詳細情報を取得します。
入力パラメータ:
{
article_id: number; // 記事ID
blog_id: number; // ブログID
}
verge_create_article
新しい記事を作成します。
入力パラメータ:
{
blog_id: number; // ブログID（必須）
title: string; // タイトル（必須）
content: string; // 本文（必須、Markdown）
slug: string; // URLスラッグ（必須）
status?: 'draft' | 'published'; // ステータス（デフォルト: draft）
featured_image?: string; // アイキャッチ画像URL
excerpt?: string; // 抜粋
author_id?: number; // 著者ID
category_ids?: number[]; // カテゴリID配列
tag_ids?: number[]; // タグID配列
}
使用例:
// Claude Desktopでの使用例
"新しい記事を作成してください。
ブログID: 1
タイトル: 'TypeScriptでMCPサーバーを作る'
スラッグ: 'typescript-mcp-server'
内容: '# はじめに\n\nこの記事では...'"
verge_update_article
既存の記事を更新します。
入力パラメータ:
{
article_id: number; // 記事ID（必須）
blog_id: number; // ブログID（必須）
title?: string; // 新しいタイトル
content?: string; // 新しい本文
slug?: string; // 新しいスラッグ
status?: 'draft' | 'published'; // 新しいステータス
featured_image?: string; // 新しいアイキャッチ画像
excerpt?: string; // 新しい抜粋
author_id?: number; // 新しい著者ID
category_ids?: number[]; // 新しいカテゴリID配列
tag_ids?: number[]; // 新しいタグID配列
}
verge_publish_article
記事を公開状態に変更します。
入力パラメータ:
{
article_id: number; // 記事ID
blog_id: number; // ブログID
}
verge_delete_article
記事を削除します。
入力パラメータ:
{
article_id: number; // 記事ID
blog_id: number; // ブログID
}
🧪 開発ワークフロー
TDD方針
このプロジェクトはTest-Driven Development (TDD) で開発されています:
Zodスキーマのユニットテスト優先: 入出力フォーマットを確定
APIクライアント層: fetchモックでリクエスト生成・レスポンス処理をテスト
MCPツール層: APIクライアントモックでハンドラーをテスト
統合テスト: 型整合性とMCPプロトコル整合性を確認
現在のテスト状態: 155テスト全てパス ✅
テストの実行
# 全テスト実行
npm test
# テストUI起動
npm run test:ui
# カバレッジ測定
npm run test:coverage
開発コマンド
# TypeScriptを直接実行（開発モード）
npm run dev
# MCPインスペクター（ツールの動作を検証）
npm run inspector
# ビルド
npm run build
# 型チェック
npx tsc --noEmit
# Lint
npm run lint
📂 プロジェクト構造
verge-mcp-server/
├── src/
│ ├── index.ts # MCPサーバーエントリーポイント
│ ├── server.ts # MCPサーバーコア実装
│ ├── config.ts # 環境変数管理
│ ├── auth/
│ │ ├── index.ts # 認証フロー統合
│ │ ├── browser-auth.ts # ブラウザ認証フロー
│ │ └── token-storage.ts # トークン永続化
│ ├── client/
│ │ ├── types.ts # Zodスキーマ・型定義
│ │ ├── errors.ts # カスタムエラークラス
│ │ └── api.ts # Plume APIクライアント
│ └── tools/
│ ├── schemas.ts # MCPツール入力スキーマ
│ ├── auth.ts # 認証ツールハンドラー
│ ├── blogs.ts # ブログ管理ツールハンドラー
│ └── articles.ts # 記事管理ツールハンドラー
├── tests/
│ ├── client/
│ │ ├── types.test.ts # Zodスキーマテスト（43テスト）
│ │ ├── api.test.ts # APIクライアントテスト（21テスト）
│ │ ├── api-retry.test.ts # リトライ機能テスト（11テスト）
│ │ ├── api-backoff.test.ts # バックオフテスト（7テスト）
│ │ ├── api-timeout.test.ts # タイムアウトテスト（5テスト）
│ │ └── errors.test.ts # エラーハンドリングテスト（11テスト）
│ ├── tools/
│ │ ├── auth.test.ts # 認証ツールテスト（6テスト）
│ │ ├── blogs.test.ts # ブログ管理ツールテスト（10テスト）
│ │ └── articles.test.ts # 記事管理ツールテスト（8テスト）
│ └── integration/
│ ├── server.e2e.test.ts # E2Eテスト（6テスト）
│ ├── error-handling.test.ts # エラーハンドリング統合テスト（8テスト）
│ └── articles.scenario.test.ts # 記事管理シナリオテスト（3テスト）
├── dist/ # ビルド出力
├── package.json
├── tsconfig.json
├── vitest.config.ts
└── README.md
🔧 トラブルシューティング
よくある質問（FAQ）
Q: 認証に失敗します
A: 以下を確認してください:
Q: "Token expired" エラーが表示されます
A: トークンの有効期限が切れています。以下のコマンドで再認証してください:
# トークンファイルを削除
rm ~/.verge-mcp-token.json
# Claude Desktopを再起動し、再度ログインを実行
Q: MCPツールが認識されません
A: Claude Desktopの設定を確認してください:
claude_desktop_config.jsonのパスが正しいか
dist/index.jsのパスが絶対パスになっているか
Claude Desktopを再起動したか
Q: ビルドエラーが発生します
A: 以下を試してください:
# node_modulesを削除して再インストール
rm -rf node_modules
npm install
# ビルド
npm run build
セキュリティに関する注意事項
トークン保存: 認証トークンは~/.verge-mcp-token.jsonに保存されます
環境変数: 本番環境では環境変数に認証情報を設定しないでください
ブラウザ認証推奨: セキュリティの観点から、ブラウザ認証フローの使用を推奨します
🔗 関連リンク
📝 ライセンス
MIT License - 詳細はLICENSEを参照してください。
👤 作者
Tomohiro Fukuda
🙏 謝辞
