PlainSignal MCP Server

PlainSignal MCP 服务

这是一个用于 PlainSignal 分析数据的模型上下文协议（MCP）服务实现。它提供用于通过 MCP 协议获取分析报告和指标的工具。

设置

安装

从 npm 安装（推荐）

# Install globally
npm install -g @plainsignal/plainsignal-mcp

# Or install locally in your project
npm install @plainsignal/plainsignal-mcp

从源代码安装

1. 克隆此仓库
2. 安装依赖项：

npm install

此项目使用 ES 模块，而不是 CommonJS。请确保使用支持 ES 模块的 Node.js 版本（Node.js 14+）。

使用方法

从 npm 安装时

# If installed globally
plainsignal-mcp --token <your_access_token>

# If installed locally
npx plainsignal-mcp --token <your_access_token>

# Or using an environment variable
export PLAINSIGNAL_TOKEN=<your_access_token>
plainsignal-mcp

从源代码使用时

使用访问令牌运行服务：

node src/index.js --token <your_access_token>

# Or using an environment variable
export PLAINSIGNAL_TOKEN=<your_access_token>
node src/index.js

你也可以指定自定义 API 基础 URL：

node src/index.js --token <your_access_token> --api-base-url <api_base_url>

或者使用简短格式：

node src/index.js -t <your_access_token> -u <api_base_url>

也可以将访问令牌和 API 基础 URL 设置为环境变量，然后使用测试脚本：

export PLAINSIGNAL_TOKEN=your_access_token
export API_BASE_URL=https://app.plainsignal.com/api/v1
./test.sh

默认情况下，服务会连接到 https://app.plainsignal.com/api/v1。

MCP 服务配置

Claude Desktop

将此代码片段添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "plainsignal": {
      "command": "npx -y @plainsignal/plainsignal-mcp",
      "env": {
        "PLAINSIGNAL_TOKEN": "<YOUR_PLAINSIGNAL_TOKEN>"
      }
    }
  }
}

可用工具

该服务提供以下工具：

getReport

获取指定域名和时间段的分析报告。

参数：

• organizationID：组织 ID
• domainID：域名 ID
• periodFrom：报告开始日期时间，采用 RFC3339 格式
• periodTo：报告结束日期时间，采用 RFC3339 格式
• periodSelection：时间段类型（m：月，y：年，d：日）
• aggregationWindow：数据聚合时间窗口（h：小时，d：天）
• filters：（可选）以键值对形式提供的筛选条件列表

getSubReport

获取分析数据中特定方面的详细指标。

参数：

• organizationID：组织 ID
• domainID：域名 ID
• periodFrom：报告开始日期时间，采用 RFC3339 格式
• periodTo：报告结束日期时间，采用 RFC3339 格式
• periodSelection：时间段类型（m：月，y：年，d：日）
• aggregationWindow：数据聚合时间窗口（h：小时，d：天）
• subReportType：报告类型（1：页面，2：入口页面等）
• filters：（可选）以键值对形式提供的筛选条件列表
• pagination：（可选）分页控制项，包含 limit 和 offset

API 参考

此服务与 PlainSignal API 通信。默认情况下，它会连接到 https://app.plainsignal.com/api/v1，但你可以通过以下几种方式配置 API 端点：

1. 使用 --api-base-url 命令行选项：

   node src/index.js --token <your_token> --api-base-url https://app.plainsignal.com/api/v1
   

2. 设置 API_BASE_URL 环境变量：

   export API_BASE_URL=https://app.plainsignal.com/api/v1
   

3. 以编程方式实例化服务时，将自定义 API 基础 URL 传递给构造函数：

   const server = new PlainSignalStdioServer(token, 'https://app.plainsignal.com/api/v1');
   

开发者指南

此服务使用 MCP SDK 实现，并通过 STDIO 通信。

示例

项目提供了一个示例客户端，用于演示如何使用 MCP 服务：

# Set your access token
export PLAINSIGNAL_TOKEN=your_access_token

# Run the example client
npm run example

或者运行资源示例客户端：

# Set your access token
export PLAINSIGNAL_TOKEN=your_access_token

# Run the resources example client
npm run resources-example

示例客户端演示了如何：

1. 连接到 MCP 服务
2. 列出可用工具
3. 使用示例参数调用 getReport 工具
4. 处理并显示结果

资源示例客户端演示了如何：

1. 连接到 MCP 服务
2. 列出可用资源
3. 读取 listDomains 资源
4. 处理并显示结果

许可证

此项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。