Simplified MCP Server

🚀 シンプライファイドMCPサーバー

このModel Context Protocol (MCP)サーバーは、Claude、Cursor、Kiro（およびその他のMCP対応プラットフォーム）とSimplifiedのAPIをシームレスに統合します。このサーバーにより、LLMは標準化されたMCPツールを介してSimplifiedのサービスとやり取りでき、複数のプラットフォームでのソーシャルメディアアカウント管理と投稿作成が可能になります。

🚀 クイックスタート

このSimplified MCPサーバーを使用することで、ClaudeやKiroなどのMCP対応プラットフォームとSimplifiedのAPIを連携させることができます。以下の手順に従ってサーバーのセットアップと使用を行ってください。

✨ 主な機能

• 完全なMCPプロトコルサポート：公式の@modelcontextprotocol/sdkを使用して構築されています。
• ソーシャルメディア管理：包括的なソーシャルメディアアカウントと投稿管理機能を備えています。
• 複数プラットフォームサポート：Facebook、Instagram、Twitter、LinkedIn、TikTok、YouTube、Pinterest、Threads、Google Business Profile、Blueskyをサポートしています。
• 型安全な実装：TypeScriptで書かれており、完全な型安全性が保証されています。
• 堅牢なエラーハンドリング：詳細なエラーメッセージを伴う包括的なエラーハンドリング機能があります。
• 設定可能なロギング：デバッグと監視のためにロギングレベルを調整できます。
• プラットフォーム固有の機能：Google Business Profile、TikTok、YouTube、Instagramなどのプラットフォーム固有の高度な設定が可能です。
• スケジューリングサポート：プラットフォーム固有の設定で予約投稿を作成できます。
• 認証管理：自動リトライロジックを備えた安全なAPIトークン処理が行われます。

📦 インストール

前提条件

• Node.js 18.0.0以上
• npm 8.0.0以上
• Simplified APIトークン

NPMからのインストール

npm install -g simplified-mcp-server

ソースからのインストール

git clone https://github.com/celeryhq/simplified-mcp-server.git
cd simplified-mcp-server
npm install
npm run build

DXTファイルのパック

npm install -g @anthropic-ai/dxt
npx @anthropic-ai/dxt pack        

📚 ドキュメント

設定

サーバーは環境変数を使用して設定されます。プロジェクトルートに.envファイルを作成するか、環境変数を設定してください。

必須設定

オプション設定

設定例

# 必須
SIMPLIFIED_API_TOKEN=sk_live_your_token_here
SIMPLIFIED_API_BASE_URL=https://api.simplified.com
LOG_LEVEL=info

# オプション
REQUEST_TIMEOUT=30000
RETRY_ATTEMPTS=3
RETRY_DELAY=1000

💻 使用例

プログラムによる使用

import { SimplifiedMCPServer } from 'simplified-mcp-server';
import { ConfigurationManager } from 'simplified-mcp-server/config';

async function startServer() {
  const config = ConfigurationManager.loadConfig();
  const server = new SimplifiedMCPServer(config);
  await server.start();
}

startServer().catch(console.error);

Claudeとの統合

ClaudeのMCP設定にサーバーを追加します。

{
   "mcpServers": {
      "simplified": {
        "command": "node",
        "args": [
          "{PATH_TO_CLONED_REPOSITORY}/dist/cli.js",
          "start"
        ],
        "env": {
          "SIMPLIFIED_API_TOKEN": "your_token_here",
          "SIMPLIFIED_API_BASE_URL": "https://api.simplified.com",
          "LOG_LEVEL": "info"
        }
      }
    }
}

DXT拡張機能をインストールします。 Extensions -> Advanced settings -> Install Extension... simplified-mcp.dxtファイルを選択し、トークンを追加します。

Kiroとの統合

KiroのMCP設定にサーバーを追加します。

{
  "mcpServers": {
    "simplified": {
      "command": "simplified-mcp-server",
      "env": {
        "SIMPLIFIED_API_TOKEN": "your_token_here"
      }
    }
  }
}

利用可能なツール

サーバーは、プラットフォーム固有の機能を備えた包括的なソーシャルメディア管理ツールを提供します。

ソーシャルメディアツール

ソーシャルメディアアカウントと投稿を管理するためのツールです。

get_social_media_accounts

接続されているすべてのソーシャルメディアアカウントを取得します。 パラメーター:

• network (オプション): プラットフォームでフィルタリング（facebook, instagram, linkedin, tiktok, youtube, pinterest, threads, google, bluesky, tiktokBusiness）

例:

{
  "name": "get_social_media_accounts",
  "arguments": {
    "network": "instagram"
  }
}

create_social_media_post

Google、TikTok、Threads、YouTube、Facebook、LinkedIn、Instagram、Pinterestのプラットフォーム固有の設定で新しいソーシャルメディア投稿を作成します。 パラメーター:

• message (必須): 投稿メッセージ/内容（1 - 5000文字）
• accountId (必須): ソーシャルメディアアカウントID
• action (必須): 実行するアクション（schedule, add_to_queue, draft）
• date (オプション): 投稿の予定日（形式: YYYY-MM-DD HH:MM）
• media (オプション): 添付するメディアファイルのURLの配列（最大10個）
• additional (オプション): プラットフォーム固有の投稿設定とメタデータ

基本的な例:

{
  "name": "create_social_media_post",
  "arguments": {
    "message": "Excited to announce our new product launch! 🚀",
    "accountId": "acc_fb123",
    "action": "schedule",
    "date": "2024-01-22 12:00",
    "media": [
      "https://example.com/product-image.jpg",
      "https://example.com/launch-video.mp4"
    ],
    "additional": {}
  }
}

メディアファイル

mediaパラメーターは、メディアファイルを指すURL文字列の配列を受け入れます。

{
  "media": [
    "https://example.com/image1.jpg",
    "https://example.com/video.mp4",
    "https://example.com/image2.png"
  ]
}

メディア要件:

• 投稿ごとに最大10個のメディアファイル
• URLは公開アクセス可能でなければなりません
• サポートされる形式はプラットフォームによって異なります（画像: JPG, PNG, GIF; 動画: MP4, MOVなど）

プラットフォーム固有の機能

additionalパラメーターは、プラットフォーム固有の設定をサポートしています。

Google Business Profile

{
  "additional": {
    "google": {
      "post": {
        "title": "New Product Launch",
        "topicType": "OFFER",
        "couponCode": "LAUNCH20",
        "callToActionUrl": "https://example.com/product",
        "callToActionType": "SHOP",
        "termsConditions": "Valid until end of month"
      }
    }
  }
}

TikTok / TikTok Business

{
  "additional": {
    "tiktok": {
      "post": {
        "brandContent": true,
        "privacyStatus": "PUBLIC_TO_EVERYONE",
        "duetDisabled": false,
        "commentDisabled": false
      },
      "channel": { "value": "direct" },
      "postType": { "value": "video" }
    }
  }
}

YouTube

{
  "additional": {
    "youtube": {
      "post": {
        "title": "Product Launch Video",
        "license": "standard",
        "privacyStatus": "public",
        "selfDeclaredMadeForKids": "no"
      },
      "postType": { "value": "short" }
    }
  }
}

Instagram

{
  "additional": {
    "instagram": {
      "postReel": {
        "audioName": "Trending Audio Track",
        "shareToFeed": true
      },
      "postType": { "value": "reel" }
    }
  }
}

Pinterest

{
  "additional": {
    "pinterest": {
      "post": {
        "link": "https://example.com/product",
        "title": "Amazing Product",
        "imageAlt": "Product showcase image"
      }
    }
  }
}

LinkedIn

{
  "additional": {
    "linkedin": {
      "audience": { "value": "PUBLIC" }
    }
  }
}

Facebook

{
  "additional": {
    "facebook": {
      "postType": { "value": "feed" }
    }
  }
}

Threads

{
  "additional": {
    "threads": {
      "channel": { "value": "direct" }
    }
  }
}

プラットフォーム固有のオプションリファレンス

エラーハンドリング

サーバーは、詳細なエラーメッセージを伴う包括的なエラーハンドリングを提供します。

エラータイプ

• 設定エラー：欠落または無効な設定
• 認証エラー：無効または期限切れのAPIトークン
• APIエラー：SimplifiedのAPIからのエラー
• ツール実行エラー：ツール実行中のエラー
• 検証エラー：無効なツールパラメーター

エラーレスポンス形式

{
  "success": false,
  "error": "Error message",
  "details": {
    "type": "AUTHENTICATION_ERROR",
    "code": 401,
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

開発

ソースからのビルド

git clone https://github.com/celeryhq/simplified-mcp-server.git
cd simplified-mcp-server
npm install
npm run build

テストの実行

# すべてのテストを実行
npm test

# カバレッジ付きでテストを実行
npm run test:coverage

# ウォッチモードでテストを実行
npm run test:watch

開発モード

# 自動リロードで開発モードを開始
npm run dev

# ウォッチで開発モードを開始
npm run dev:watch

プロジェクト構造

simplified-mcp-server/
├── src/
│   ├── index.ts              # メインエントリーポイント
│   ├── server.ts             # MCPサーバーの実装
│   ├── cli.ts                # コマンドラインインターフェース
│   ├── config/
│   │   └── configuration.ts  # 設定管理
│   ├── tools/
│   │   ├── registry.ts       # ツールレジストリ
│   │   ├── definitions.ts    # ツール定義ユーティリティ
│   │   └── implementations/  # ツール実装
│   │       ├── social-media-tools.ts  # ソーシャルメディア管理ツール
│   │       └── index.ts               # ツールエクスポート
│   ├── api/
│   │   └── client.ts         # Simplified APIクライアント
│   ├── utils/
│   │   ├── errors.ts         # エラーハンドリングユーティリティ
│   │   └── logger.ts         # ロギングユーティリティ
│   └── types/
│       └── index.ts          # TypeScriptの型定義
├── tests/                    # テストファイル
├── dist/                     # コンパイルされたJavaScript
└── docs/                     # ドキュメント

トラブルシューティング

一般的な問題

サーバーが起動しない

問題：設定エラーでサーバーが起動できません。 解決策：

1. .envファイルにSIMPLIFIED_API_TOKENが含まれていることを確認します。
2. APIトークンが有効であることを確認します。
3. Node.jsのバージョンが18.0.0以上であることを確認します。

# Node.jsのバージョンを確認
node --version

# 環境変数を確認
echo $SIMPLIFIED_API_TOKEN

認証エラー

問題：API呼び出しが認証エラーで失敗します。 解決策：

1. APIトークンが正しく、期限切れでないことを確認します。
2. トークンに必要な権限があることを確認します。
3. APIのベースURLが正しいことを確認します。

ツール実行失敗

問題：ツールがエラーまたは予期しない結果を返します。 解決策：

1. ツールのパラメーターが期待されるスキーマと一致することを確認します。
2. APIエンドポイントが存在し、アクセス可能であることを確認します。
3. サーバーログを確認して詳細なエラー情報を取得します。

# デバッグロギングを有効にする
LOG_LEVEL=debug simplified-mcp-server

接続問題

問題：Simplified APIに接続できません。 解決策：

1. インターネット接続を確認します。
2. APIのベースURLがアクセス可能であることを確認します。
3. ファイアウォール制限がないかを確認します。
4. ヘルスチェックツールを使用して接続性を診断します。

デバッグモード

詳細なトラブルシューティングのためにデバッグロギングを有効にします。

LOG_LEVEL=debug simplified-mcp-server

ヘルスチェック

組み込みのヘルスチェックツールを使用してサーバーの状態を確認します。

{
  "name": "simplified-health-check",
  "arguments": {
    "includeDetails": true
  }
}

ヘルプの取得

1. ログを確認する：デバッグロギングを有効にして詳細なエラー情報を確認します。
2. 設定を検証する：すべての必須環境変数が設定されていることを確認します。
3. 接続性をテストする：ヘルスチェックとAPIステータスツールを使用します。
4. APIドキュメントを確認する：エンドポイントのパスとパラメーターを確認します。
5. 問題を報告する：GitHubリポジトリにログと設定の詳細を添付して問題を作成します。

APIリファレンス

サーバー設定

サーバーは以下の設定オプションを受け入れます。

interface ServerConfig {
  apiToken: string;           // 必須: Simplified APIトークン
  apiBaseUrl: string;         // オプション: APIのベースURL
  logLevel: 'debug' | 'info' | 'warn' | 'error'; // オプション: ログレベル
  timeout: number;            // オプション: リクエストのタイムアウト（ミリ秒）
  retryAttempts: number;      // オプション: リトライ試行回数
  retryDelay: number;         // オプション: リトライ間の遅延（ミリ秒）
}

ツールレスポンス形式

すべてのツールは以下の形式でレスポンスを返します。

interface ToolResponse {
  content: Array<{
    type: 'text';
    text: string; // 実際のレスポンスデータを含むJSON文字列
  }>;
}

成功レスポンス

{
  "success": true,
  "data": { /* レスポンスデータ */ },
  "message": "Operation completed successfully"
}

エラーレスポンス

{
  "success": false,
  "error": "Error description",
  "details": { /* 追加のエラー情報 */ }
}

貢献

私たちは貢献を歓迎します！詳細についてはContributing Guideを参照してください。

開発環境のセットアップ

1. リポジトリをフォークします。
2. あなたのフォークをクローンします：git clone https://github.com/your-username/simplified-mcp-server.git
3. 依存関係をインストールします：npm install
4. 機能ブランチを作成します：git checkout -b feature/your-feature
5. 変更を加え、テストを追加します。
6. テストを実行します：npm test
7. プロジェクトをビルドします：npm run build
8. 変更をコミットします：git commit -m "Add your feature"
9. あなたのフォークにプッシュします：git push origin feature/your-feature
10. プルリクエストを作成します。

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細についてはLICENSEファイルを参照してください。

サポート

• APIドキュメント：API Docs
• ドキュメント：GitHub Wiki
• 問題報告：GitHub Issues
• ディスカッション：GitHub Discussions