Apt MCP 服务器

基于TypeScript的模型上下文协议（MCP）服务器，用于控制Linux上的apt包管理器。设计用于与AI代理（例如Cursor、Claude Desktop、Windsurf）和开发者工具集成，它通过系统原生的apt和dpkg二进制文件（具有sudo权限）提供安装、卸载、更新和查询apt包的工具。

---

特性

• 通过MCP工具安装、卸载、更新和查询apt包
• 所有操作假设安全且无需密码的sudo
• 输入验证和强大的错误处理
• 所有工具具有一致且易于阅读的输出
• 设计用于标准I/O传输（默认用于本地AI代理集成）

---

安装与设置

1. 克隆仓库：

   git clone <your-repo-url>
   cd popos-control-mcp
   

2. 安装依赖项：

   npm install
   

3. 构建项目：

   npm run build
   

4. 运行服务器（标准I/O传输）：

   npm run dev
   # 或
   npm start
   

注意： 该服务器假定用户对apt操作具有无需密码的sudo权限。

---

工具与API端点

所有工具都通过MCP暴露，并可由AI代理或客户端调用。每个工具返回一个纯文本响应，包括摘要、标准输出、标准错误和日志（如果有）。

1. installAptPackage

• 描述： 安装一个或多个apt包。
• 参数：
  • packages: 包名数组（例如，["curl", "git"]）
• 示例输入：

  { "packages": ["curl"] }
  

• 示例输出：

  结果：成功
  摘要：apt安装成功：curl
  [标准输出]
  ...
  [标准错误]
  ...
  

2. removeAptPackage

• 描述： 卸载一个或多个apt包。
• 参数：
  • packages: 包名数组
• 示例输入：

  { "packages": ["curl"] }
  

• 示例输出：

  结果：成功
  摘要：apt卸载成功：curl
  [标准输出]
  ...
  [标准错误]
  ...
  

3. queryAptPackageStatus

• 描述： 查询包是否已安装、可用或可升级。
• 参数：
  • package: 包名（字符串）
• 示例输入：

  { "package": "curl" }
  

• 示例输出：

  结果：成功
  摘要：包curl的状态：已安装=已安装，可升级=否，可用=可用
  [标准输出]
  包：curl
  已安装：已安装
  可升级：否
  可用：可用
  

4. updateAptPackages

• 描述： 更新apt包列表并升级所有包。
• 参数： 无
• 示例输入：

  {}
  

• 示例输出：

  结果：成功
  摘要：apt更新和升级完成。
  [标准输出]
  apt更新的标准输出：
  ...
  apt升级的标准输出：
  ...
  [标准错误]
  ...
  

5. listUpgradableAptPackages

• 描述： 列出所有可升级的apt包。
• 参数： 无
• 示例输入：

  {}
  

• 示例输出：

  结果：成功
  摘要：列出可升级的包成功。
  [标准输出]
  ...
  [标准错误]
  ...
  

6. upgradeSpecificAptPackage

• 描述： 升级特定的apt包。
• 参数：
  • package: 包名（字符串）
• 示例输入：

  { "package": "curl" }
  

• 示例输出：

  结果：成功
  摘要：仅升级apt包成功：curl
  [标准输出]
  ...
  [标准错误]
  ...
  

---

示例用法

命令行（标准I/O传输）

您可以使用MCP CLI测试服务器，或者通过连接AI代理（如Cursor、Claude Desktop）进行测试。

Node.js 示例

const { Client } = require("@modelcontextprotocol/sdk/client");
const { StdioClientTransport } = require("@modelcontextprotocol/sdk/client/stdio");

const client = new Client({ name: "test-client", version: "1.0.0" });
const transport = new StdioClientTransport();

(async () => {
  await client.connect(transport);
  const result = await client.callTool("installAptPackage", { packages: ["curl"] });
  console.log(result);
})();

---

错误处理与故障排除

• 所有错误以一致的格式返回，带有结果：错误和摘要。
• 常见错误原因：
  • 无效包名：检查拼写和允许的字符
  • 包未找到：确保包存在于您的存储库中
  • 权限被拒绝：确保配置了无需密码的sudo
  • apt锁：服务器会自动重试一次，但如果错误持续，请等待并再次尝试
• 示例错误输出：

  结果：错误
  摘要：apt安装失败：E: 无法找到包notarealpackage
  [标准输出]
  ...
  [标准错误]
  E: 无法找到包notarealpackage
  

---

常见问题解答

问：服务器需要无需密码的sudo吗？ 答：是的，所有apt/dpkg命令都使用sudo执行，并假设没有密码提示。

问：服务器使用什么传输方式？ 答：默认使用标准I/O，便于与本地AI代理和工具集成。

问：我可以远程使用这个服务器吗？ 答：您可以将其适应HTTP/SSE传输，但建议本地/代理使用标准I/O。

问：如何添加新工具？ 答：在src/index.ts中添加一个新的server.addTool块，遵循现有模式。

---

许可证

MIT