D365fo Client

🚀 Dynamics 365 Finance & Operations MCP Server

這是一個生產就緒的模型上下文協議（MCP）服務器，它將 Microsoft Dynamics 365 Finance & Operations（D365 F&O）的全部功能開放給 AI 助手和其他 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 服務器（推薦）

現代的 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

主要優勢：

• 使用 FastMCP 框架優化性能。
• 通過優化架構實現高效的資源利用。
• 支持多傳輸方式：stdio、HTTP、服務器發送事件（SSE）。
• 增強的錯誤處理，提供更好的異步/等待支持。
• 具備用於 API 集成的 Web 傳輸功能，可用於生產環境。

與 AI 助手集成

VS Code 集成（推薦）

使用默認憑證的 FastMCP 服務器： 將以下內容添加到你的 VS Code mcp.json 中，以用於支持 MCP 的 GitHub Copilot：

{
  "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"
      }
    }
  }
}

選項 2：顯式憑證 對於需要服務主體認證的環境：

{
  "servers": {
    "d365fo-fastmcp-server": {
      "type": "stdio", 
      "command": "uvx",
      "args": [
        "--from",
        "d365fo-client",
        "d365fo-fastmcp-server"
      ],
      "env": {
        "D365FO_BASE_URL": "https://your-environment.dynamics.com",
        "D365FO_LOG_LEVEL": "DEBUG",
        "D365FO_CLIENT_ID": "${input:client_id}",
        "D365FO_CLIENT_SECRET": "${input:client_secret}",
        "D365FO_TENANT_ID": "${input:tenant_id}"
      }
    }
  },
  "inputs": [
    {
      "id": "tenant_id",
      "type": "promptString",
      "description": "用於 D365 F&O 認證的 Azure AD 租戶 ID",
      "password": true
    },
    {
      "id": "client_id", 
      "type": "promptString",
      "description": "用於 D365 F&O 認證的 Azure AD 客戶端 ID",
      "password": true
    },
    {
      "id": "client_secret",
      "type": "promptString", 
      "description": "用於 D365 F&O 認證的 Azure AD 客戶端密鑰",
      "password": true
    }
  ]
}

選項 3：Docker 集成 對於容器化環境和增強的隔離性：

{
  "servers": {
    "d365fo-fastmcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "d365fo-mcp:/home/mcp_user/",
        "-e",
        "D365FO_CLIENT_ID=${input:client_id}",
        "-e",
        "D365FO_CLIENT_SECRET=${input:client_secret}",
        "-e",
        "D365FO_TENANT_ID=${input:tenant_id}",
        "ghcr.io/mafzaal/d365fo-client:latest"
      ],
      "env": {
        "D365FO_LOG_LEVEL": "DEBUG",
        "D365FO_CLIENT_ID": "${input:client_id}",
        "D365FO_CLIENT_SECRET": "${input:client_secret}",
        "D365FO_TENANT_ID": "${input:tenant_id}"
      }
    }
  },
  "inputs": [
    {
      "id": "tenant_id",
      "type": "promptString",
      "description": "用於 D365 F&O 認證的 Azure AD 租戶 ID",
      "password": true
    },
    {
      "id": "client_id",
      "type": "promptString",
      "description": "用於 D365 F&O 認證的 Azure AD 客戶端 ID",
      "password": true
    },
    {
      "id": "client_secret",
      "type": "promptString",
      "description": "用於 D365 F&O 認證的 Azure AD 客戶端密鑰",
      "password": true
    }
  ]
}

Docker 方式的優勢：

• 完整的環境隔離和可重複性。
• 無需本地安裝 Python。
• 不同系統間的運行時環境一致。
• 通過預構建鏡像實現自動依賴管理。
• 通過容器化增強安全性。
• 通過 Docker 卷（d365fo-mcp）實現持久數據存儲。

前提條件：

• 已安裝並運行 Docker。
• 可以訪問 Docker Hub 或 GitHub 容器註冊表。
• 具備拉取容器鏡像的網絡訪問權限。

Claude Desktop 集成

FastMCP 服務器： 將以下內容添加到你的 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"
      }
    }
  }
}

傳統 MCP 服務器（替代方案）：

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

uvx 方式的優勢：

• 始終使用倉庫中的最新版本。
• 無需本地安裝。
• 自動進行依賴管理。
• 適用於不同的環境。

與 FastMCP 進行 Web 集成

FastMCP 服務器為 Web 應用程序集成提供了 HTTP 和 SSE 傳輸方式：

用於 Web API 的 HTTP 傳輸

import aiohttp
import json

async def call_d365fo_api():
    """示例：使用 HTTP 傳輸進行 Web API 集成"""
    
    # 啟動帶有 HTTP 傳輸的 FastMCP 服務器
    # 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 傳輸

// 示例：用於即時 D365FO 數據的 JavaScript 客戶端
// 啟動 FastMCP 服務器：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);
    
    // 處理來自 D365FO 的即時更新
    if (data.method === 'notification') {
        updateDashboard(data.params);
    }
};

// 通過 SSE 發送 MCP 請求
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)
    });
}

替代方案：編程式使用

from d365fo_client.mcp import D365FOMCPServer

# 使用自定義配置創建並運行服務器
config = {
    "default_environment": {
        "base_url": "https://your-environment.dynamics.com",
        "use_default_credentials": True
    }
}

server = D365FOMCPServer(config)
await server.run()

自定義 MCP 客戶端

使用任何 MCP 兼容的客戶端庫進行連接：

from mcp import Client

async with Client("d365fo-fastmcp-server") as client:
    # 發現可用工具
    tools = await client.list_tools()
    
    # 執行操作
    result = await client.call_tool(
        "d365fo_query_entities",
        {"entityName": "Customers", "top": 5}
    )

Docker 部署

對於容器化環境和生產部署： 拉取 Docker 鏡像：

# 從 GitHub 容器註冊表拉取
docker pull ghcr.io/mafzaal/d365fo-client:latest

# 或者拉取特定版本
docker pull ghcr.io/mafzaal/d365fo-client:v0.2.3

獨立 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

# 使用 Docker 運行 CLI 命令
docker run --rm -it \
  -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" \
  ghcr.io/mafzaal/d365fo-client:latest \
  d365fo-client entities --limit 10

Docker Compose 示例：

version: '3.8'
services:
  d365fo-mcp:
    image: ghcr.io/mafzaal/d365fo-client:latest
    environment:
      - D365FO_BASE_URL=https://your-environment.dynamics.com
      - D365FO_CLIENT_ID=${D365FO_CLIENT_ID}
      - D365FO_CLIENT_SECRET=${D365FO_CLIENT_SECRET}
      - D365FO_TENANT_ID=${D365FO_TENANT_ID}
      - D365FO_LOG_LEVEL=INFO
    volumes:
      - d365fo-mcp:/home/mcp_user/
    stdin_open: true
    tty: true

volumes:
  d365fo-mcp:

Docker 的優勢：

• 完整的環境隔離和可重複性。
• 無需本地安裝 Python。
• 不同系統間的運行時環境一致。
• 內置依賴管理。
• 通過容器化增強安全性。
• 通過 Docker 卷實現持久數據存儲。
• 易於與編排平臺（Kubernetes、Docker Swarm）集成。

✨ 主要特性

• 49 個綜合工具：涵蓋 9 個功能類別中的所有主要 D365 F&O 操作。
• 12 種資源類型：具備全面的元數據暴露和發現功能。
• 2 個提示模板：用於高級工作流輔助。
• 多傳輸支持（FastMCP）：stdio、HTTP、服務器發送事件（SSE）。
• 生產就緒：實現了正確的錯誤處理、身份驗證和安全驗證。
• 性能提升（FastMCP）：啟動速度提高 40%，內存使用降低 15%。
• 高級配置文件管理：支持多個環境，並安全存儲憑證。
• 數據庫分析功能：支持安全的 SQL 查詢和元數據洞察。
• 基於會話的同步：詳細的進度跟蹤和多種同步策略。
• 多語言支持：具備標籤解析和本地化功能。
• 企業安全：與 Azure AD 集成，支持 Key Vault 和審計日誌記錄。

v0.3.0 版本新增特性

• 🔧 Pydantic 設置模型：對 35 多個配置選項進行類型安全的環境變量管理和驗證。
• 📂 自定義日誌文件支持：使用 D365FO_LOG_FILE 環境變量設置靈活的日誌文件路徑。
• 🔄 舊配置遷移：自動檢測並遷移舊的配置文件。
• 🌐 環境變量標準化：所有 MCP HTTP 變量現在都使用 D365FO_ 前綴以保持一致性。
• ⚡ 增強的 FastMCP 服務器：改進了啟動配置、錯誤處理和優雅關閉功能。
• 🔀 MCP 返回類型標準化：所有 MCP 工具現在返回字典而不是 JSON 字符串，以提高類型安全性。
• 🛠️ 增強的配置：支持 .env 文件，並提供全面的環境變量文檔。

📦 安裝指南

一鍵安裝到 VS Code

使用 Docker 安裝到 VS Code

部署到 Azure 容器應用

將 MCP 服務器部署為一個安全的、可通過互聯網訪問的 HTTP 端點，並使用 OAuth 或 API 密鑰進行身份驗證。非常適合 Web 集成和遠程 AI 助手訪問。 選項 1：使用 Bash 腳本（推薦）

# 下載並運行部署腳本
curl -O https://raw.githubusercontent.com/mafzaal/d365fo-client/main/deploy-aca.sh
chmod +x deploy-aca.sh

# 設置認證（選擇 OAuth 或 API 密鑰）
export D365FO_MCP_AUTH_CLIENT_ID="your-client-id"
export D365FO_MCP_AUTH_CLIENT_SECRET="your-client-secret"
export D365FO_MCP_AUTH_TENANT_ID="your-tenant-id"
# 或者
export D365FO_MCP_API_KEY_VALUE="your-secret-key"

# 部署
./deploy-aca.sh

選項 2：使用 ARM 模板

1. 下載 azure-deploy.json
2. 訪問 Azure 門戶 → 部署自定義模板
3. 點擊“在編輯器中自己構建模板”
4. 粘貼 azure-deploy.json 的內容
5. 填寫參數並部署

💻 使用示例

基本工具執行

{
  "tool": "d365fo_query_entities",
  "arguments": {
    "entityName": "CustomersV3",
    "select": ["CustomerAccount", "Name", "Email"],
    "filter": "CustomerGroup eq 'VIP'",
    "top": 10
  }
}

實體架構發現

{
  "tool": "d365fo_get_entity_schema", 
  "arguments": {
    "entityName": "CustomersV3",
    "includeProperties": true,
    "resolveLabels": true,
    "language": "en-US"
  }
}

環境信息

{
  "tool": "d365fo_get_environment_info",
  "arguments": {}
}

📚 詳細文檔

MCP 服務器概述

d365fo-client 包含一個基於 FastMCP 框架構建的生產就緒的模型上下文協議（MCP）服務器 (d365fo-fastmcp-server)，它將 D365 Finance & Operations 的全部功能開放給 AI 助手和其他 MCP 兼容工具。 該服務器提供多傳輸支持（stdio、HTTP、SSE），具有增強的性能和部署靈活性。

架構優勢

對於 AI 助手

• 標準化接口：通過一致的 MCP 協議訪問 D365 F&O。
• 豐富的元數據：自描述的實體和操作。
• 類型安全：對所有操作進行模式驗證。
• 錯誤上下文：提供詳細的錯誤信息，便於故障排除。

對於開發人員

• 最小化集成：使用標準的 MCP 客戶端庫。
• 全面覆蓋：暴露 D365 F&O 的全部功能。
• 性能優化：採用高效的連接和緩存策略。
• 文檔完善：提供完整的 API 文檔和示例。

對於組織

• 安全訪問：企業級身份驗證（Azure AD、託管標識）。
• 審計日誌：完整的操作跟蹤和監控。
• 可擴展設計：連接池和會話管理。
• 易於維護：清晰的架構和全面的測試覆蓋。

故障排除

常見問題

連接失敗

# 測試連接性
d365fo-client version app --base-url https://your-environment.dynamics.com

# 查看日誌
tail -f ~/.d365fo-mcp/logs/mcp-server.log

身份驗證問題

# 驗證 Azure CLI 身份驗證
az account show

# 使用顯式憑證進行測試
export D365FO_CLIENT_ID="your-client-id"
# ... 設置其他變量
d365fo-fastmcp-server

性能問題

# 啟用調試日誌
export D365FO_LOG_LEVEL="DEBUG"

# 調整連接設置
export D365FO_CONNECTION_TIMEOUT="120"
export D365FO_MAX_CONCURRENT_REQUESTS="5"

獲取幫助

• 日誌：查看 ~/.d365fo-mcp/logs/mcp-server.log 以獲取詳細的錯誤信息。
• 環境：使用 d365fo_get_environment_info 工具檢查系統狀態。
• 文檔：查看 MCP 實現總結 以獲取技術細節。
• 問題反饋：在 GitHub 問題 中報告問題。

MCP 工具

服務器提供49 個綜合工具，按功能類別組織：

連接與環境工具（2 個）

• d365fo_test_connection：使用性能指標和錯誤診斷測試連接性和身份驗證。
• d365fo_get_environment_info：獲取包括版本、配置和功能在內的全面環境詳細信息。

CRUD 操作工具（7 個）

• d365fo_query_entities：使用 'eq' 過濾、通配符模式、字段選擇和分頁進行簡化的 OData 查詢。
• d365fo_get_entity_record：通過鍵檢索特定記錄，並支持擴展選項和 ETag。
• d365fo_create_entity_record：創建新的實體記錄，並進行驗證和執行業務邏輯。
• d365fo_update_entity_record：使用部分更新和樂觀併發控制更新現有記錄。
• d365fo_delete_entity_record：刪除實體記錄，並進行引用完整性檢查和級聯規則處理。
• d365fo_call_action：執行 OData 操作和函數，以實現複雜的業務操作。
• d365fo_call_json_service：調用通用 JSON 服務端點，並支持參數和響應處理。

元數據發現工具（6 個）

• d365fo_search_entities：通過模式搜索實體，並支持類別過濾和全文搜索功能。
• d365fo_get_entity_schema：獲取詳細的實體架構，包括屬性、關係和標籤解析。
• d365fo_search_actions：搜索可用的 OData 操作，並提供綁定類型和參數信息。
• d365fo_search_enumerations：通過關鍵字過濾搜索系統枚舉。
• d365fo_get_enumeration_fields：獲取詳細的枚舉成員信息，並支持多語言。
• d365fo_get_installed_modules：檢索已安裝模塊及其配置的信息。

標籤管理工具（2 個）

• d365fo_get_label：通過 ID 獲取單個標籤文本，並支持多語言和回退選項。
• d365fo_get_labels_batch：通過批處理和性能優化高效獲取多個標籤。

配置文件管理工具（14 個）

• d365fo_list_profiles：列出所有配置的 D365FO 環境配置文件，並顯示狀態信息。
• d365fo_get_profile：獲取特定配置文件的詳細配置信息。
• d365fo_create_profile：創建新的環境配置文件，並提供全面的身份驗證選項。
• d365fo_update_profile：修改現有配置文件的配置，並支持部分更新。
• d365fo_delete_profile：刪除環境配置文件，並進行適當的清理和驗證。
• d365fo_set_default_profile：指定特定配置文件為操作的默認配置文件。
• d365fo_get_default_profile：檢索當前配置的默認配置文件的信息。
• d365fo_validate_profile：驗證配置文件的完整性和安全性合規性。
• d365fo_test_profile_connection：測試特定配置文件的連接性和身份驗證。
• d365fo_clone_profile：克隆現有配置文件，併為新環境提供自定義選項。
• d365fo_search_profiles：通過模式搜索配置文件，並支持過濾和排序功能。
• d365fo_get_profile_names：獲取可用配置文件名稱的簡化列表，以便快速參考。
• d365fo_import_profiles：從外部源或備份導入配置文件配置。
• d365fo_export_profiles：導出配置文件配置，用於備份或部署目的。

數據庫分析工具（4 個）

• d365fo_execute_sql_query：對元數據數據庫執行 SELECT 查詢，並進行安全驗證。
• d365fo_get_database_schema：獲取包括關係在內的全面數據庫架構信息。
• d365fo_get_table_info：獲取特定數據庫表的詳細信息，並提供示例數據。
• d365fo_get_database_statistics：生成數據庫統計信息和分析，用於性能監控。

同步工具（5 個）

• d365fo_start_sync：使用各種策略和會話跟蹤啟動元數據同步。
• d365fo_get_sync_progress：監控同步會話的詳細進度，並提供時間估計。
• d365fo_cancel_sync：取消正在運行的同步會話，並進行優雅清理。
• d365fo_list_sync_sessions：列出所有活動的同步會話，並顯示狀態和進度信息。
• d365fo_get_sync_history：獲取已完成同步會話的歷史記錄，包括成功/失敗狀態和統計信息。

SRS 報告工具（6 個）

• d365fo_download_srs_report：下載 SQL Server 報告服務（SRS）報告，並支持參數。
• d365fo_download_sales_confirmation：以各種格式下載銷售確認報告。
• d365fo_download_purchase_order：下載帶有格式選項的採購訂單文檔。
• d365fo_download_customer_invoice：下載自定義的客戶發票報告。
• d365fo_download_free_text_invoice：下載自由文本發票文檔。
• d365fo_download_debit_credit_note：下載借項和貸項通知單報告。

性能監控工具（3 個）

• d365fo_get_server_performance：獲取服務器性能指標和統計信息。
• d365fo_get_server_config：獲取服務器配置信息和系統設置。
• d365fo_reset_performance_stats：重置性能統計信息和計數器，以便重新進行監控。

📖 有關所有 MCP 工具的詳細信息，包括使用示例和最佳實踐，請參閱 綜合 MCP 工具介紹。

🤖 對於 AI 代理和助手，請參閱 AI 代理指南，以獲取結構化工作流、最佳實踐和自動化模式。

MCP 資源

服務器公開了四種類型的資源，用於發現和訪問：

實體資源

訪問實體元數據和示例數據：

d365fo://entities/CustomersV3     # 帶有元數據和示例數據的客戶實體
d365fo://entities/SalesOrders     # 銷售訂單實體信息
d365fo://entities/Products        # 產品實體詳細信息

元數據資源

訪問系統級元數據：

d365fo://metadata/entities        # 所有數據實體元數據（V2 緩存）
d365fo://metadata/actions         # 可用的 OData 操作
d365fo://metadata/enumerations    # 系統枚舉
d365fo://metadata/labels          # 系統標籤和翻譯

環境資源

訪問環境狀態和信息：

d365fo://environment/status       # 環境健康和連接性
d365fo://environment/version      # 版本信息（應用程序、平臺、構建）
d365fo://environment/cache        # 緩存狀態和統計信息 V2

查詢資源

訪問預定義和模板化的查詢：

d365fo://queries/customers_recent # 近期客戶查詢模板
d365fo://queries/sales_summary    # 帶有參數的銷售摘要查詢

數據庫資源（V2 新增）

訪問元數據數據庫查詢：

d365fo://database/entities        # 基於 SQL 的實體搜索，使用 FTS5
d365fo://database/actions         # 帶有元數據的操作發現
d365fo://database/statistics      # 緩存和性能統計信息

🔧 技術細節

Python 客戶端庫

特性

• 🔗 OData 客戶端：對 D365 F&O 數據實體進行完整的 CRUD 操作，並支持複合鍵。
• 📊 元數據管理 V2：增強的緩存系統，具有智能同步和 FTS5 搜索功能。
• 🏷️ 標籤操作 V2：多語言標籤緩存，性能提升並支持異步操作。
• 🔍 高級查詢：支持所有 OData 查詢參數（$select、$filter、$expand 等）。
• ⚡ 操作執行：執行綁定和未綁定的 OData 操作，並進行全面的參數處理。
• 📡 JSON 服務：通用訪問 D365 F&O JSON 服務端點（/api/services 模式）。
• 🔒 身份驗證：與 Azure AD 集成，支持默認憑證、服務主體和 Azure Key Vault。
• 💾 智能緩存：跨環境緩存共享，支持基於模塊的版本檢測。
• 🌐 異步/等待：採用現代的異步/等待模式，優化會話管理。
• 📝 類型提示：全面支持類型註解，增強數據模型。
• 🤖 MCP 服務器：生產就緒的模型上下文協議服務器，提供 49 個工具和 4 種資源類型。
• 🖥️ 綜合 CLI：為所有 D365 F&O 操作提供分層命令行界面。
• 🧪 多層測試：模擬、沙盒和即時集成測試框架（17/17 測試通過）。
• 📋 元數據腳本：用於實體、枚舉和操作發現的 PowerShell 和 Python 實用程序。
• 🔐 增強的憑證管理：支持 Azure Key Vault 和多個憑證源。
• 📊 高級同步管理：基於會話的同步，提供詳細的進度跟蹤。
• 🔧 NEW v0.3.0：Pydantic 設置模型，對環境變量進行類型安全的驗證。
• 📂 NEW v0.3.0：支持自定義日誌文件路徑和靈活的日誌配置。
• 🔄 NEW v0.3.0：自動遷移舊配置並提供兼容性層。

安裝

# 從 PyPI 安裝
pip install d365fo-client

# 或者從源代碼安裝
git clone https://github.com/mafzaal/d365fo-client.git
cd d365fo-client
uv sync  # 使用 uv.lock 中的精確依賴項進行安裝

# 或者使用 Docker（無需本地安裝）
docker pull ghcr.io/mafzaal/d365fo-client:latest

# 使用 Docker 運行
docker run --rm -it \
  -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" \
  -v d365fo-mcp:/home/mcp_user/ \
  ghcr.io/mafzaal/d365fo-client:latest

注意：該軟件包默認包含 MCP（模型上下文協議）依賴項，可實現 AI 助手集成。安裝後，d365fo-client CLI 和 d365fo-fastmcp-server 命令將可用。

v0.2.3 版本的重大變更：環境變量名稱已更新以保持一致性：

• AZURE_CLIENT_ID → D365FO_CLIENT_ID
• AZURE_CLIENT_SECRET → D365FO_CLIENT_SECRET
• AZURE_TENANT_ID → D365FO_TENANT_ID 升級時請相應更新你的環境變量。

Python 客戶端快速入門

命令行界面（CLI）

d365fo-client 提供了一個全面的 CLI，具有分層命令，用於與 Dynamics 365 Finance & Operations API 和元數據進行交互。該 CLI 支持所有主要操作，包括實體管理、元數據發現和系統管理。

使用方法

# 使用已安裝的 CLI 命令
d365fo-client [全局選項] 命令 [子命令] [選項]

# 替代方法：模塊執行
python -m d365fo_client.main [選項] 命令 [參數]

命令類別

實體操作

# 列出實體並進行過濾
d365fo-client entities list --pattern "customer" --limit 10

# 獲取實體詳細信息和架構
d365fo-client entities get CustomersV3 --properties --keys --labels

# CRUD 操作
d365fo-client entities create Customers --data '{"CustomerAccount":"US-999","Name":"Test"}'
d365fo-client entities update Customers US-999 --data '{"Name":"Updated Name"}'
d365fo-client entities delete Customers US-999

元數據操作

# 搜索和發現實體
d365fo-client metadata entities --search "sales" --output json

# 獲取可用操作
d365fo-client metadata actions --pattern "calculate" --limit 5

# 枚舉系統枚舉
d365fo-client metadata enums --search "status" --output table

# 同步元數據緩存
d365fo-client metadata sync --force-refresh

版本信息

# 獲取應用程序版本
d365fo-client version app
d365fo-client version platform
d365fo-client version build

標籤操作

# 解析單個標籤
d365fo-client labels resolve "@SYS13342"

# 按模式搜索標籤
d365fo-client labels search "customer" --language "en-US"

JSON 服務操作

# 調用 SQL 診斷服務
d365fo-client service sql-diagnostic GetAxSqlExecuting
d365fo-client service sql-diagnostic GetAxSqlResourceStats --since-minutes 5
d365fo-client service sql-diagnostic GetAxSqlBlocking --output json

# 通用 JSON 服務調用
d365fo-client service call SysSqlDiagnosticService SysSqlDiagnosticServiceOperations GetAxSqlExecuting
d365fo-client service call YourServiceGroup YourServiceName YourOperation --parameters '{"param1":"value1"}'

全局選項

• --base-url URL — 指定 D365 F&O 環境 URL
• --profile NAME — 使用命名配置文件
• --output FORMAT — 輸出格式：json、table、csv、yaml（默認：table）
• --verbose — 啟用詳細輸出以進行調試
• --timeout SECONDS — 請求超時時間（默認：30）

配置文件

在 ~/.d365fo-client/config.yaml 中創建可重用的配置：

profiles:
  production:
    base_url: "https://prod.dynamics.com"
    use_default_credentials: true
    timeout: 60

  development:
    base_url: "https://dev.dynamics.com" 
    client_id: "${D365FO_CLIENT_ID}"
    client_secret: "${D365FO_CLIENT_SECRET}"
    tenant_id: "${D365FO_TENANT_ID}"
    use_cache_first: true

default_profile: "development"

示例

# 快速實體發現
d365fo-client entities list --pattern "cust.*" --output json

# 獲取全面的實體信息
d365fo-client entities get CustomersV3 --properties --keys --labels --output yaml

# 搜索計算操作
d365fo-client metadata actions --pattern "calculate|compute" --output table

# 測試環境連接性
d365fo-client version app --verbose

如需完整的命令參考：

d365fo-client --help
d365fo-client entities --help
d365fo-client metadata --help

基本用法

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("✅ 連接成功！")

        # 獲取環境信息
        env_info = await client.get_environment_info()
        print(f"環境：{env_info.application_version}")

        # 搜索實體（使用元數據緩存 v2）
        customer_entities = await client.search_entities("customer")
        print(f"找到 {len(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"檢索到 {len(customers['value'])} 個客戶")

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)

配置

環境變量管理（v0.3.0 新增）

d365fo-client 現在包含一個全面的Pydantic 設置模型，用於類型安全的環境變量管理：

from d365fo_client import D365FOSettings, get_settings

# 獲取類型安全的設置實例
settings = get_settings()

# 使用完整的智能感知功能訪問設置
print(f"基礎 URL：{settings.base_url}")
print(f"日誌級別：{settings.log_level}")
print(f"緩存目錄：{settings.cache_dir}")

# 檢查配置狀態
if settings.has_client_credentials():
    print("已配置客戶端憑證")

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

# 轉換為環境字典，供外部工具使用
env_vars = settings.to_env_dict()

主要優勢：

• 類型安全：對所有 35 多個環境變量進行自動驗證和類型轉換。
• IDE 支持：為配置選項提供完整的智能感知和自動完成功能。
• 環境文件：在開發環境中支持 .env 文件。
• 全面的默認值：為所有配置選項提供合理的默認值。
• 驗證：對 URL、端口、超時時間和其他設置進行內置驗證。

身份驗證選項

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  # 緩存 2 小時
)

舊配置遷移（v0.3.0 新增）

d365fo-client 會自動檢測並遷移舊的配置文件：

• 自動檢測：識別舊的配置模式（缺少 verify_ssl、過時的字段名稱）。
• 字段遷移：將 cache_dir 更新為 metadata_cache_dir，將 auth_mode 更新為 use_default_credentials。
• 備份創建：在遷移前創建原始配置的備份。
• 無縫升級：確保從舊版本順利過渡，無需手動干預。

# 啟動 FastMCP 服務器時，舊配置會自動遷移
# 無需手動干預 - 遷移過程透明進行

核心操作

CRUD 操作

async with D365FOClient(config) as client:
    # 創建 - 創建新客戶（支持複合鍵）
    new_customer = {
        "CustomerAccount": "US-999",
        "Name": "Test Customer",
        "SalesCurrencyCode": "USD"
    }
    created = await client.create_data("/data/CustomersV3", new_customer)

    # 讀取 - 通過鍵獲取單個客戶
    customer = await client.get_data("/data/CustomersV3('US-001')")

    # 更新 - 使用樂觀併發更新客戶
    updates = {"Name": "Updated Customer Name"}
    updated = await client.update_data("/data/CustomersV3('US-001')", updates)

    # 刪除 - 刪除客戶
    success = await client.delete_data("/data/CustomersV3('US-999')")
    print(f"刪除成功：{success}")

高級查詢

from d365fo_client import QueryOptions

# 具有多個選項的複雜查詢
options = QueryOptions(
    select=["CustomerAccount", "Name", "SalesCurrencyCode", "CustomerGroupId"],
    filter="SalesCurrencyCode eq 'USD' and contains(Name, 'Corp')",
    expand=["CustomerGroup"],
    orderby=["Name desc", "CustomerAccount"],
    top=50,
    skip=10,
    count=True
)

result = await client.get_data("/data/CustomersV3", options)
print(f"總計數：{result.get('@odata.count')}")

操作執行

# 未綁定操作
result = await client.post_data("/data/calculateTax", {
    "amount": 1000.00,
    "taxGroup": "STANDARD"
})

# 實體集上的綁定操作
result = await client.post_data("/data/CustomersV3/calculateBalances", {
    "asOfDate": "2024-12-31"
})

# 特定實體實例上的綁定操作
result = await client.post_data("/data/CustomersV3('US-001')/calculateBalance", {
    "asOfDate": "2024-12-31"
})

JSON 服務操作

# 基本 JSON 服務調用（無參數）
response = await client.post_json_service(
    service_group="SysSqlDiagnosticService",
    service_name="SysSqlDiagnosticServiceOperations",
    operation_name="GetAxSqlExecuting"
)

if response.success:
    print(f"找到 {len(response.data)} 條正在執行的 SQL 語句")
    print(f"狀態：HTTP {response.status_code}")
else:
    print(f"錯誤：{response.error_message}")

# 帶有參數的 JSON 服務調用
from datetime import datetime, timezone, timedelta

end_time = datetime.now(timezone.utc)
start_time = end_time - timedelta(minutes=10)

response = await client.post_json_service(
    service_group="SysSqlDiagnosticService",
    service_name="SysSqlDiagnosticServiceOperations",
    operation_name="GetAxSqlResourceStats",
    parameters={
        "start": start_time.isoformat(),
        "end": end_time.isoformat()
    }
)

# 使用 JsonServiceRequest 對象以獲得更好的結構
from d365fo_client.models import JsonServiceRequest

request = JsonServiceRequest(
    service_group="SysSqlDiagnosticService",
    service_name="SysSqlDiagnosticServiceOperations",
    operation_name="GetAxSqlBlocking"
)

response = await client.call_json_service(request)
print(f"服務端點：{request.get_endpoint_path()}")

# 多個 SQL 診斷操作
operations = ["GetAxSqlExecuting", "GetAxSqlBlocking", "GetAxSqlLockInfo"]
for operation in operations:
    response = await client.post_json_service(
        service_group="SysSqlDiagnosticService",
        service_name="SysSqlDiagnosticServiceOperations",
        operation_name=operation
    )

    if response.success:
        count = len(response.data) if isinstance(response.data, list) else 1
        print(f"{operation}：{count} 條記錄")

# 自定義服務調用模板
response = await client.post_json_service(
    service_group="YourServiceGroup",
    service_name="YourServiceName",
    operation_name="YourOperation",
    parameters={
        "parameter1": "value1",
        "parameter2": 123,
        "parameter3": True
    }
)

元數據操作

# 智能元數據同步（v2 系統）
sync_manager = await client.get_sync_manager()
await sync_manager.smart_sync()

# 帶有增強過濾的實體搜索
sales_entities = await client.search_entities("sales")
print("與銷售相關的實體：", [e.name for e in sales_entities])

# 獲取帶有標籤的詳細實體信息
entity_info = await client.get_public_entity_info("CustomersV3")
if entity_info:
    print(f"實體：{entity_info.name}")
    print(f"標籤：{entity_info.label_text}")
    print(f"數據服務啟用：{entity_info.data_service_enabled}")

# 帶有緩存的操作搜索
calc_actions = await client.search_actions("calculate")
print("計算操作：", [a.name for a in calc_actions])

# 獲取枚舉信息
enum_info = await client.get_public_enumeration_info("NoYes")
if enum_info:
    print(f"枚舉：{enum_info.name}")
    for member in enum_info.members:
        print(f"  {member.name} = {member.value}")

標籤操作

# 獲取特定標籤（v2 緩存系統）
label_text = await client.get_label_text("@SYS13342")
print(f"標籤文本：{label_text}")

# 高效獲取多個標籤
labels = await client.get_labels_batch([
    "@SYS13342", "@SYS9490", "@GLS63332"
])
for label_id, text in labels.items():
    print(f"{label_id}：{text}")

# 帶有解析標籤的增強實體信息
entity_info = await client.get_public_entity_info_with_labels("CustomersV3")
if entity_info.label_text:
    print(f"實體顯示名稱：{entity_info.label_text}")

# 訪問帶有標籤的增強屬性
for prop in entity_info.enhanced_properties[:5]:
    if hasattr(prop, 'label_text') and prop.label_text:
        print(f"{prop.name}：{prop.label_text}")

錯誤處理

from d365fo_client import D365FOClientError, AuthenticationError, ConnectionError

try:
    async with D365FOClient(config) as client:
        customer = await client.get_data("/data/CustomersV3('NON-EXISTENT')")
except ConnectionError as e:
    print(f"連接失敗：{e}")
except AuthenticationError as e:
    print(f"身份驗證失敗：{e}")
except D365FOClientError as e:
    print(f"客戶端操作失敗：{e}")
    print(f"狀態碼：{e.status_code}")
    print(f"響應：{e.response_text}")

開發

設置開發環境

# 克隆倉庫
git clone https://github.com/mafzaal/d365fo-client.git
cd d365fo-client

# 使用 uv 安裝開發依賴項
uv sync --dev

# 運行測試
uv run pytest

# 運行集成測試
.\tests\integration\integration-test-simple.ps1 test-sandbox

# 格式化代碼
uv run black .
uv run isort .

# 類型檢查
uv run mypy src/

# 質量檢查
.\make.ps1 quality-check  # Windows PowerShell
# 或者
make quality-check       # Unix/Linux/macOS

項目結構

d365fo-client/
├── src/
│   └── d365fo_client/
│       ├── __init__.py          # 公共 API 導出
│       ├── main.py              # CLI 入口點
│       ├── cli.py               # CLI 命令處理程序
│       ├── client.py            # 增強的 D365FOClient 類
│       ├── config.py            # 配置管理
│       ├── auth.py              # 身份驗證管理
│       ├── session.py           # HTTP 會話管理
│       ├── crud.py              # CRUD 操作
│       ├── query.py             # OData 查詢實用程序
│       ├── metadata.py          # 舊的元數據操作
│       ├── metadata_api.py      # 元數據 API 客戶端
│       ├── metadata_cache.py    # 元數據緩存層 V2
│       ├── metadata_sync.py     # 元數據同步 V2，帶有會話管理
│       ├── sync_session.py      # 增強的同步會話管理（v0.2.3 新增）
│       ├── credential_manager.py # 憑證源管理（v0.2.3 新增）
│       ├── labels.py            # 標籤操作 V2
│       ├── profiles.py          # 配置文件數據模型
│       ├── profile_manager.py   # 配置文件管理
│       ├── models.py            # 數據模型和配置
│       ├── output.py            # 輸出格式化
│       ├── utils.py             # 實用函數
│       ├── exceptions.py        # 自定義異常
│       └── mcp/                 # 模型上下文協議服務器
│           ├── __init__.py      # MCP 服務器導出
│           ├── main.py          # MCP 服務器入口點
│           ├── server.py        # 核心 MCP 服務器實現
│           ├── client_manager.py# D365FO 客戶端連接池
│           ├── models.py        # MCP 特定的數據模型
│           ├── mixins/          # FastMCP 工具混合類（49 個工具）
│           ├── tools/           # 舊的 MCP 工具（已棄用）
│           │   ├── connection_tools.py
│           │   ├── crud_tools.py
│           │   ├── metadata_tools.py
│           │   └── label_tools.py
│           ├── resources/       # MCP 資源處理程序（4 種類型）
│           │   ├── entity_handler.py
│           │   ├── metadata_handler.py
│           │   ├── environment_handler.py
│           │   └── query_handler.py
│           └── prompts/         # MCP 提示模板
├── tests/                       # 全面的測試套件
│   ├── unit/                    # 單元測試（基於 pytest）
│   ├── integration/             # 多層集成測試
│   │   ├── mock_server/         # 模擬 D365 F&O API 服務器
│   │   ├── test_mock_server.py  # 模擬服務器測試
│   │   ├── test_s