D365fo Client

🚀 Dynamics 365 Finance & Operations MCP Server

このプロジェクトは、Microsoft Dynamics 365 Finance & Operations (D365 F&O) の全機能をAIアシスタントやその他のMCP互換ツールに公開する、本番環境で使用可能なModel Context Protocol (MCP) サーバーを提供します。標準化されたプロトコルを通じて、高度なDynamics 365統合ワークフローを実現します。

🚀 クイックスタート

インストールとセットアップ

# MCP依存関係を含むd365fo-clientをインストール
pip install d365fo-client

# 環境変数を設定
export D365FO_BASE_URL="https://your-environment.dynamics.com"
export D365FO_CLIENT_ID="your-client-id"          # デフォルトの資格情報を使用する場合は省略可能
export D365FO_CLIENT_SECRET="your-client-secret"  # デフォルトの資格情報を使用する場合は省略可能  
export D365FO_TENANT_ID="your-tenant-id"          # デフォルトの資格情報を使用する場合は省略可能

FastMCPサーバーの起動

# 開発用（stdioトランスポート - デフォルト）
d365fo-fastmcp-server

# 本番用HTTP API
d365fo-fastmcp-server --transport http --port 8000 --host 0.0.0.0

# リアルタイムWebアプリケーション（SSE）
d365fo-fastmcp-server --transport sse --port 8001 --host 0.0.0.0

AIアシスタントとの統合

VS Code統合

{
  "servers": {
    "d365fo-fastmcp-server": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "d365fo-client@latest",
        "d365fo-fastmcp-server"
      ],
      "env": {
        "D365FO_BASE_URL": "https://your-environment.dynamics.com",
        "D365FO_LOG_LEVEL": "INFO"
      }
    }
  }
}

Claude Desktop統合

{
  "mcpServers": {
    "d365fo-fastmcp": {
      "command": "uvx",
      "args": [
        "--from",
        "d365fo-client",
        "d365fo-fastmcp-server"
      ],
      "env": {
        "D365FO_BASE_URL": "https://your-environment.dynamics.com",
        "D365FO_LOG_LEVEL": "INFO"
      }
    }
  }
}

Webアプリケーションとの統合

HTTPトランスポートを使用したWeb API

import aiohttp
import json

async def call_d365fo_api():
    """Example: Using HTTP transport for web API integration"""
    
    # Start FastMCP server with HTTP transport
    # d365fo-fastmcp-server --transport http --port 8000
    
    mcp_request = {
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tools/call",
        "params": {
            "name": "d365fo_query_entities",
            "arguments": {
                "entityName": "CustomersV3",
                "top": 10,
                "select": ["CustomerAccount", "Name"]
            }
        }
    }
    
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "http://localhost:8000/mcp",
            json=mcp_request,
            headers={"Content-Type": "application/json"}
        ) as response:
            result = await response.json()
            print(json.dumps(result, indent=2))

SSEトランスポートを使用したリアルタイムアプリケーション

// Example: JavaScript client for real-time D365FO data
// Start FastMCP server: d365fo-fastmcp-server --transport sse --port 8001

const eventSource = new EventSource('http://localhost:8001/sse');

eventSource.onmessage = function(event) {
    const data = JSON.parse(event.data);
    console.log('Received D365FO data:', data);
    
    // Handle real-time updates from D365FO
    if (data.method === 'notification') {
        updateDashboard(data.params);
    }
};

// Send MCP requests via SSE
function queryCustomers() {
    const request = {
        jsonrpc: "2.0",
        id: Date.now(),
        method: "tools/call",
        params: {
            name: "d365fo_search_entities",
            arguments: {
                pattern: "customer",
                limit: 50
            }
        }
    };
    
    fetch('http://localhost:8001/sse/send', {
        method: 'POST',
        headers: {'Content-Type': 'application/json'},
        body: JSON.stringify(request)
    });
}

✨ 主な機能

MCPサーバーの機能

• 49の包括的なツール：9つの機能カテゴリにまたがる主要なD365 F&O操作を網羅
• 12のリソースタイプ：包括的なメタデータの公開と探索機能
• 2つのプロンプトテンプレート：高度なワークフロー支援
• マルチトランスポートサポート (FastMCP)：stdio、HTTP、Server-Sent Events (SSE)
• 本番環境での使用に適した実装：適切なエラーハンドリング、認証、セキュリティ検証
• パフォーマンスの向上 (FastMCP)：起動時間が40%短縮、メモリ使用量が15%削減
• 高度なプロファイル管理：複数の環境をサポートし、セキュアな資格情報の保存
• データベース分析機能：セキュアなSQLクエリとメタデータの洞察
• セッションベースの同期：詳細な進捗トラッキングと複数の同期戦略
• 多言語サポート：ラベルの解決とローカライズ機能
• エンタープライズセキュリティ：Azure AD統合、Key Vaultサポート、監査ログ

Pythonクライアントライブラリの機能

• 🔗 ODataクライアント：複合キーをサポートするD365 F&Oデータエンティティの完全なCRUD操作
• 📊 メタデータ管理V2：インテリジェントな同期とFTS5検索を備えた強化されたキャッシュシステム
• 🏷️ ラベル操作V2：パフォーマンス向上と非同期サポートを備えた多言語ラベルキャッシュ
• 🔍 高度なクエリ：すべてのODataクエリパラメータ ($select, $filter, $expandなど) をサポート
• ⚡ アクション実行：包括的なパラメータ処理を備えたバインドおよび非バインドのODataアクションの実行
• 🔒 認証：デフォルトの資格情報、サービスプリンシパル、およびAzure Key Vaultサポートを備えたAzure AD統合
• 💾 インテリジェントキャッシュ：モジュールベースのバージョン検出を備えたクロス環境キャッシュ共有
• 🌐 非同期/エイトパターン：最適化されたセッション管理を備えた最新の非同期/エイトパターン
• 📝 型ヒント：強化されたデータモデルを備えた完全な型注釈サポート
• 🤖 MCPサーバー：49のツールと4つのリソースタイプを備えた本番環境で使用可能なModel Context Protocolサーバー
• 🖥️ 包括的なCLI：すべてのD365 F&O操作に対応した階層的なコマンドラインインターフェイス
• 🧪 多層テスト：モック、サンドボックス、およびライブ統合テストフレームワーク (17/17のテストが合格)
• 📋 メタデータスクリプト：エンティティ、列挙型、およびアクションの探索用のPowerShellおよびPythonユーティリティ
• 🔐 強化された資格情報管理：Azure Key Vaultと複数の資格情報ソースをサポート
• 📊 高度な同期管理：詳細な進捗トラッキングを備えたセッションベースの同期
• 🔧 NEW v0.3.0：Pydantic設定モデルを使用した型安全な環境変数の検証
• 📂 NEW v0.3.0：カスタムログファイルパスのサポートと柔軟なロギング設定
• 🔄 NEW v0.3.0：自動的なレガシー構成の移行と互換性レイヤー

📦 インストール

MCPサーバーのインストール

VS Codeでのワンクリックインストール

Dockerを使用したインストール

# Dockerイメージを取得
docker pull ghcr.io/mafzaal/d365fo-client:latest

# DockerでMCPサーバーを実行
docker run --rm -i \
  -e D365FO_BASE_URL="https://your-environment.dynamics.com" \
  -e D365FO_CLIENT_ID="your-client-id" \
  -e D365FO_CLIENT_SECRET="your-client-secret" \
  -e D365FO_TENANT_ID="your-tenant-id" \
  -e D365FO_LOG_LEVEL="INFO" \
  -v d365fo-mcp:/home/mcp_user/ \
  ghcr.io/mafzaal/d365fo-client:latest

Pythonクライアントライブラリのインストール

# PyPIからインストール
pip install d365fo-client

# ソースからインストール
git clone https://github.com/mafzaal/d365fo-client.git
cd d365fo-client
uv sync  # uv.lockから正確な依存関係をインストール

💻 使用例

Pythonクライアントライブラリの基本的な使用法

import asyncio
from d365fo_client import D365FOClient, FOClientConfig

async def main():
    # デフォルトの資格情報を使用したシンプルな設定
    config = FOClientConfig(
        base_url="https://your-fo-environment.dynamics.com",
        use_default_credentials=True  # Azureのデフォルト資格情報を使用
    )
    
    async with D365FOClient(config) as client:
        # 接続テスト
        if await client.test_connection():
            print("✅ Connected successfully!")
        
        # 環境情報の取得
        env_info = await client.get_environment_info()
        print(f"Environment: {env_info.application_version}")
        
        # エンティティの検索（メタデータキャッシュv2を使用）
        customer_entities = await client.search_entities("customer")
        print(f"Found {len(customer_entities)} customer entities")
        
        # クエリオプションを使用した顧客の取得
        from d365fo_client import QueryOptions
        options = QueryOptions(
            select=["CustomerAccount", "Name", "SalesCurrencyCode"],
            top=10,
            orderby=["Name"]
        )
        
        customers = await client.get_data("/data/CustomersV3", options)
        print(f"Retrieved {len(customers['value'])} customers")

if __name__ == "__main__":
    asyncio.run(main())

便利関数を使用したクライアントの作成

from d365fo_client import create_client

# 強化されたデフォルト設定でクイックにクライアントを作成
async with create_client("https://your-fo-environment.dynamics.com") as client:
    customers = await client.get_data("/data/CustomersV3", top=5)

📚 ドキュメント

MCPツールの詳細情報

Comprehensive MCP Tools Introduction を参照してください。

AIエージェントとアシスタントのガイド

AI Agent Guide を参照してください。

インテグレーションテストのドキュメント

Integration Testing Documentation を参照してください。

🔧 技術詳細

MCPサーバーのアーキテクチャ

AIアシスタントにとってのメリット

• 標準化されたインターフェース：D365 F&Oへの一貫したMCPプロトコルアクセス
• 豊富なメタデータ：自己記述的なエンティティと操作
• 型安全性：すべての操作に対するスキーマ検証
• エラーコンテキスト：トラブルシューティング用の詳細なエラー情報

開発者にとってのメリット

• 最小限の統合：標準的なMCPクライアントライブラリ
• 包括的なカバレッジ：D365 F&Oの全機能が公開されている
• パフォーマンス最適化：効率的な接続とキャッシュ戦略
• 充実したドキュメント：完全なAPIドキュメントとサンプル

組織にとってのメリット

• セキュアなアクセス：エンタープライズグレードの認証 (Azure AD、Managed Identity)
• 監査ログ：完全な操作の追跡と監視
• スケーラブルな設計：コネクションプーリングとセッション管理
• 保守容易性：明確なアーキテクチャと包括的なテストカバレッジ

Pythonクライアントライブラリの技術詳細

環境変数の管理

v0.3.0から、Pydantic設定モデルを使用した型安全な環境変数の管理がサポートされています。

from d365fo_client import D365FOSettings, get_settings

# 型安全な設定インスタンスを取得
settings = get_settings()

# IntelliSenseを使用して設定にアクセス
print(f"Base URL: {settings.base_url}")
print(f"Log Level: {settings.log_level}")
print(f"Cache Directory: {settings.cache_dir}")

# 設定の状態を確認
if settings.has_client_credentials():
    print("Client credentials configured")

startup_mode = settings.get_startup_mode()  # "profile_only", "default_auth", "client_credentials"

# 外部ツール用の環境辞書に変換
env_vars = settings.to_env_dict()

認証オプション

from d365fo_client import FOClientConfig

# オプション1: Azureのデフォルト資格情報（推奨）
config = FOClientConfig(
    base_url="https://your-fo-environment.dynamics.com",
    use_default_credentials=True
)

# オプション2: クライアント資格情報
config = FOClientConfig(
    base_url="https://your-fo-environment.dynamics.com",
    client_id="your-client-id",
    client_secret="your-client-secret", 
    tenant_id="your-tenant-id",
    use_default_credentials=False
)

# オプション3: Azure Key Vault統合（v0.2.3で追加）
config = FOClientConfig(
    base_url="https://your-fo-environment.dynamics.com",
    credential_source="keyvault",  # 資格情報をAzure Key Vaultから取得
    keyvault_url="https://your-keyvault.vault.azure.net/"
)

# オプション4: カスタム設定
config = FOClientConfig(
    base_url="https://your-fo-environment.dynamics.com",
    use_default_credentials=True,
    verify_ssl=False,  # 開発環境用
    timeout=60,  # リクエストのタイムアウト時間（秒）
    metadata_cache_dir="./my_cache",  # カスタムキャッシュディレクトリ
    use_label_cache=True,  # ラベルキャッシュを有効にする
    label_cache_expiry_minutes=120  # キャッシュの有効期限（分）
)

レガシー構成の移行

v0.3.0から、レガシー構成ファイルの自動検出と移行がサポートされています。

# FastMCPサーバーが起動すると、レガシー構成が自動的に移行されます
# 手動での介入は必要ありません - 移行は透過的に行われます

📄 ライセンス

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