软件管理服务器

MCP-软件管理🚀

本地模型上下文协议（MCP）服务器，使AI编码代理能够以安全、自动化和非交互式的方式管理计算机上的软件。

该项目侧重于系统自动化：它使AI代理能够通过显式的MCP工具执行常见的软件管理工作流程，从安装应用程序到检查更新，再到为特定任务推荐软件。

🌟 概述

现代人工智能编码代理擅长理解需求和自动化任务，但它们往往缺乏对系统软件管理工作流程的标准化、非交互式访问。

该项目通过将软件管理功能作为显式MCP工具公开，使AI代理能够安全、可预测地管理系统软件，而无需依赖终端提示或交互式安装程序，从而弥合了这一差距。

🏗️ 建筑

该项目遵循一种干净的分层架构，其灵感来自现代MCP服务器的最佳实践：

main.py (MCP Tool Endpoints)
    ↓ Async/Sync Bridge (asyncio.to_thread)
services/ (Business Logic)
    ↓
utils/ (Low-level Utilities)
    ↓
models/ (Data Validation)

目录结构

software/
├── main.py                 # MCP tool endpoints
├── settings.py             # Configuration management
├── pyproject.toml          # Project metadata
├── requirements.txt        # Python dependencies
├── README.md               # This file
├── models/                 # Data validation & response models
│   ├── __init__.py
│   ├── result.py           # ToolResult, ErrorInfo
│   ├── cmd_result.py       # CmdResult (command execution)
│   └── software_models.py  # Input validators (Pydantic)
├── services/               # Business logic layer
│   ├── __init__.py
│   └── software_service.py # SoftwareService class
├── utils/                  # Utility functions
│   ├── __init__.py
│   ├── errors.py           # Error code constants
│   ├── paths.py            # Path utilities
│   └── validate.py         # Input validation helpers
└── tests/                  # Test suite (future)

建筑原理

• 关注点分离：每一层都有单一的职责
• 错误处理：用于程序处理的结构化错误代码
• 非交互式：所有操作异步运行，适用于AI代理
• 类型安全：用于输入/输出验证的Pydantic模型
• 不变性：冻结数据类以实现可靠的状态管理

🛠️ 可用工具

install_software

安装具有自动版本管理和跟踪功能的软件应用程序。

参数：

• software_name （string，必填）：要安装的软件的名称

退货：

• ok （布尔值）：成功指示器
• data （object）：包含软件名称、版本和状态

错误代码：

• software_not_found：软件不在数据库中
• already_installed：软件已安装
• invalid_input：输入验证失败
• registry_error：保存注册表时出错

uninstall_software

通过适当的清理和注册表更新从系统中删除软件。

参数：

• software_name （string，必填）：要卸载的软件的名称

退货：

• ok （布尔值）：成功指示器
• data （object）：包含软件名称和状态

错误代码：

• software_not_found：软件不在数据库中
• not_installed：当前未安装软件
• invalid_input：输入验证失败
• registry_error：保存注册表时出错

list_installed_software

显示所有已安装软件及其版本的完整列表。

参数：

• 无

退货：

• ok （布尔值）：成功指示器
• data （对象）：包含 installed_software 数组和计数

响应示例：

{
  "ok": true,
  "data": {
    "installed_software": [
      {
        "name": "python",
        "version": "3.11.0",
        "description": "Python programming language"
      }
    ],
    "count": 1
  }
}

check_updates

识别具有可用更新的软件。

参数：

• 无

退货：

• ok （布尔值）：成功指示器
• data （对象）：包含 available_updates 数组和计数

update_software

将软件应用程序更新到最新版本。

参数：

• software_name （string，必填）：要更新的软件的名称

退货：

• ok （布尔值）：成功指示器
• data （object）：包含旧版本、新版本和状态

错误代码：

• software_not_found：软件不在数据库中
• not_installed：当前未安装软件
• up_to_date：已为最新版本
• invalid_input：输入验证失败
• registry_error：保存注册表时出错

get_recommendations

获取特定任务或目标的软件建议。

参数：

• task （字符串，必填）：任务名称（例如“web开发”）

支持的任务：

• web development → Python、Node.js、VS代码、Git
• data science → Python、Node.js、Git
• database MySQL，PostgreSQL，Git
• containerization → Docker、Git
• java development → Java、VS代码、Git
• full stack → Python、Node.js、MySQL、Docker、VS Code、Git

退货：

• ok （布尔值）：成功指示器
• data （object）：包含任务名称、建议数组和计数

错误代码：

• software_not_found：未找到任务
• invalid_input：输入验证失败

set_auto_update

配置软件的自动更新设置。

参数：

• software_name （string，必填）：软件名称
• enabled （布尔值，必填）：启用（true）或禁用（false）自动更新

退货：

• ok （布尔值）：成功指示器
• data （对象）：包含软件名称、auto_update状态和状态消息

错误代码：

• software_not_found：软件不在数据库中
• not_installed：当前未安装软件
• invalid_input：输入验证失败
• registry_error：保存注册表时出错

get_software_info

检索有关软件应用程序的详细信息。

参数：

• software_name （string，必填）：软件名称

退货：

• ok （布尔值）：成功指示器
• data （object）：包含完整的软件详细信息

响应示例：

{
  "ok": true,
  "data": {
    "name": "python",
    "description": "Python programming language",
    "latest_version": "3.11.0",
    "current_version": "3.11.0",
    "installed": true,
    "auto_update": false
  }
}

错误代码：

• software_not_found：软件不在数据库中
• invalid_input：输入验证失败

📋 支持的软件

⚙️ 需求

• Python 3.10+
• MCP兼容客户端（克劳德桌面等）
• 媒染剂>=2.0.0
• python dotenv>=1.0.0

▶️ 作为本地MCP服务器运行

安装

1. 克隆存储库：

git clone <repository-url>
cd software

2. 安装依赖项：

pip install -r requirements.txt

3. 配置克劳德桌面MCP：

创建或编辑 ~/AppData/Roaming/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "software-management": {
      "command": "python",
      "args": ["/absolute/path/to/software/main.py"]
    }
  }
}

4. 重新启动克劳德桌面

本地测试

python -m pytest tests/

🧾 错误代码参考

MCP服务器返回结构化错误代码，用于程序错误处理：

🧰 故障排除

1） 安装失败，显示“找不到软件”

症状：

{
  "ok": false,
  "error": {
    "code": "software_not_found",
    "message": "Software 'xyz' not found in database"
  }
}

修复：

• 检查软件名称拼写（不区分大小写）
• 使用 list_installed_software 查看可用选项
• 验证上表中支持的软件

2） 更新失败，显示“已更新”

症状：

{
  "ok": false,
  "error": {
    "code": "up_to_date",
    "message": "Software 'python' is already up to date (v3.11.0)"
  }
}

修复：

• 这是当前软件的预期行为
• 无需操作

3） 未知任务的建议返回为空

症状：

{
  "ok": false,
  "error": {
    "code": "software_not_found",
    "hint": "Available tasks: web development, data science, ..."
  }
}

修复：

• 使用列表中支持的任务名称
• 任务名称不区分大小写
• 使用建议文档查看所有任务

4） 注册表操作失败

症状：

{
  "ok": false,
  "error": {
    "code": "registry_error",
    "message": "Error saving registry"
  }
}

修复：

• 验证项目目录中的文件权限
• 检查可用磁盘空间
• 确保 software_registry.json 未损坏
• 删除要重置的注册表文件（将在下次操作时重新创建）

📊 软件注册表

系统保持持久 software_registry.json 跟踪的文件：

• 已安装的软件和版本
• 安装日期
• 自动更新首选项

注册表示例：

{
  "installed_software": {
    "python": {
      "version": "3.11.0",
      "installed_date": "2026-02-18T10:30:00.123456",
      "auto_update": false
    },
    "git": {
      "version": "2.43.0",
      "installed_date": "2026-02-18T10:35:00.654321",
      "auto_update": true
    }
  }
}

🔁 工作流示例

1. 发现任务的建议：

   复制

   Call: get_recommendations("web development")
   Result: Receive list of recommended software
   

2. 安装推荐的软件：

   复制

   Call: install_software("python")
   Call: install_software("nodejs")
   

3. 列出已安装的软件：

   复制

   Call: list_installed_software()
   Result: View all installed programs and versions
   

4. 检查更新：

   复制

   Call: check_updates()
   Result: See available updates
   

5. 更新单个软件：

   复制

   Call: update_software("python")
   Result: Update to latest version
   

6. 启用自动更新：

   复制

   Call: set_auto_update("python", true)
   Result: Enable automatic updates
   

🚧 未来改进

以下功能将进一步增强服务器：

• 批量操作：一次安装/更新多个软件
• 依赖解析：自动安装软件依赖项
• 存储库集成：支持自定义软件存储库
• 预定更新：类似Cron的自动更新调度
• 健康检查：验证安装完整性和功能
• 回滚：恢复到以前的软件版本
• 配置描述文件：保存和恢复系统配置
• 多语言支持：本地化消息和文档
• 云同步：跨机器同步安装
• 通知：成功/失败操作的警报

📄 许可证

本项目按原样提供，用于软件管理和自动化目的。

项目：MCP-软件管理
版本: 1.0.0
最后更新：2026年2月
建筑：分层MCP服务器
状态：生产就绪

#� �m�c�p� � �