1NCE API MCP Server

1NCE IoT 平台 MCP 服务

一个模型上下文协议（MCP）服务，可让 AI Agent 通过自然语言与 1NCE IoT 连接管理平台交互。

概述

本项目提供一个中间件层，将大模型（LLM）连接到 1NCE API，以管理 IoT 连接。它可让 AI 助手：

• 获取产品信息
• 管理订单
• 监控 SIM 卡状态
• 查看数据和 SMS 配额
• 更新 SIM 配置
• 查看连接信息

通过模型上下文协议提供这些功能，AI Agent 可以使用自然语言与 IoT 基础设施交互，从而简化联网设备的管理。

功能

• 身份验证：通过 1NCE API 进行安全的 OAuth 2.0 令牌身份验证
• 产品管理：查询可用的 IoT 连接产品
• 订单管理：创建和跟踪订单
• SIM 管理：监控和配置 SIM 卡
• 资源：直接访问 SIM 状态和产品数据
• 提示词：针对常见任务预先定义的交互模板

前提条件

• Python 3.8+
• FastMCP v2
• 拥有 API 凭据的 1NCE 账户

安装

1. 克隆此仓库

git clone https://github.com/yourusername/1nce-mcp-server.git
cd 1nce-mcp-server

2. 安装所需依赖

pip install fastmcp httpx

3. 设置包含 1NCE API 凭据的环境变量

export ONCE_CLIENT_ID="your_client_id"
export ONCE_CLIENT_SECRET="your_client_secret"

使用方法

使用 FastMCP 安装

推荐使用 FastMCP CLI 安装此 MCP 服务：

fastmcp install 1nce_mcp.py

这样即可让兼容的 MCP 客户端使用此服务，包括 Claude Desktop。

直接运行

在开发或测试时，可以直接运行此服务：

python 1nce_mcp.py

与客户端配合使用

可以使用 FastMCP 客户端以编程方式与服务交互：

from fastmcp import Client

async with Client("1nce_mcp.py") as client:
    # Get list of products
    products = await client.call_tool("get_all_products")
    print(products)
    
    # Check SIM status
    sim_status = await client.call_tool("get_sim_status", {"iccid": "your_sim_iccid"})
    print(sim_status)

可用工具

产品工具

• get_all_products() - 获取所有可用的 1NCE 产品

订单工具

• get_all_orders(page, page_size, sort) - 获取订单列表，支持分页
• get_order_by_number(order_number) - 获取指定订单的详细信息
• create_order(products, delivery_address, customer_reference) - 创建新订单

SIM 工具

• get_all_sims(page, page_size, query, sort) - 列出 SIM 卡，支持筛选选项
• get_sim_details(iccid) - 获取指定 SIM 卡的详细信息
• get_sim_status(iccid) - 查看 SIM 卡的连接状态
• get_sim_data_quota(iccid) - 查看 SIM 卡的剩余数据配额
• get_sim_sms_quota(iccid) - 查看 SIM 卡的剩余 SMS 配额
• update_sim_status(iccid, status, label, imei_lock) - 更新 SIM 配置
• get_sim_usage(iccid, start_date, end_date) - 获取指定时间段的使用统计信息
• get_sim_events(iccid, page, page_size, sort) - 获取 SIM 卡的事件历史记录
• reset_sim_connectivity(iccid) - 触发 SIM 卡连接重置

示例

检查 SIM 状态

from fastmcp import Client

async with Client("1nce_mcp.py") as client:
    # Check SIM status
    sim_status = await client.call_tool("get_sim_status", {
        "iccid": "8988303000123456789"
    })
    print(f"SIM Status: {sim_status.get('status')}")
    
    # Check data quota
    quota = await client.call_tool("get_sim_data_quota", {
        "iccid": "8988303000123456789"
    })
    print(f"Remaining data: {quota.get('volume')} MB")
    print(f"Expires on: {quota.get('expiry_date')}")

创建订单

from fastmcp import Client

async with Client("1nce_mcp.py") as client:
    # Create an order for 5 SIM cards
    order = await client.call_tool("create_order", {
        "products": [{"productId": 1001, "quantity": 5}],
        "customer_reference": "IoT-Project-XYZ"
    })
    print(f"Order created with number: {order.get('order_number')}")

安全性

• MCP 服务要求将 1NCE API 凭据设置为环境变量
• 使用 OAuth 2.0 和 Basic Authentication 进行身份验证
• 动态获取访问令牌，不会持久存储
• 此服务仅公开必要的 API 操作，并优先提供读取操作而非写入操作

贡献

欢迎贡献！欢迎提交 Pull Request。

许可证

本项目采用 MIT License 许可，详情请参阅 LICENSE 文件。

致谢

• 感谢 1NCE 提供 IoT 连接 API
• 感谢 FastMCP 提供 MCP 服务框架
• 感谢 Anthropic 提供 Claude AI 助手功能