Pdq Connect MCP

PDQ连接MCP服务器

模型上下文协议（MCP）服务器，提供用于与PDQ Connect API交互的工具。此服务器使Claude和其他MCP客户端能够通过PDQ Connect管理设备、组、包和部署。

特性

• 设备管理：通过过滤、排序和分页列出和检索详细的设备信息
• 组管理：列出和筛选设备组
• 包管理：浏览可用包并检索包详细信息
• 部署操作：将包部署到目标设备或组
• 高级过滤：支持字符串运算符（以开头、包含、以结尾）、日期时间比较、整数比较和布尔过滤器
• 分页：处理具有可配置页面大小的大型数据集（每页最多100个）
• 灵活包括：检索嵌套设备数据（磁盘、驱动程序、功能、网络、处理器、更新、软件、Active Directory信息）

先决条件

• Node.js 18.0.0或更高版本
• PDQ Connect API承载令牌（从https://app.pdq.com)

安装

1. 克隆或下载此存储库
2. 导航到项目目录
3. 安装依赖项：

npm install

1. 构建TypeScript代码：

npm run build

配置

环境变量

创建一个 .env 在项目根目录中创建文件或设置环境变量：

PDQ_API_TOKEN=your_bearer_token_here

Claude桌面配置

将服务器添加到Claude Desktop配置文件中：

视窗: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "pdq-connect": {
      "command": "node",
      "args": ["/path/to/pdq-connect-mcp/dist/index.js"],
      "env": {
        "PDQ_API_TOKEN": "your_bearer_token_here"
      }
    }
  }
}

注： 替换 /path/to/pdq-connect-mcp 安装的实际路径：

• 视窗：使用反斜杠，例如。， C:\\Users\\YourName\\mcp\\pdq-connect-mcp\\dist\\index.js
• macOS/Linux：使用正斜杠，例如。， /home/username/mcp/pdq-connect-mcp/dist/index.js 或 ~/mcp/pdq-connect-mcp/dist/index.js

VS代码MCP扩展配置

创建或更新 .vscode/mcp.json:

{
  "servers": {
    "pdq-connect": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/pdq-connect-mcp/dist/index.js"],
      "env": {
        "PDQ_API_TOKEN": "your_bearer_token_here"
      }
    }
  }
}

注： 替换 /path/to/pdq-connect-mcp 使用您的实际安装路径（有关特定于平台的格式，请参阅上面的注释）。

可用工具

1.pdq_list_devices

从PDQ Connect列出设备，包括可选的过滤、排序、分页和包含。

参数：

• includes （可选）：以逗号分隔的嵌套数据列表（磁盘、驱动程序、功能、网络、处理器、更新、软件、activeDirectory、activeDirectoryGroups、customFields）
• group （可选）：按组ID筛选
• pageSize （可选）：页面大小（1-100，默认值：100）
• page （可选）：页码（默认：1）
• sort （可选）：使用可选的“Desc”后缀对camelCase中的字段进行排序（例如，“insertedAt”、“nameDesc”）
• filter （可选）：具有筛选条件的对象

筛选器示例：

{
  "filter": {
    "name": "^WIN",              // Starts with "WIN"
    "manufacturer": "~Dell",      // Contains "Dell"
    "os": "Windows 11$",          // Ends with "Windows 11"
    "memory": ">8589934592",      // Greater than 8GB
    "requireReboot": "true"       // Boolean exact match
  }
}

2.pdq_get_设备

按ID获取特定设备的详细信息。

参数：

• device_id （必填）：唯一设备ID

3.pdq_list_group

列出具有可选过滤、排序和分页功能的设备组。

参数：

• pageSize （可选）：页面大小（1-100，默认值：100）
• page （可选）：页码（默认：1）
• sort （可选）：camelCase中的排序字段
• filter （可选）：筛选对象（id、名称、来源、类型）

4.pdq_list_packages

列出具有可选过滤、排序和分页功能的可用包。

参数：

• pageSize （可选）：页面大小（1-100，默认值：100）
• page （可选）：页码（默认：1）
• sort （可选）：camelCase中的排序字段
• filter （可选）：筛选对象（名称、发布者、来源）

5.pdq_get-package

按ID获取特定包的详细信息，包括最新版本。

参数：

• package_id （必填）：唯一的包ID

6.pdq_deploy_package

将包版本部署到目标设备或组。

参数：

• package （必填）：包ID或包版本ID
• targets （必填）：逗号分隔的设备ID或组ID（例如，“设备-1，设备-2”）

备注：这是一个启动实际部署的写入操作。

过滤器操作员

字符串筛选器

• 无前缀：完全匹配
• ^：以（例如。， "^WIN" 匹配“Windows”、“WIN-PC”）
• ~：包含（例如。， "~Dell" 匹配“Dell股份有限公司”、“Dell Computer”）
• $：以（例如。， "11$" 匹配“Windows 11”）

日期时间过滤器

• 无前缀：完全匹配（ISO 8601格式）
• `：之后（例如。， ">2024-01-01T00:00:00.000000Z"`)

整数过滤器

• 无前缀：完全匹配
• ``：大于
• =：大于或等于

布尔过滤器

• "true" 或 "false" （字符串）

有效筛选字段

设备

• 字符串字段：架构、biosAssetTag、biosManufacturer、biosVersion、机箱、currentUser、dotNetVersions、系列、主机名、lastUser、lastUserShortName、macAddress、制造商、型号、名称、os、osFullName、osProductType、osVersion、powershellVersion、publicIpAddress、serialNumber、servicePack、sku、systemVersion、时区
• 日期时间字段：insertedAt，lastBootUpTime，osInstallDate，updatedAt
• 整数字段：freePercent，内存
• 布尔字段：requireReboot，smbVersionOne

群组

• 字符串字段：id、名称、来源、类型
• 日期时间字段: 插入

包裹

• 字符串字段：名称、发布者、来源

使用示例

示例1：列出所有Windows 11设备

List all devices running Windows 11 with their disk information

克劳德将致电：

{
  "tool": "pdq_list_devices",
  "arguments": {
    "filter": { "os": "~Windows 11" },
    "includes": "disks"
  }
}

示例2：获取特定设备详细信息

Show me details for device ID abc-123

克劳德将致电：

{
  "tool": "pdq_get_device",
  "arguments": {
    "device_id": "abc-123"
  }
}

示例3：查找需要重新启动的Dell设备

Find all Dell devices that require a reboot

克劳德将致电：

{
  "tool": "pdq_list_devices",
  "arguments": {
    "filter": {
      "manufacturer": "~Dell",
      "requireReboot": "true"
    }
  }
}

示例4：将包部署到组

Deploy package pkg-456 to group grp-789

克劳德将致电：

{
  "tool": "pdq_deploy_package",
  "arguments": {
    "package": "pkg-456",
    "targets": "grp-789"
  }
}

发展

构建

npm run build

监视模式（更改后自动重建）

npm run watch

直接运行

npm start

故障排除

错误：“未设置PDQ_API_TOKEN环境变量”

• 确保您已设置 PDQ_API_TOKEN 在您的环境中或 .env 文件
• 验证令牌是否为空或仅包含空格

错误：“身份验证失败”

• 检查您的持票人令牌是否有效
• 验证您是否有权访问PDQ Connect API
• 尝试从生成新令牌https://app.pdq.com

错误：“找不到资源”

• 验证设备/包/组ID是否存在
• 检查ID中的拼写错误

错误：“提供的参数无效”

• 查看筛选器字段名称和运算符
• 确保筛选器值与预期类型匹配
• 检查分页限制（最大页面大小：100）

服务器未出现在Claude Desktop中

• 更新配置后重新启动Claude Desktop
• 检查配置文件路径是否适合您的操作系统
• 验证路径 dist/index.js 绝对正确
• 检查Claude Desktop日志是否有错误

API 参考

此MCP服务器实现PDQ Connect API v1:

• 基本URL: https://app.pdq.com
• API文件：https://app.pdq.com/api/docs

安全说明

• 永远不要承诺你的 .env 文件或公开您的API令牌
• 承载令牌提供对您的PDQ Connect组织的完全访问权限
• 部署操作时要小心，因为它们会影响生产系统
• 如果可用于更安全的操作，请考虑使用只读令牌

许可证

麻省理工学院

贡献

欢迎投稿！请确保：

• TypeScript代码编译时没有错误
• 所有工具都遵循既定的模式
• 文档已针对新功能进行了更新
• 错误处理全面

支持

对于以下问题：

• 此MCP服务器：在存储库中打开问题
• PDQ连接API：联系PDQ支持
• MCP协议：参见https://modelcontextprotocol.io