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密钥，立即开始！ 🎯