内容
# LicenseSpring® MCP 服务器
LicenseSpring 授权服务器的实现，集成 LicenseSpring API，提供全面的授权管理和客户操作功能。
## 功能
- **授权操作**：激活、检查、停用带有硬件绑定的授权
- **客户管理**：创建、列出和管理客户
- **使用跟踪**：监控授权消耗和功能使用情况
- **试用管理**：生成和管理试用授权
- **浮动授权**：处理浮动授权操作
- **身份验证优先级**：以 LICENSE_API_KEY 为主要方法，LICENSE_SHARED_KEY 为可选，以增强安全性
- **全面测试**：具有真实 API 验证的完整集成测试套件
## 工具
### 授权 API 工具
- **activate_license** - 激活带有硬件 ID 绑定的授权
- **check_license** - 检查授权状态和有效性
- **deactivate_license** - 停用特定硬件的授权
- **add_consumption** - 向授权添加消费单位
- **get_trial_key** - 生成试用授权密钥
- **get_product_details** - 检索产品信息
- **floating_release** - 释放浮动授权
- **floating_borrow** - 借用浮动授权用于离线使用
- **change_password** - 更改基于用户的授权的用户密码
- **get_versions** - 获取可用的软件版本
- **get_installation_file** - 获取安装文件信息
- **get_sso_url** - 生成单点登录 URL
### 管理 API 工具
- **list_licenses** - 列出授权，可选过滤
- **create_license** - 创建新的授权
- **update_license** - 更新现有的授权
- **get_license** - 获取详细的授权信息
- **delete_license** - 删除授权
- **list_customers** - 列出客户，可选过滤选项
- **create_customer** - 创建新的客户
## 配置
### 获取 API 凭证
1. **授权 API 密钥**：登录 LicenseSpring 控制台 → 设置 → 密钥（主要身份验证方法）
2. **管理 API 密钥**：相同位置，复制您的管理 API 密钥
3. **共享密钥**：适用于使用共享 API 设置的组织（提供增强的安全性）
### 测试
运行综合集成测试以验证功能：
```bash
# 构建项目
npm run build
# 对真实 LicenseSpring API 运行集成测试
npm run test:integration
# 运行单元测试
npm test
```
集成测试验证了所有 34 个 MCP 工具与真实 LicenseSpring API，并验证身份验证优先级正确工作。该实现提供了与 LicenseSpring Postman 集合的 100% 功能对等。
🔧 **CI/CD 集成**：GitHub Actions 工作流现在支持具有适当机密配置的完整集成测试。
### 与 Claude Desktop 配合使用
将以下内容添加到您的 `claude_desktop_config.json`：
#### 授权 API 服务器
```json
{
"mcpServers": {
"licensespring": {
"command": "npx",
"args": [
"-y",
"@tfedorko/licensespring-mcp-server",
"license-api"
],
"env": {
"LICENSE_API_KEY": "您的_LICENSE_API_KEY",
"LICENSE_SHARED_KEY": "如果使用共享 API 设置，则为您的共享密钥"
}
}
}
}
```
#### 管理 API 服务器
```json
{
"mcpServers": {
"licensespring-management": {
"command": "npx",
"args": [
"-y",
"@tfedorko/licensespring-mcp-server",
"management-api"
],
"env": {
"MANAGEMENT_API_KEY": "您的管理 API 密钥"
}
}
}
}
```
#### Docker
```json
{
"mcpServers": {
"licensespring": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"LICENSE_API_KEY",
"-e",
"LICENSE_SHARED_KEY",
"stiertfedorko/licensespring-mcp:latest"
],
"env": {
"LICENSE_API_KEY": "您的_LICENSE_API_KEY",
"LICENSE_SHARED_KEY": "您的共享密钥或留空"
}
},
"licensespring-management": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"MANAGEMENT_API_KEY",
"stiertfedorko/licensespring-mcp-management:latest"
],
"env": {
"MANAGEMENT_API_KEY": "您的管理 API 密钥"
}
}
}
}
```
## 订阅层级支持
服务器会自动适应您的 LicenseSpring 订阅层级：
- **高级/企业**：具有 HMAC 身份验证的完整功能
- **基本/标准**：有限模式，并提供升级指导
- **开发**：测试模式，用于安全开发
> **注意**：`LICENSE_SHARED_KEY` 是可选的。无论您的订阅层级如何，服务器都将启动，并为 API 限制提供适当的指导。
## 与 VS Code 配合使用
对于快速安装，请使用下面的“一键安装”按钮：
[](https://insiders.vscode.dev/redirect/mcp/install?name=licensespring&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22apiKey%22%7D%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40modelcontextprotocol%2Fserver-licensespring%22%5D%2C%22env%22%3A%7B%22LICENSE_API_KEY%22%3A%22%24%7Binput%3Alicense_api_key%7D%22%7D%7D)
[](https://insiders.vscode.dev/redirect/mcp/install?name=licensespring&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22apiKey%22%7D%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40modelcontextprotocol%2Fserver-licensespring%22%5D%2C%22env%22%3A%7B%22LICENSE_API_KEY%22%3A%22%24%7Binput%3Alicense_api_key%7D%22%7D%7D&quality=insiders)
对于手动安装，请在 VS Code 的用户设置（JSON）文件中添加以下 JSON 块：
#### NPX
```json
{
"mcp": {
"inputs": [
{
"type": "promptString",
"id": "license_api_key",
"description": "LicenseSpring 授权 API 密钥",
"password": true
},
{
"type": "promptString",
"id": "license_shared_key",
"description": "LicenseSpring 共享密钥（基本/标准层级的可选）",
"password": true
}
],
"servers": {
"licensespring": {
"command": "npx",
"args": ["-y", "@tfedorko/licensespring-mcp-server", "license-api"],
"env": {
"LICENSE_API_KEY": "${input:license_api_key}",
"LICENSE_SHARED_KEY": "${input:license_shared_key}"
}
}
}
}
}
```
## 故障排除
### 常见问题
**错误：“npm 错误：无法确定要运行的可执行文件”**
- **解决方案**：更新到 1.0.1 或更高版本：`npx @tfedorko/licensespring-mcp-server@latest`
- **原因**：在 v1.0.1 中修复 - 改进的二进制配置和启动过程
**错误：“MCP 错误 -1：连接关闭”**
- **解决方案**：更新到 1.0.2 或更高版本：`npx @tfedorko/licensespring-mcp-server@latest`
- **原因**：在 v1.0.2 中修复 - 服务器现在默认为 Claude Desktop 兼容性的 license-api 模式
**错误：“LICENSE_API_KEY 是必需的”**
- **解决方案**：在 `.env` 文件或 Claude Desktop 配置中设置环境变量
- **检查**：复制 `.env.example` 到 `.env` 并填写您的 API 凭证
**错误：“身份验证失败”**
- **解决方案**：在 LicenseSpring 控制台中验证您的 API 密钥
- **注意**：对于基本/标准订阅层级，`LICENSE_SHARED_KEY` 是可选的
**服务器启动但 API 调用失败**
- **检查**：您的 LicenseSpring 订阅层级和可用的 API 功能
- **解决方案**：服务器为订阅限制提供有用的指导
### 获取帮助
1. 检查错误消息 - 它们提供特定的指导
2. 验证您的 LicenseSpring 订阅层级和 API 访问权限
3. 查看下面的 [高级文档](#高级文档)
4. 在 GitHub 上打开一个问题，并附上错误详细信息
## 发布自动化
该项目包括全面的自动化发布版本和 NPM 分发：
### 快速发布命令
```bash
npm run release # 修补程序发布（1.0.0 -> 1.0.1）
npm run release:minor # 次要发布（1.0.0 -> 1.1.0）
npm run release:major # 主要发布（1.0.0 -> 2.0.0）
```
### 预览更改
```bash
npm run version:dry # 预览版本提升
npm run publish:dry # 预览 NPM 发布
```
### 自动 GitHub 发布
- **提交触发器**：在提交消息中使用 `[release]`
- **手动调度**：GitHub Actions 工作流
- **语义发布**：约定提交消息
有关完整的自动化文档，请参阅 **[发布自动化指南](docs/RELEASE_AUTOMATION.md)**。
## 高级文档
有关综合指南和高级配置：
- **[发布自动化指南](docs/RELEASE_AUTOMATION.md)** - 完整的自动化发布和分发系统
- **[订阅层级支持](docs/SUBSCRIPTION_TIERS.md)** - 不同 LicenseSpring 订阅层级的详细指南
- **[分发指南](docs/DISTRIBUTION_GUIDE.md)** - 完整的设置和共享说明
- **[测试报告](docs/TEST_REPORT.md)** - 综合测试结果和验证
- **[迁移指南](docs/MIGRATION_TO_OFFICIAL_PATTERN.md)** - 技术实现细节
## 安装
### NPM 包
```bash
npm install -g @tfedorko/licensespring-mcp-server
```
> **注意**：需要 Node.js 20.x 或更高版本以获得最佳兼容性。
### Docker 镜像
```bash
# 授权 API 服务器
docker pull stiertfedorko/licensespring-mcp:latest
# 管理 API 服务器
docker pull stiertfedorko/licensespring-mcp-management:latest
```
## 构建
Docker 构建：
```bash
docker build -t licensespring-mcp:latest -f Dockerfile .
docker build -t licensespring-mcp-management:latest -f Dockerfile.management .
```
## 许可证
该 MCP 服务器根据 MIT 许可证授权。这意味着您可以自由使用、修改和分发该软件，但需遵守 MIT 许可证的条款和条件。有关更多详细信息，请参阅项目存储库中的 LICENSE 文件。
## 商标声明
该项目在获得 Cense Data Inc. 的许可后使用 LicenseSpring® 名称。请参阅 [TRADEMARK](TRADEMARK) 文件以获取详细信息。
