MCP Wygiwyh

🚀 WYGIWYH API MCP Server

WYGIWYHの経費追跡APIに対する汎用インターフェースを提供する、本番環境で使用可能なModel Context Protocol (MCP) サーバーです。このサーバーは、OpenAPI仕様から75のMCPツールを動的に生成し、AIエージェントやn8nなどの自動化プラットフォームが標準化されたツール呼び出しを通じて経費追跡システムとやり取りできるようにします。

WYGIWYH のオリジナルリポジトリ

✨ 主な機能

• 🔄 動的ツール生成 - OpenAPI仕様から自動的に75のMCPツールを生成します。
• 🔐 安全な認証 - MCPエンドポイントにはベアラートークン認証、APIアクセスには基本認証を使用します。
• 🚀 HTTPストリーム可能なトランスポート - n8nや他のMCPクライアントと完全互換性があります。
• 🐳 本番環境向けDocker - ヘルスチェック付きの最適化されたマルチステージビルドです。
• ⚡ 非同期/待機 - 効率的な非ブロッキングAPI通信を実現します。
• 📊 包括的なAPIカバレッジ - すべてのWYGIWYH APIエンドポイントがツールとして公開されています。

🎯 使用例

• n8nを使って経費追跡ワークフローを自動化する
• 財務データを管理するAIアシスタントを構築する
• WYGIWYH APIとのカスタムインテグレーションを作成する
• 音声で制御する経費記録を実装する
• 自動レポートシステムを開発する

📦 インストール

前提条件

• Docker と Docker Compose
• WYGIWYH APIの資格情報
• MCPベアラートークン

インストール手順

1. リポジトリをクローンする

   git clone https://github.com/ReNewator/MCP-WYGIWYH.git
   cd MCP-WYGIWYH
   

2. 環境を設定する

   cp .env.example .env
   # .env をあなたの資格情報で編集してください
   # server.py でWYGIWYHのURLを変更するのを忘れないでください
   

3. Dockerでデプロイする

   ./deploy.sh
   

   または手動で:

   docker-compose up -d
   

4. デプロイを確認する

   curl http://localhost:5000/health
   

🔧 設定

以下の変数を含む .env ファイルを作成してください:

# WYGIWYH API Credentials
API_USERNAME=your_email@example.com
API_PASSWORD=your_password_here

# MCP Server Authentication
MCP_TOKEN=your_mcp_bearer_token_here

🌐 n8n との統合

n8n MCPクライアントノードを設定します:

• エンドポイント: http://your-server:5000/
• トランスポート: HTTP Streamable
• 認証: ヘッダー認証
  • 名前: Authorization
  • 値: Bearer YOUR_MCP_TOKEN

🛠️ 利用可能なツール

サーバーは、カテゴリ別に整理された 75のMCPツール を公開しています:

アカウント管理

• account-groups_* - アカウントグループ操作 (6つのツール)
• accounts_* - アカウントのCRUD操作 (6つのツール)

トランザクション管理

• transactions_* - トランザクション操作 (6つのツール)
• recurring-transactions_* - 定期トランザクション管理 (6つのツール)
• installment-plans_* - 分割払いプランの処理 (6つのツール)

財務ツール

• categories_* - 経費カテゴリ管理 (6つのツール)
• tags_* - トランザクションタグ付け (6つのツール)
• currencies_* - 通貨管理 (6つのツール)
• exchange-rates_* - 為替レート操作 (6つのツール)

投資機能

• dca_* - 平均コスト法戦略 (15のツール)
• entities_* - エンティティ管理 (6つのツール)

tools/list メソッドを使用して、すべての利用可能なツールとそのスキーマを確認できます。

📁 プロジェクト構造

.
├── mcp_sse_server.py      # HTTP Streamableを備えたメインMCPサーバー
├── server.py              # コアMCP実装
├── test_server.py         # 検証スクリプト
├── Dockerfile             # 本番用Dockerイメージ
├── docker-compose.yml     # Docker Compose設定
├── deploy.sh              # 自動デプロイ
├── requirements.txt       # Python依存関係
├── DEPLOYMENT.md          # 詳細なデプロイガイド
├── PROJECT.md             # 技術ドキュメント
└── attached_assets/
    └── WYGIWYH API.yaml   # OpenAPI仕様

🚀 デプロイ

Docker (推奨)

# ビルドして実行
docker-compose up -d

# ログを表示
docker-compose logs -f

# サーバーを停止
docker-compose down

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: wygiwyh-mcp-server
spec:
  replicas: 2
  template:
    spec:
      containers:
      - name: mcp-server
        image: wygiwyh-mcp-server:latest
        ports:
        - containerPort: 5000
        env:
        - name: API_USERNAME
          valueFrom:
            secretKeyRef:
              name: wygiwyh-secrets
              key: api-username

クラウドプラットフォーム

• AWS ECS/Fargate - 環境変数付きのDockerイメージを使用します。
• Google Cloud Run - シークレット管理付きのコンテナとしてデプロイします。
• Azure Container Instances - Docker Hubから直接デプロイします。

詳細なクラウドデプロイ手順については、DEPLOYMENT.md を参照してください。

🧪 テスト

設定を検証するには、検証スクリプトを実行します:

python test_server.py

これにより、カテゴリ別にグループ化された75の生成されたMCPツールが表示されます。

📊 APIエンドポイント

• POST / - MCP JSON-RPCエンドポイント (ベアラートークンが必要)
• GET /health - ヘルスチェック (認証不要)

🔒 セキュリティ機能

• ✅ MCPアクセスにはベアラートークン認証
• ✅ WYGIWYH APIリクエストには基本認証
• ✅ ルート以外のコンテナユーザー
• ✅ 環境変数を介したシークレット管理
• ✅ ログに資格情報を公開しない

🏗️ アーキテクチャ

動的ツール生成

サーバーは、OpenAPI仕様から自動的にMCPツールを生成します:

1. WYGIWYH APIのOpenAPI YAMLを解析する
2. スキーマをJSON Schema形式に変換する
3. すべての操作に対してツールオブジェクトを作成する
4. 複雑な型の allOf マージを処理する
5. MCPプロトコルを介してツールを公開する

利点:

• 単一の情報源 (OpenAPI仕様)
• APIが変更されたときの自動更新
• 手動でのエンドポイント定義が不要
• 一貫したツールスキーマ

認証フロー

┌─────────────┐     ベアラートークン     ┌─────────────┐
│   n8n/MCP   │ ──────────────────> │  MCP Server │
│   Client    │                      │             │
└─────────────┘                      └─────────────┘
                                            │
                                            │ 基本認証
                                            ▼
                                     ┌─────────────┐
                                     │  WYGIWYH    │
                                     │     API     │
                                     └─────────────┘

🐛 トラブルシューティング

サーバーが起動しない場合

# ログを確認する
docker-compose logs

# 環境を確認する
cat .env

認証エラーが発生する場合

• API_USERNAME があなたのWYGIWYHメールアドレスであることを確認してください。
• API_PASSWORD が正しいことを確認してください。
• MCP_TOKEN がクライアントの設定と一致していることを確認してください。

接続が拒否される場合

# サーバーの状態を確認する
docker-compose ps

# ヘルスエンドポイントをテストする
curl http://localhost:5000/health

📚 ドキュメント

• DEPLOYMENT.md - 包括的なデプロイガイド
• PROJECT.md - 技術アーキテクチャドキュメント

🤝 コントリビューション

コントリビューションは大歓迎です！ 以下のガイドラインに従ってください:

1. リポジトリをフォークする
2. 機能ブランチを作成する
3. テストを含めて変更を加える
4. プルリクエストを送信する

📄 ライセンス

Copyright (c) 2025 ReNewator.com. All rights reserved.

🔗 リンク

• WYGIWYH API Documentation
• Model Context Protocol
• n8n Automation

💬 サポート

問題や質問については:

• GitHubでイシューを作成する
• 既存のドキュメントを確認する
• デプロイログを確認する

Built with ❤️ by ReNewator.com