内容
align="center">
<img src="assets/PMATS_Alex_Logo_Transparent_700x513.png" alt="Alex Logo" width="350">
</p>
# Alex MCP 代理
MCP 代理客户端，用于连接 GitHub Copilot 和 Claude Desktop 到 Alex，即 Business Central AL 代码助手。
## 🎯 什么是 Alex？
Alex 是一款专门针对微软 Dynamics 365 Business Central AL AI 助手。它帮助您更高效地理解、调试和开发 AL 代码。
**🔗 链接：**
- **Web 应用**: [https://alex.app.pmats.ai](https://alex.app.pmats.ai)
- **文档**: [https://alex.app.pmats.ai/docs/](https://alex.app.pmats.ai/docs/)
本指南向您展示如何在 **GitHub Copilot** （VS Code）或 **Claude Desktop** 中安装 Alex MCP 代理。
## 🤔 什么是 MCP？
**MCP（模型上下文协议）** 是一种开放标准，允许 GitHub Copilot 或 Claude Desktop 等 AI 助手连接到外部知识源和工具。
可以将 MCP 视为一个**通用插件**，让您的 AI 助手可以访问专业知识库、API 或服务。AI 助手除了依赖其训练数据外，还可以从外部源获取实时、准确的信息。
**在 Alex 的情况下：**
- 您的 AI 助手（Copilot 或 Claude）询问有关 Business Central 的问题
- MCP 代理将请求转发到 Alex 后端
- Alex 搜索其 Business Central AL 代码知识库
- 答案返回给您的 AI 助手
- 您获得有关 Business Central AL 代码的准确、最新信息
**好处：**
- ✅ **专业知识** - Alex 深入了解 Business Central AL 代码
- ✅ **始终保持最新** - 信息来自最新的 BC 版本
- ✅ **版本比较** - 比较不同 BC 版本（26、27 等）的代码
- ✅ **安全** - 您的 API 密钥保护您的查询隐私
## 🔧 可用的 MCP 工具
Alex 为 AI 助手公开了两个 MCP 工具：
### `alex_al_query`
**用途：** 查询 Business Central AL 代码知识库
**输入模式：**
```json
{
"request": "string (required)"
}
```
**用法：**
- 回答有关 Business Central AL 代码的问题
- 解释表、代码单元、页面如何工作
- 提供代码示例和最佳实践
- 搜索特定的 AL 对象或过程
**示例：**
- `{"request": "Business Central 中的 Customer 表如何工作？"}`
- `{"request": "显示一个发布销售订单的代码单元示例"}`
- `{"request": "Sales Header 表中有哪些事件？"}`
### `alex_al_comparison`
**用途：** 比较不同版本的 Business Central AL 代码
**输入模式：**
```json
{
"request": "string (required)"
}
```
**用法：**
- 比较不同 BC 版本（例如 v26 和 v27）之间的 AL 对象
- 确定版本之间的重大更改
- 发现新增的字段、过程或事件
- 跟踪特定 AL 对象的演变
**示例：**
- `{"request": "版本 26 和 27 之间 Customer 表发生了什么变化？"}`
- `{"request": "比较 BC 25 和 BC 26 中的 Sales Order 页面"}`
- `{"request": "显示版本 27 中 Codeunit 80 新增的过程"}`
**注意：** 两个工具都会自动检测用户的意图并路由到相应的后端端点。
## 🚀 安装
### 先决条件
**1. 获取代码**
克隆或分叉此仓库：
```bash
# 克隆（推荐用户）
git clone https://github.com/pmoisontech/Alex-MCP-Proxy.git
cd Alex-MCP-Proxy
# 或分叉（如果您想贡献）
# 1. 在 GitHub 上点击“分叉”
# 2. 克隆您的分叉：
git clone https://github.com/YOUR-USERNAME/Alex-MCP-Proxy.git
cd Alex-MCP-Proxy
```
**2. Node.js 要求**
需要 Node.js 18 或更高版本。安装程序可以在缺少时自动安装。
### 自动安装（推荐）
**Windows PowerShell：**
```powershell
cd mcp-server-proxy
.\install-mcp.ps1
```
**Linux / macOS / WSL：**
```bash
cd mcp-server-proxy
./install-mcp.sh
```
安装程序将指导您完成整个设置：
- ✅ 安装 Node.js（如果需要）
- ✅ 连接到您的 Alex 帐户
- ✅ 配置 GitHub Copilot（VS Code）或 Claude Desktop
- ✅ 测试连接
安装后，重启 VS Code 或 Claude Desktop 以激活 Alex。
#### 命令行参数（高级）
用于自动/脚本安装：
**Linux / macOS / WSL：**
```bash
./install-mcp.sh --url URL --username USER --password PASS [--expiration-date DATE] [--vscode] [--claude]
```
**Windows PowerShell：**
```powershell
.\install-mcp.ps1 -Url URL -Username USER -Password PASS [-ExpirationDate DATE] [-VSCode] [-Claude]
```
**可用参数：**
| 参数 | 描述 | 默认值 |
|-----------|-------------|---------|
| `--url` / `-Url` | 后端 API URL（/api 包含在内） | `https://alex.app.pmats.ai/api` |
| `--username` / `-Username` | Alex 帐户用户名 | （自动模式下必填） |
| `--password` / `-Password` | Alex 帐户密码 | （自动模式下必填） |
| `--expiration-date` / `-ExpirationDate` | API 密钥过期日期（ISO 8601 UTC 格式） | 今天 + 3 个月 |
| `--vscode` / `-VSCode` | 配置 VS Code（GitHub Copilot） | 交互式提示 |
| `--claude` / `-Claude` | 配置 Claude Desktop | 交互式提示 |
| `--help` / `-Help` | 显示帮助消息 | - |
**示例 - 自动安装：**
```bash
./install-mcp.sh \
--username john@example.com \
--password MySecurePassword \
--expiration-date "2026-06-30T23:59:59Z" \
--vscode
```
**注意：** 过期日期格式必须是 ISO 8601 UTC：`YYYY-MM-DDTHH:MM:SSZ`
### 手动安装
如果您更喜欢手动配置：
#### 1. 安装 Node.js
确保您的计算机上已安装 Node.js 18 或更高版本。
#### 2. 安装依赖项
```bash
cd mcp-server-proxy
npm install
```
#### 3. 获取您的 API 密钥
连接到 Alex 并获取您的个人 API 密钥。密钥类似于 `sk_live_xxxxx`。
**⚠️ 保持您的 API 密钥安全！** 它可以访问您的 Alex 帐户。
#### 4. 配置 GitHub Copilot（VS Code）
创建或编辑文件：
**Windows**: `%APPDATA%\Code\User\mcp.json`
**Linux/macOS**: `~/.config/Code/User/mcp.json`
添加此配置：
```json
{
"mcpServers": {
"alex": {
"command": "node",
"args": [
"/ABSOLUTE/PATH/to/mcp-server-proxy/mcp-proxy-client.js"
],
"env": {
"_API_URL": "https://alex.app.pmats.ai/api",
"ALEX_API_KEY": "sk_live_xxxxx",
"MCP_CLIENT_NAME": "github_copilot"
}
}
}
}
```
**⚠️ 重要：**
- 将 `/ABSOLUTE/PATH/to/` 替换为计算机上的实际路径
- 将 `sk_live_xxxxx` 替换为您的个人 API 密钥
- `MCP_CLIENT_NAME` 有助于跟踪正在使用的客户端（github_copilot、cursor、windsurf、vscode 等）
- 保存后重启 VS Code
#### 5. 配置 Claude Desktop
创建或编辑文件：
**Windows**: `%APPDATA%\Claude\claude_config.json`
**macOS**: `~/Library/Application Support/Claude/claude_config.json`
**Linux**: `~/.Claude/claude_des.json`
**Windows with WSL:**
```json
"mcpServers": {
"alex": {
command": "wsl.exe",
"args": [
"-e", "bash", "-c",
"cd /home/user/mcp-server-proxy && ALEX_API_URL=https://alex.app.pmats.ai/api ALEX_API_KEY=sk_live_xxxxx MCP_CLIENT_NAME=claude_desktop node mcp-proxy-client.js"
]
}
}
}
```
**Linux/macOS:**
```json
{
"mcpServers": {
"alex": {
"command": "bash",
"args": [
"-c",
"cd /absolute/path/mcp-server-proxy && ALEX_API_URL=https://alex.app.pmats.ai/api ALEX_API_KEY=sk_live_xxxxx MCP_CLIENT_NAME=claude_desktop node mcp-proxy-client.js"
]
}
}
}
```
**⚠️ 重要：**
- 用实际值替换路径和 API 密钥
- `MCP_CLIENT_NAME` 有助于跟踪正在使用的客户端（claude_desktop、cursor、windsurf 等）
- 完全重启 Claude Desktop 后保存
## 💬 使用 Alex
### 与 GitHub Copilot 结合使用
1. **完全重启 VS Code**
2. 打开 **Copilot Chat** 面板
3. 询问有关 Business Central 的问题：
- "Business Central 中的 Customer 表如何工作？"
- "显示一个发布销售订单的代码单元示例"
- "版本 27 的 System App 中有什么新功能？"
Alex 将使用其对 Business Central AL 代码的了解自动回答。
### 与 Claude Desktop 结合使用
1. **完全重启 Claude Desktop** （关闭所有窗口，而不仅仅是聊天）
2. **打开设置** → **所有连接器**
3. 您应该看到 **"alex"**，包含 2 个工具：
- `alex_al_query`
- `alex_al_comparison`
4. **授权工具**：
- 点击 **"Blocked"** 下拉菜单
- 选择 **"Always allow"** 或 **"Allow for this**
- 两个工具现在都应显示 ✅（已授权）而不是 🚫（已阻止）
5. **开始提问**：
- "解释版本 26 和 27 之间 Customer 表的区别"
- "如何在 Business Central 中创建 API 页面？"
Alex 与 Claude 的对话无缝集成。
## 🔄 更新代理
如果 MCP 代理代码已更新功能、错误修复等），请按照以下步骤更新您的安装：
### 自动更新
**1. 拉取最新更改：**
```bash
cd mcp-server-proxy
git pull origin main
```
**2. 更新依赖项：**
```bash
npm install
```
**3. 重启 MCP 客户端：**
- **GitHub Copilot（VS Code）**：完全重启 VS Code
- **Claude Desktop**：关闭所有窗口并重启 Claude Desktop
### 手动验证
如果更新后遇到问题：
**1. 检查配置文件是否仍然有效：**
- **VS Code**: `%APPDATA%\Code\User\mcp.json`（Windows）或 `~/.config/Code/User/mcp.json`（Linux/macOS）
- **Claude Desktop**: `%APPDATA%\Claude\claude_desktop_config.json`（Windows）或 `~/.config/Claude/claude_desktop_config.json`（Linux/mac
**2. 验证文件路径是否指向更新的代理：**
`args` 数组应指向本地仓库中更新的 `mcp-proxy-client.js` 文件。
. 测试连接：**
简单的问题以确认更新是否成功：
- VS Code：使用 `#mcp_alex_alex_al_query`，问题为“什么是 Customer 表？”
- Claude Desktop：询问“什么是 Customer 表并授权 alex
### 重大更改
如果重大更新引入了重大更改（API 密钥格式、配置结构等）：
**备份当前配置** （API 密钥、. **再次运行安装程序**：`./install-mcp.sh` 或 `.\install-mcp.ps1`
3. 安装检测现有配置并合并更新
4. 按照LOG](../CHANGELOG 中的迁移说明进行操作
**注意：** 安装程序在更新时保留您的 API 密钥和其他自定义设置。
## 🔧 常见问题
### Alex 未出现在 GitHub Copilot 中
**解决方案：**
1. 检查 `mcp.json` 文件是否位于正确的位置
2. 验证文件路径是否为**绝对路径**（而非相对路径）
3. 完全重启 VS Code
4. 检查您的 API 密钥是否正确输入
### Alex 未出现在 Claude Desktop 中
**解决方案：**
1. 检查配置文件是否位于正确的位置
2. 完全**关闭并重新打开** Claude Desktop（不仅仅是最小化）
3. 检查 Claude 底部的**连接器图标**
4. 如有必要，请检查 `%APPDATA%\Claude\logs\`（Windows）中的日志
### “401 Unauthorized”错误
您的 API 密钥无效或已过期。
**解决方案：** 检查您的 API 密钥是否正确复制到配置文件中（格式为 `sk_live`）。
### Alex 没有回应
**解决方案：**
1. 检查您的互联网连接
2. 验证 `ALEX_API_URL` 是否为 `https://alex.app.pmats.ai/api`（包含 `/api` 后缀）
3. 尝试提出一个更简单的问题
4. 稍等几秒钟（初始响应可能需要一段时间）
## 🔐 安全
- 您的 **API 密钥是个人和机密的** - 永远不要分享它
- 与 Alex 的连接使用 **HTTPS**（安全）
- 您的代码和问题**不会永久存储**
- 每个用户都有自己的 **隔离帐户**
## ℹ️ 需要帮助？
如果您遇到本指南中未涵盖的问题：
1. 检查 Node.js 是否正确安装（`node --version`）
2. 验证配置文件是否为有效的 JSON
3. 如果手动配置，请尝试自动安装程序
4. 联系支持团队并提供精确的错误描述
## 📄 许可证
MIT 许可证 - 有关详细信息，请参见 [LICENSE](LICENSE) 文件。
2025 PMATS Consulting Group
