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入出力を型安全に検証
• エラーハンドリング: 詳細なエラー情報とリトライ機能
• エクスポネンシャルバックオフ: ネットワークエラー時の賢いリトライ戦略

🚀 クイックスタート

前提条件

• Node.js >= 18.0.0
• VergeCMS アカウント (tomohirof/verge-cms)
• MCPクライアント (Claude Desktop、ChatGPTなど)

インストール

# リポジトリのクローン
git clone https://github.com/tomohirof/verge-mcp-server.git
cd verge-mcp-server

# 依存関係のインストール
npm install

# ビルド
npm run build

環境変数の設定

.env.exampleをコピーして.envを作成:

cp .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) で開発されています:

1. Zodスキーマのユニットテスト優先: 入出力フォーマットを確定
2. APIクライアント層: fetchモックでリクエスト生成・レスポンス処理をテスト
3. MCPツール層: APIクライアントモックでハンドラーをテスト
4. 統合テスト: 型整合性と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: 以下を確認してください:

• VergeCMSのアカウントが有効か
• VERGE_API_URLが正しいか
• ブラウザ認証の場合、ブラウザが正常に起動するか
• 環境変数認証の場合、メールアドレスとパスワードが正しいか

Q: "Token expired" エラーが表示されます

A: トークンの有効期限が切れています。以下のコマンドで再認証してください:

# トークンファイルを削除
rm ~/.verge-mcp-token.json

# Claude Desktopを再起動し、再度ログインを実行

Q: MCPツールが認識されません

A: Claude Desktopの設定を確認してください:

1. claude_desktop_config.jsonのパスが正しいか
2. dist/index.jsのパスが絶対パスになっているか
3. Claude Desktopを再起動したか

Q: ビルドエラーが発生します

A: 以下を試してください:

# node_modulesを削除して再インストール
rm -rf node_modules
npm install

# ビルド
npm run build

セキュリティに関する注意事項

• トークン保存: 認証トークンは~/.verge-mcp-token.jsonに保存されます
• 環境変数: 本番環境では環境変数に認証情報を設定しないでください
• ブラウザ認証推奨: セキュリティの観点から、ブラウザ認証フローの使用を推奨します

🔗 関連リンク

• VergeCMS リポジトリ
• Model Context Protocol 公式ドキュメント
• TypeScript MCP SDK
• Zod - TypeScript-first schema validation
• 親Issue #65

📝 ライセンス

MIT License - 詳細はLICENSEを参照してください。

👤 作者

Tomohiro Fukuda

• GitHub: @tomohirof

🙏 謝辞

• Anthropic - Model Context Protocolの開発
• VergeCMS - ブログプラットフォーム
• Zod - TypeScript-first schema validation
• すべてのコントリビューターとユーザーの皆様