Hostbill MCP Server

HostBill MCP服务器

一个生产就绪的模型上下文协议（MCP）服务器，提供对HostBill全面的API的标准化访问，使AI代理能够管理客户端、计费、支持票证、域和托管服务。

概述

此MCP服务器通过15个组织良好的工具公开HostBill的70+API方法，遵循MCP最佳实践，在保持完整功能的同时防止工具预算过多。服务器处理身份验证、错误转换、日志记录，并提供相关操作的智能分组。

特性

• 15组织工具 -按业务域对70+HostBill API方法进行逻辑分组
• 客户管理 -搜索、检索、创建、更新和删除客户端帐户
• 服务账户 -管理托管服务、暂停和终止
• 账单和发票 -创建发票、处理付款、搜索账单记录
• 支持票 -完整的票证生命周期管理，包括回复和状态更新
• 域管理 -检查可用性、注册和管理域
• 订单处理 -浏览产品并管理订单生命周期
• 全面的错误处理 -具有适当分类的结构化错误
• 日志记录 -基于Winston的关联ID结构化日志记录
• 输入验证 -所有参数的Zod模式
• 连接池 -Axios具有自动重试逻辑

安装

1. 克隆或下载此存储库

1. 安装依赖项

npm install

1. 配置环境变量

复制 .env.example 到 .env 并填写您的HostBill凭据：

cp .env.example .env

编辑 .env:

HOSTBILL_URL=https://your-hostbill-instance.com
HOSTBILL_API_ID=your_api_id
HOSTBILL_API_KEY=your_api_key
NODE_ENV=development
LOG_LEVEL=info

1. 构建项目

npm run build

用法

运行服务器

npm start

Watch开发模式

npm run watch

然后在另一个终端中：

npm start

MCP检验员测试

npm run inspect

可用工具

客户管理（3个工具）

search-clients

使用分页搜索和列出客户帐户。

• 参数: query, page, perPage
• 退货：具有分页信息的客户端列表

get-client-profile

检索完整的客户信息，包括订单、发票、域和票证。

• 参数: clientId
• 退货：全面的客户资料及相关数据

manage-client

创建、更新或删除客户端帐户。

• 参数: action （创建/更新/删除），客户详细信息
• 行动:

- create：添加新客户端 - update：修改客户详细信息 - delete：删除客户端

服务帐户（2个工具）

list-services

使用分页列出和筛选服务帐户。

• 参数: status, page, perPage
• 退货：服务帐户列表

manage-service

创建、修改、暂停、取消暂停或终止服务。

• 参数: action （创建/更新/挂起/取消挂起/终止）
• 行动:

- create：提供新服务 - update：修改服务详细信息 - suspend：暂停服务 - unsuspend：重新激活服务 - terminate：终止服务

账单和发票（3个工具）

search-invoices

按页码列出和过滤发票。

• 参数: status, page, perPage
• 退货：发票清单

create-invoice

使用行项目创建新发票。

• 参数: clientId, items, dueDate
• 退货：发票ID和创建状态

process-payment

申请付款或从信用卡中扣款。

• 参数: action （记录/收费）， invoiceId, amount
• 行动:

- record：记录手动付款 - charge：从信用卡上扣款

支持票（3个工具）

search-tickets

列出并过滤支持票。

• 参数: status, priority, page, perPage
• 退货：门票列表

get-ticket-thread

检索所有回复的完整票。

• 参数: ticketId
• 退货：带有完整对话线索的门票详细信息

manage-ticket

创建工单、添加回复、更新状态/优先级。

• 参数: action （创建/回复/更新状态/更新优先级）
• 行动:

- create：打开新票 - reply：向工单添加回复 - update-status：更改票证状态 - update-priority：更改票证优先级

域管理（2个工具）

check-domain-availability

检查域是否可用于注册。

• 参数: domain
• 退货：可用性状态

manage-domain

注册、编辑或获取域详细信息。

• 参数: action （注册/编辑/获取），域名详细信息
• 行动:

- register：注册新域 - edit：更新域详细信息 - get：检索域信息

订单和产品（2个工具）

browse-products

列出可用产品及其定价。

• 参数: page, perPage
• 退货：带定价层的产品目录

manage-order

创建和管理订单。

• 参数: action （创建/激活/取消），订单详细信息
• 行动:

- create：创建新订单 - activate：激活待处理订单 - cancel：取消订单

建筑

hostbill-mcp-server/
├── src/
│   ├── index.ts              # Server initialization and tool registration
│   ├── tools/                # MCP tool implementations
│   │   ├── clients.ts        # Client management tools
│   │   ├── accounts.ts       # Service account tools
│   │   ├── invoices.ts       # Billing and invoice tools
│   │   ├── tickets.ts        # Support ticket tools
│   │   ├── domains.ts        # Domain management tools
│   │   └── orders.ts         # Order processing tools
│   ├── services/
│   │   └── hostbill.ts       # HostBill API client wrapper
│   ├── config/
│   │   └── auth.ts           # Configuration management
│   └── utils/
│       ├── errors.ts         # Error handling utilities
│       ├── logger.ts         # Structured logging
│       └── validation.ts     # Input validation schemas
├── build/                    # Compiled JavaScript
├── .env                      # Environment configuration
├── package.json
└── tsconfig.json

安全

• 环境变量：从不硬编码凭据
• 输入验证：Zod模式防止注入攻击
• 错误处理：没有敏感数据泄漏的结构化错误
• IP白名单：在HostBill管理面板中配置
• API权限：在HostBill中使用功能级访问控制

错误处理

服务器使用结构化错误类别：

• AUTHENTICATION_ERROR -API凭据无效
• PERMISSION_ERROR -API密钥缺少所需的权限
• VALIDATION_ERROR -无效参数
• RESOURCE_NOT_FOUND -实体不存在
• API_ERROR -HostBill API错误
• NETWORK_ERROR -连接失败
• RATE_LIMIT -请求太多

所有错误都会用相关ID记录下来，以便调试。

日志记录

日志将写入：

• error.log -仅错误级别日志
• combined.log -所有日志
• 控制台-用于开发的格式化输出

日志条目包括：

• 用于请求跟踪的相关ID
• 工具调用详细信息
• API调用延迟指标
• 错误上下文和堆栈跟踪

API集成

服务器使用HostBill的Admin API：

• 端点: {HOSTBILL_URL}/admin/api.php
• 方法：HTTP POST
• 认证：API ID+API密钥
• 响应格式：JSON格式 success 布尔

分页

大多数列表操作都支持分页：

• 默认值：每页25条记录
• 每页最多100条记录
• 响应包括 hasMore 指标

Docker部署

构建Docker镜像

# Build the image
docker build -t hostbill-mcp-server .

# Or use docker-compose
docker-compose build

使用Docker运行

选项1：使用docker run

docker run -d \
  --name hostbill-mcp-server \
  -e HOSTBILL_URL=https://your-hostbill-instance.com \
  -e HOSTBILL_API_ID=your_api_id \
  -e HOSTBILL_API_KEY=your_api_key \
  -e NODE_ENV=production \
  -e LOG_LEVEL=info \
  -v $(pwd)/logs:/app/logs \
  hostbill-mcp-server

选项2：使用docker compose

1. 创建一个 .env 使用您的凭据文件：

HOSTBILL_URL=https://your-hostbill-instance.com
HOSTBILL_API_ID=your_api_id
HOSTBILL_API_KEY=your_api_key
NODE_ENV=production
LOG_LEVEL=info

1. 启动容器：

docker-compose up -d

1. 查看日志：

docker-compose logs -f

1. 停止容器：

docker-compose down

Docker镜像功能

• 多阶段构建 -优化图像大小
• 非root用户 -出于安全考虑，以无特权用户身份运行
• 健康检查 -自动集装箱健康监测
• 资源限制 -CPU和内存限制
• 持久日志 -用于日志持久性的卷装载
• Alpine Linux -最小基础映像（总计约150MB）

Docker命令

# Check container status
docker-compose ps

# View logs
docker-compose logs -f hostbill-mcp-server

# Restart container
docker-compose restart

# Rebuild after code changes
docker-compose up -d --build

# Execute commands in container
docker-compose exec hostbill-mcp-server sh

# Remove container and volumes
docker-compose down -v

生产Docker部署

对于生产环境：

1. 使用机密管理:

# Use Docker secrets or Kubernetes secrets
docker secret create hostbill_api_key /path/to/api_key.txt

1. 配置监视:

# Add to docker-compose.yml
logging:
  driver: "json-file"
  options:
    max-size: "10m"
    max-file: "3"

1. 使用编排 （Kubernetes示例）：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: hostbill-mcp-server
spec:
  replicas: 3
  selector:
    matchLabels:
      app: hostbill-mcp-server
  template:
    metadata:
      labels:
        app: hostbill-mcp-server
    spec:
      containers:
      - name: hostbill-mcp-server
        image: hostbill-mcp-server:latest
        env:
        - name: HOSTBILL_URL
          valueFrom:
            secretKeyRef:
              name: hostbill-secrets
              key: url
        resources:
          limits:
            cpu: "1"
            memory: "512Mi"
          requests:
            cpu: "500m"
            memory: "256Mi"

发展

TypeScript编译

npm run build

观看模式

npm run watch

日志记录级别

集 LOG_LEVEL 在 .env:

• error -仅错误
• warn -警告和错误
• info -一般信息（默认）
• debug -详细调试

生产部署

对于生产使用，请考虑：

1. 环境：设置 NODE_ENV=production
2. HTTPS传输：使用OAuth 2.1实现流式HTTP
3. 秘密管理：使用安全的秘密存储（AWS Secrets Manager等）
4. 监控：配置监控和警报
5. 速率限制：实施客户端速率限制
6. 码头工人：使用提供的Dockerfile和docker-compose.yml

故障排除

连接问题

• 验证 HOSTBILL_URL 正确且可访问
• 检查API凭据是否有效
• 确保IP在HostBill中被列入白名单
• 验证API密钥是否具有所需的功能权限

身份验证错误

• 在HostBill管理面板中重新生成API凭据
• 检查IP白名单配置
• 验证API密钥是否可以访问所需的功能

工具故障

• 检查登录 error.log 和 combined.log
• 在错误消息中查找相关ID
• 验证输入参数是否符合架构要求

贡献

此服务器遵循MCP最佳实践和HostBill API约定。添加新工具时：

1. 在中添加验证架构 utils/validation.ts
2. 按照现有模式创建工具处理程序
3. 在中注册工具 index.ts
4. 添加全面的错误处理
5. 包括调试日志
6. 更新README文档

许可证

麻省理工学院

支持

有关HostBill API文档，请访问您的HostBill实例： https://your-hostbill-instance.com/admin/api.php

对于MCP文件：

• 模型上下文协议
• MCP TypeScript SDK

致谢

内置：

• @模型上下文协议/sdk -MCP实施
• 轴 -HTTP客户端
• 黄道带 -架构验证
• 温斯顿 -日志记录