Business Central MCP Agent

使用Microsoft Agent Framework（Semantic Kernel ChatCompletionAgent）的Python代理，直接连接到Business Central。

✨ 特性

• 直接连接 - 不需要exe文件！直接连接到Business Central MCP HTTP端点
• 跨平台 - 支持Windows、macOS和Linux
• 灵活的身份验证 - 支持设备代码流（委托）和客户端凭据（应用程序）
• Microsoft Agent Framework - 使用Semantic Kernel ChatCompletionAgent模式

快速开始

1. 安装依赖项：

pip install -r requirements.txt

2. 配置 BusinessCentralMCP.env：

# Azure OpenAI
AZURE_OPENAI_API_KEY=your_key
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
AZURE_OPENAI_CHAT_DEPLOYMENT_NAME=gpt-4o

# Business Central
BC_TENANT_ID=your_tenant_id
BC_CLIENT_ID=your_client_id
# BC_CLIENT_SECRET=your_secret  # 可选 - 用于服务主体身份验证
BC_ENVIRONMENT_NAME=Production
BC_COMPANY_NAME=CRONUS International Ltd.

3. 运行：

python bc_direct_agent.py

身份验证选项：

• 设备代码流（默认）：交互式浏览器身份验证 - 代理提示您访问一个URL并输入一个代码
• 客户端凭据流：添加BC_CLIENT_SECRET以使用服务主体身份验证（无需用户交互）

架构

此实现遵循Microsoft Agent Framework模式：

用户问题
    ↓
ChatCompletionAgent (Semantic Kernel)
    ↓
BusinessCentralMCPPlugin (@kernel_function装饰器)
    ↓
MCP客户端会话(stdio_client)
    ↓
BcMCPProxy.exe (MCP服务器)
    ↓
Business Central API

关键组件

1. Semantic Kernel内核 - 核心框架
2. ChatCompletionAgent - 来自semantic_kernel.agents的代理
3. BusinessCentralMCPPlugin - 带有@kernel_function装饰器的插件
4. FunctionChoiceBehavior.Auto() - 启用自动函数调用
5. MCP客户端会话 - 通过stdio连接到BC MCP服务器

先决条件

1. Business Central MCP服务器（BcMCPProxy.exe）

   • 下载/构建自：https://github.com/microsoft/BCTech/tree/master/samples/BcMCPProxy
   • 将BcMCPProxy.exe放置在此目录或在.env中更新路径

2. Azure AD应用注册

   • 在Azure门户创建应用注册
   • 添加重定向URL：ms-appx-web://Microsoft.AAD.BrokerPlugin/<clientID>
   • 添加API权限：
     • Financials.ReadWrite.All（委托）
     • user_impersonation（委托）

3. Python 3.10+

4. Azure OpenAI或OpenAI API密钥

安装

1. 克隆此仓库：

git clone <repository-url>
cd BusinessCentralMCPserver

2. 安装依赖项：

pip install -r requirements.txt

3. 配置环境变量：
   • 编辑BusinessCentralMCP.env并填写您的值：
     • Azure OpenAI凭证
     • BC MCP服务器路径
     • Azure租户/客户端ID
     • BC环境和公司名称

配置

编辑BusinessCentralMCP.env：

# Azure OpenAI
AZURE_OPENAI_API_KEY=your_key_here
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
AZURE_OPENAI_CHAT_DEPLOYMENT_NAME=your_deployment
AZURE_OPENAI_API_VERSION=2_2024-08-01-preview

# Business Central MCP服务器
BC_MCP_SERVER_PATH=BcMCPProxy.exe
BC_TENANT_ID=your_tenant_id
BC_CLIENT_ID=your_client_id
BC_ENVIRONMENT_NAME=production
BC_COMPANY_NAME=CRONUS International Ltd.
BC_CONFIG_NAME=default

使用

运行代理：

python bc_mcp_agent.py

代理将：

1. 初始化Semantic Kernel
2. 连接到BC MCP服务器
3. 发现可用的BC工具
4. 开始交互式聊天会话

示例交互

> 有哪些可用的工具？
[代理列出所有BC MCP工具]

> 显示客户信息
[代理调用适当的BC工具并显示结果]

> 列出最近的销售订单
[代理查询BC并格式化响应]

工作原理

Microsoft Agent Framework模式

此实现使用与Semantic-Kernel-PlantRequestAgent参考中的完全相同模式：

1. 内核设置

   kernel = Kernel()
   add_chat_service(kernel)  # Azure OpenAI或OpenAI
   

2. 插件创建

   class BusinessCentralMCPPlugin:
       @kernel_function(description="...", name="...")
       async def call_bc_tool(self, tool_name: str, arguments: str) -> str:
           # 调用MCP服务器
   

3. 插件注册

   kernel.add_plugin(bc_plugin, plugin_name="business_central")
   

4. 代理创建

   agent = ChatCompletionAgent(
       name="BusinessCentralAgent",
       instructions=system_prompt,
       kernel=kernel,
       function_choice_behavior=FunctionChoiceBehavior.Auto()
   )
   

5. 交互循环

   async for response_item in agent.invoke(user_input):
       print(response_item.content, end="")
   

MCP连接

代理通过stdio（标准输入/输出）连接到BcMCPProxy.exe：

async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        # 使用会话调用工具

与PlantRequestAgent的区别

PlantRequestAgent直接对Business Central进行HTTP API调用：

async with httpx.AsyncClient() as client:
    response = await client.get(url, headers=headers)

而这个BC MCP代理通过MCP服务器连接：

result = await session.call_tool(tool_name, arguments=args_dict)

MCP方法的优点：

• 抽象的身份验证（由MCP服务器处理）
• 简化的API访问
• 与其他MCP客户端兼容（Claude Desktop，VS Code）
• 中央化的BC访问逻辑

故障排除

MCP服务器未找到

❌ 错误：BC MCP服务器未在以下位置找到：BcMCPProxy.exe

解决方案：在.env中更新BC_MCP_SERVER_PATH为BcMCPProxy.exe的完整路径

身份验证错误

❌ 连接到BC MCP服务器时出错：...

解决方案：

1. 检查Azure AD应用注册
2. 验证重定向URL格式
3. 确保已授予API权限
4. 确认租户/客户端ID正确

连接超时

解决方案：

1. 验证BC环境名称是否正确
2. 检查公司名称（区分大小写）
3. 测试到BC的网络连接

参考资料

• BcMCPProxy：https://github.com/microsoft/BCTech/tree/master/samples/BcMCPProxy
• MCP协议：https://modelcontextprotocol.io/
• Semantic Kernel：https://learn.microsoft.com/en-us/semantic-kernel/
• Microsoft Agent Framework：Semantic Kernel ChatCompletionAgent的组合

许可证

MIT许可证