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。请确保您使用的Node.js版本支持ES模块（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 桌面版

在您的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: (可选) 分页控制，包括限制和偏移量

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文件。