Fo Semantic MCP

🚀 FO語義MCP服務器

本服務器是用於Microsoft Dynamics 365 Finance & Operations開發的模型上下文協議（MCP）服務器，它能為你的AI編碼助手注入深厚的F&O知識。藉助此MCP服務器，Cursor IDE、Claude Desktop和VS Code中的AI代理可以搜索50,000多個F&O工件，讀取本地源代碼，併為你的開發任務找到相關示例。

🚀 快速開始

1. 前提條件

確保你已安裝 Node.js：

• 下載地址：https://nodejs.org/
• 最低版本要求：Node.js 18+

2. 獲取API密鑰

從 https://www.xplusplus.ai/ 獲取你的API密鑰。你可以訪問我們的網站查看可用的計劃和定價。

3. 安裝

選擇最適合你的安裝方法：

選項A：使用npx（推薦 - 始終使用最新版本）

無需安裝！啟動MCP客戶端時，它將自動獲取最新版本。

Cursor IDE (~/.cursor/mcp.json 或 %USERPROFILE%\.cursor\mcp.json)：

{
  "mcpServers": {
    "fo-semantic-mcp": {
      "command": "npx",
      "args": ["-y", "fo-semantic-mcp"],
      "env": {
        "FOINDEX_API_KEY": "your_api_key_here",
        "FO_LOCAL_ASSETS_PATH": "C:\\Users\\YourName\\AppData\\Local\\Microsoft\\Dynamics365\\10.0.xxxx\\PackagesLocalDirectory"
      }
    }
  }
}

Claude Desktop（Windows系統下的 ~/AppData/Roaming/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "fo-semantic-mcp": {
      "command": "npx",
      "args": ["-y", "fo-semantic-mcp"],
      "env": {
        "FOINDEX_API_KEY": "your_api_key_here",
        "FO_LOCAL_ASSETS_PATH": "C:\\Users\\YourName\\AppData\\Local\\Microsoft\\Dynamics365\\10.0.xxxx\\PackagesLocalDirectory"
      }
    }
  }
}

VS Code（配置與Cursor IDE類似）

使用npx的好處：

• ✅ 無需安裝
• ✅ 自動使用最新版本
• ✅ 無需手動更新
• ✅ 支持Windows、macOS和Linux系統

macOS/Linux用戶：路徑中使用正斜槓：

{
  "env": {
    "FOINDEX_API_KEY": "your_api_key_here",
    "FO_LOCAL_ASSETS_PATH": "/Users/yourname/.local/Microsoft/Dynamics365/10.0.xxxx/PackagesLocalDirectory"
  }
}

選項B：全局安裝

在系統中全局安裝該軟件包：

npm install -g fo-semantic-mcp

然後配置你的MCP客戶端：

Cursor IDE / Claude Desktop / VS Code：

{
  "mcpServers": {
    "fo-semantic-mcp": {
      "command": "fo-semantic-mcp",
      "env": {
        "FOINDEX_API_KEY": "your_api_key_here",
        "FO_LOCAL_ASSETS_PATH": "C:\\Users\\YourName\\AppData\\Local\\Microsoft\\Dynamics365\\10.0.xxxx\\PackagesLocalDirectory"
      }
    }
  }
}

何時使用全局安裝：

• 你希望固定使用特定版本
• 你的網絡連接受限
• 你更喜歡顯式的版本控制

更新方法：

npm update -g fo-semantic-mcp

選項C：從GitHub版本手動安裝

從本地目錄下載並運行：

1. 從GitHub下載 最新版本。
2. 解壓到你喜歡的位置（例如 C:\tools\fo-semantic-mcp）。
3. 在解壓後的文件夾中運行 npm install。

然後使用完整路徑進行配置：

{
  "mcpServers": {
    "fo-semantic-mcp": {
      "command": "node",
      "args": ["C:\\tools\\fo-semantic-mcp\\dist\\server.js"],
      "env": {
        "FOINDEX_API_KEY": "your_api_key_here",
        "FO_LOCAL_ASSETS_PATH": "C:\\Users\\YourName\\AppData\\Local\\Microsoft\\Dynamics365\\10.0.xxxx\\PackagesLocalDirectory"
      }
    }
  }
}

macOS/Linux 路徑使用正斜槓：/path/to/fo-semantic-mcp/dist/server.js

何時使用手動安裝：

• 你希望完全控制安裝位置
• 你正在開發或自定義服務器
• 你的環境限制了npm包的執行

4. 重啟AI客戶端

完全重啟Cursor IDE、Claude Desktop或VS Code以加載MCP服務器。

✨ 主要特性

✅ 語義搜索 - 使用自然語言查找F&O工件。 ✅ 50,000多個工件 - 包含表、表單、類、擴展數據類型（EDT）、枚舉、數據實體、視圖、查詢等。 ✅ AI描述 - 無需閱讀XML即可理解工件的用途。 ✅ 本地文件訪問 - 讀取實際的F&O XML文件以進行全面分析。 ✅ 豐富的元數據 - 涵蓋業務領域、模塊、配置鍵、使用上下文等信息。 ✅ 多平臺支持 - 在安裝了Node.js的Windows、macOS和Linux系統上均可運行。 ✅ MCP兼容 - 可與Cursor IDE、Claude Desktop和VS Code配合使用。

🎯 適用人群

• F&O開發人員：構建擴展和自定義功能。
• 顧問：學習現有的實現方案。
• 架構師：瞭解系統模式。
• 團隊：加速開發週期。

🔧 包含內容

MCP工具：search_FO_artifacts

對Microsoft D365 F&O標準工件進行語義搜索。返回的工件元數據包括：

• 工件名稱、類型和模塊。
• AI生成的描述和使用上下文。
• 業務領域分類。
• 本地文件路徑（如果已配置）。

MCP提示：fo-development-assistant（僅適用於Claude Desktop）

這是一個完整的6步F&O自定義開發工作流程：

1. 搜索標準D365工件。
2. 讀取標準實現。
3. 在你的工作區中搜索自定義代碼。
4. 讀取你的自定義內容。
5. 生成上下文感知的解決方案。
6. 呈現全面的分析。

注意：該提示工作流程需要用戶手動調用，並且僅在Claude Desktop中可用。在Cursor IDE中，你可以手動引導AI完成類似的步驟。

💻 使用示例

基本搜索

"Find customer tables in D365"
"Show me sales order forms"
"Search for pricing calculation classes"
"Find inventory transaction data entities"

工件類型過濾

你可以按工件類型進行過濾，以獲得更精準的結果：

• 表
• 表單
• 類
• 擴展數據類型（EDT）
• 枚舉
• 數據實體
• 視圖
• 查詢

高級查詢

"Find all tables related to inventory management"
"Show me forms that use the CustTable datasource"
"Search for classes that implement pricing logic"
"Find data entities for financial reporting"

在Claude Desktop中使用

使用 fo-development-assistant 提示來引導F&O開發工作流程。只需輸入 /fo-development-assistant 即可激活結構化工作流程。

在Cursor IDE和VS Code中使用

讓你的AI助手搜索F&O工件，然後引導它完成以下工作流程：

1. 搜索標準D365實現。
2. 讀取源文件以瞭解模式。
3. 在你的工作區中搜索現有的自定義內容。
4. 結合各種信息生成上下文感知的解決方案。

🎬 即時演示

親眼見證它的實際效果！ 查看我們的 即時演示，展示了AI代理如何使用MCP服務器完成完整的D365 F&O自定義任務 - 從自然語言請求到生成可用代碼。

任務：“在供應商組表中創建一個新字段 'External name' 並將其添加到表單的常規選項卡中”

你將看到：

• AI使用語義搜索查找D365工件。
• 通過文件路徑讀取標準實現。
• 檢查工作區中是否存在現有的自定義內容。
• 生成完整的表和表單擴展。
• 所有操作都在一個會話中完成，並遵循正確的D365模式。

👉 查看完整演示

🔧 故障排除

工具未加載

症狀：MCP服務器已在客戶端中顯示，但工具未出現。

解決方案：

1. 驗證 FOINDEX_API_KEY 是否設置正確（JSON中不要加引號，不要有多餘空格）。
2. 完全重啟你的AI客戶端（不僅僅是重新加載窗口）。
3. 檢查客戶端開發者控制檯中的MCP服務器日誌。
4. 直接在終端中使用 npx fo-semantic-mcp 進行測試，以驗證安裝情況。

超時錯誤

症狀：出現 “Request timeout” 或 “Connection refused” 錯誤。

解決方案：

1. 驗證與 https://search.xplusplus.ai 的網絡連接是否正常。
2. 增加超時時間："FO_SEARCH_TIMEOUT_MS": "30000"（30秒）。
3. 檢查防火牆或代理是否阻止了連接。
4. 嘗試使用不同的網絡（企業防火牆可能會阻止外部API）。

本地文件讀取失敗

症狀：可以搜索工件，但無法讀取XML源文件。

解決方案：

1. 驗證 FO_LOCAL_ASSETS_PATH 是否指向正確的目錄。
2. 確保路徑存在且可訪問。
3. 在Windows系統中，使用雙反斜槓："C:\\Users\\..."。
4. 檢查PackagesLocalDirectory的文件權限。
5. 更新路徑後重啟AI客戶端。

npx命令失敗

症狀：出現 “npx: command not found” 或npm錯誤。

解決方案：

1. 確保已安裝Node.js 18+：node --version。
2. 確保已安裝npm：npm --version。
3. 更新npm：npm install -g npm@latest。
4. 嘗試使用全局安裝方法（上述選項B）。

特定版本問題

查看已安裝版本：

# 全局安裝
npm list -g fo-semantic-mcp

# npx（顯示最新可用版本）
npm view fo-semantic-mcp version

使用npx強制指定版本：

{
  "command": "npx",
  "args": ["-y", "fo-semantic-mcp@2.0.7"]
}

📖 v2.0.7版本新增內容

最新修復

• ✅ MCP STDIO協議合規性 - 修復了Claude Desktop中的初始化超時問題。
• ✅ MCP註冊表發佈 - 現在可在官方MCP目錄（registry.modelcontextprotocol.io）中找到。
• ✅ npm安裝支持 - 可以通過 npm install -g 進行安裝，也可以直接使用 npx。
• ✅ 字符編碼修復 - 提示和響應顯示清晰。
• ✅ 日誌記錄改進 - 所有日誌都使用STDERR，以符合正確的MCP協議。

之前v2.0版本的改進

• ✅ 簡化架構 - 工具文檔簡潔，響應清晰。
• ✅ 單一提示 - 有一個清晰的 fo-development-assistant 提示。
• ✅ 標準TypeScript構建 - 去除了混淆，提高了透明度。
• ✅ 生產就緒包 - 僅包含必要的運行時文件。
• ✅ 更好的MCP對齊 - 遵循正確的MCP架構模式。

從早期版本遷移

從v1.x版本遷移：

• 無重大API變更。
• 更新安裝並重啟AI客戶端。
• 配置格式兼容。

從v2.0.0 - 2.0.6版本遷移：

• 使用npx方法進行最簡單的更新。
• 更新配置以使用 npx 命令（推薦）。
• 重啟AI客戶端以加載新版本。

🆘 支持

• 問題反饋：在 GitHub Issues 上報告錯誤和提出功能請求。
• 文檔：查看 入門指南。
• 企業支持：聯繫 contact@xplusplus.ai 獲取定製解決方案和企業支持。
• 社區交流：在GitHub上參與討論。

📄 許可證

本軟件僅供商業使用。詳情請參閱 LICENSE 文件。

🚀 關於FO-Index

本項目由 FO-Index 團隊開發，FO-Index是一個全面的Microsoft Dynamics 365 Finance & Operations開發知識庫。

我們的使命：通過AI使Microsoft龐大的標準工件庫可搜索和可理解，從而加速D365 F&O開發。

準備好提升你的F&O開發效率了嗎？ 獲取你的API密鑰，立即開始！ 🎯