内容
# MCP 使能 PI1 - 提供商实现
本仓库包含由 Orange 在 [Commonalities 工作组](https://lf-camaraproject.atlassian.net/wiki/x/_QPe) 的 CAMARA MCP 使能计划中贡献的提供商实现。
本仓库不是 CAMARA API 仓库，不定义规范的 CAMARA MCP 规范。它托管实现材料，可以帮助探索和演示如何通过基于 MCP 的工具暴露 CAMARA API。
## 范围
本仓库旨在包含：
- Orange MCP 服务器贡献的实现代码；
- 支持的功能、限制和假设的文档；
- 运行实现的设置和用法说明；
- 实现特定的问题和后续任务。
详细的功能范围由仓库代码所有者负责，并应在实现添加时在此记录。
## 实现描述
一个模型上下文协议（MCP）服务器，提供与 Orange 网络 API 游戏场和行政工具交互的工具，遵循 Camara 规范。该服务器实现与 AI 助手无缝集成，让您访问各种网络功能，包括设备位置、漫游状态、SIM 卡更换检测和游戏场管理。
### 功能
#### 网络 API 工具
- **设备位置检索**：获取设备的当前位置
- **设备位置验证**：验证设备是否位于特定位置
- **设备可达性状态**：检查设备在网络上是否可达
- **设备漫游状态**：确定设备是否正在漫游
- **SIM 卡更换检测**：检测最近的 SIM 卡更换事件
- **人口密度数据**：检索某个区域的人口密度信息
- **KYC 匹配**：将用户信息与运营商验证的数据进行比较以进行身份验证
- **QoS 配置文件管理**：检索和管理具有详细性能特征的服务质量配置文件
- **QoS 会话创建**：在设备和应用服务器之间创建增强的服务质量会话
- **QoS 会话管理**：获取、延长和终止服务质量会话
- **QoS 会话监控**：检索特定设备的活动 QoS 会话
#### 游戏场管理
- **电话号码管理**：列出、添加和管理游戏场中的电话号码
- **配置工具**：用于游戏场设置和管理的管理工具
### 安装与使用
#### 先决条件
- Node.js >= 24.0.0
- Yarn 4.x 包管理器（通过 Corepack 管理）
- 有效的 Orange API 凭证，访问 https://developer.orange.com/apis/camara-playground
##### 如何获取 Orange API 凭证
1. 访问 Orange 开发者门户：https://developer.orange.com/apis/camara-playground
2. 创建帐户或登录（如果已有帐户）
3. 订阅 CAMARA 游戏场 API
4. 订阅后，您将收到 `CLIENT_ID` 和 `CLIENT_SECRET`
5. 这些凭证将用于 MCP 服务器配置
#### 设置
1. 克隆仓库
2. 启用 Corepack（如果尚未启用）：
```bash
corepack enable
```
这将激活 Corepack，它根据 `package.json` 中指定的版本管理 Yarn。项目使用 Yarn 4.13.0，它将自动下载并使用。
3. 安装依赖项：
```bash
yarn install
```
4. 构建项目
```bash
yarn build
```
#### AI 助手配置
构建完成后，您可以将 MCP 服务器与任何兼容 MCP 的 AI 助手（例如 [Cline](https://cline.bot/)、[MCPJam](https://www.mcpjam.com/)、[Goose](https://github.com/aaif-goose/goose) 等）一起使用。
具体配置取决于您使用的助手。
##### 通用配置
使用以下命令：
```bash
node /绝对路径/到项目/dist/index.js
```
确保设置所需的环境变量：
- `CLIENT_ID`：您的 Orange API 客户端 ID
- `CLIENT_SECRET`：您的 Orange API 客户端密钥
##### Claude Desktop 配置
将以下配置添加到您的 Claude Desktop MCP 设置文件中：
**macOS**：`~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**：`%APPDATA%/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"orange-network-api": {
"command": "node",
"args": ["/绝对路径/到项目/dist/index.js"],
"env": {
"CLIENT_ID": "您的客户端 ID",
"CLIENT_SECRET": "您的客户端密钥"
}
}
}
}
```
#### 示例提示
配置 AI 助手后，您可以开始提示。您将在提示文件夹中找到一些示例。
注意，您需要首先创建一些假电话号码，如 [init 提示文件](./prompts/init.md) 中所述。
## 贡献
本提供商实现的讨论和协调应使用 Commonalities 工作组的邮件列表：
- 订阅 / 取消订阅：https://lists.camaraproject.org/g/wg-commonalities
- 邮件列表地址：wg-commonalities@lists.camaraproject.org
仓库特定的工作应通过此仓库的 GitHub 问题进行跟踪。
### 先决条件
- Node.js >= 24.0.0
- Yarn 4.x 包管理器（通过 Corepack 管理）
- 有效的 Orange API 凭证，访问 https://developer.orange.com/apis/camara-playground
### 设置
1. 克隆仓库
2. 启用 Corepack（如果尚未启用）：
```bash
corepack enable
```
这将激活 Corepack，它根据 `package.json` 中指定的版本管理 Yarn。项目使用 Yarn 4.13.0，它将自动下载并使用。
3. 安装依赖项：
```bash
yarn install
```
4. 创建一个包含您配置的 `.env` 文件：
```env
CLIENT_ID=您的客户端 ID
CLIENT_SECRET=您的客户端密钥
```
### 可用脚本
- **安装依赖项**：`yarn install`
- **构建项目**：`yarn build`
- **在监视模式下构建**：`yarn build:watch`
- **运行 linter**：`yarn lint`
- **类型检查**：`yarn type-check`
- **运行检查器**：`yarn inspector`
- **列出依赖项许可证**：`yarn licenses`
### 开发工作流程
1. 创建一个功能分支：`git checkout -b feature/您的功能`
2. 在 `src` 目录中进行更改
3. 运行 linter 检查代码质量：
```bash
yarn lint
```
4. 构建项目：
```bash
yarn build
```
5. 使用检查器测试您的更改：
```bash
yarn inspector
```
### 在开发过程中使用 MCP 客户端进行测试
您可以配置兼容 MCP 的应用程序使用您本地的构建进行测试：
1. 首先构建项目：
```bash
yarn build
```
2. 使用绝对路径配置您的 MCP 客户端：
```bash
node /绝对路径/到项目/dist/index.js
```
3. 确保在您的 MCP 客户端配置中设置所需环境变量或在 shell 中导出它们：
```bash
export CLIENT_ID="您的客户端 ID"
export CLIENT_SECRET="您的客户端密钥"
```
### 项目结构
```
src/
├── api/ # API 客户端实现
├── tools/ # MCP 工具实现
├── prompts/ # MCP 提示实现
├── resources/ # MCP 资源实现
├── config.ts # 配置管理
└── index.ts # 主服务器入口点
```
### 配置
服务器可以使用环境变量进行配置：
| 变量 | 描述 | 默认值 |
|----------|-------------|---------|
| `CLIENT_ID` | Orange API 客户端 ID | 必需 |
| `CLIENT_SECRET` | Orange API 客户端密钥 | 必需 |
| `API_BASE_URL` | Orange API 基本 URL | `https://api.orange.com/camara/playground` |
| `API_TIMEOUT` | 请求超时（毫秒） | `30000` |
| `API_RETRIES` | 重试次数 | `3` |
| `HTTP_PROXY` | HTTP 代理 URL | — |
| `HTTPS_PROXY` | HTTPS 代理 URL | — |
| `NO_PROXY` | 绕过代理的主机列表（逗号分隔） | — |
