# Surfmeter MCP Server

A Model Context Protocol server for the AVEQ Surfmeter management API. It exposes typed tools for clients, measurements, anomalies, groups, ISPs, users, keys, capabilities, settings, license usage, and the built-in AI assistant.

## Requirements

- Node.js 20 or newer
- A Surfmeter management API key beginning with `client_admin-`
- A reachable Surfmeter server

## Installation

Install the MCP server globally:

```bash
pnpm add --global @aveq-research/surfmeter-mcp
```

## Configuration

The server requires two environment variables:

- `API_ENDPOINT`: Either the Surfmeter server origin, such as `https://surfmeter-server.demo-analytics.aveq.info`, or the complete management endpoint, such as `https://surfmeter-server.demo-analytics.aveq.info/client_admin_api/v1`.
- `API_KEY`: A Surfmeter management API key. It is sent in the `X-API-KEY` request header.
- `API_TIMEOUT_MS`: Optional request timeout in milliseconds. The default is 30000.

Do not put a real key in source control. `.env` is ignored, but MCP clients should normally inject the values through their server configuration.

## MCP client configuration

Configure your MCP client to launch the installed `surfmeter-mcp` executable:

```json
{
  "mcpServers": {
    "surfmeter": {
      "command": "surfmeter-mcp",
      "env": {
        "API_ENDPOINT": "https://surfmeter-server.demo-analytics.aveq.info",
        "API_KEY": "client_admin-replace-me"
      }
    }
  }
}
```

## Tool surface

The server advertises ten tools. Five common operations are promoted directly:

- `surfmeter_get_clients`: list a bounded page of clients or get one client
- `surfmeter_update_client`: update client labels, tags, or groups
- `surfmeter_search_measurements`: query and aggregate measurements
- `surfmeter_search_anomalies`: query and aggregate anomaly episodes
- `surfmeter_get_system_status`: read server metadata, license usage, fleet health, client status history, detection thresholds, or AI status

The complete management API remains available through a searchable internal action catalog:

- `surfmeter_search_actions`: find operations from a natural-language intent
- `surfmeter_describe_action`: retrieve one operation's exact parameter schema
- `surfmeter_execute_read_action`: execute discovered read-only operations
- `surfmeter_execute_write_action`: execute discovered non-destructive mutations
- `surfmeter_execute_destructive_action`: execute deletes, revocations, merges, and client disabling

For example:

```json
{
  "query": "create a registration key",
  "category": "write"
}
```

The result identifies the action, its parameter names, and the correct executor. Use `surfmeter_describe_action` when the exact schema is needed, then pass the selected action to that executor:

```json
{
  "action_id": "surfmeter_create_registration_key",
  "params": {
    "comment": "Video probes",
    "capability_id": 12
  }
}
```

The server validates `params` against the selected action's internal Zod schema. It rejects action/executor category mismatches. Read, write, and destructive executors have separate MCP annotations so compatible hosts can apply the correct confirmation behavior.

The internal catalog covers clients, notification preferences, fleet and system health, groups, ISP contracts, ISPs, users, API keys, registration keys, capabilities, measurements and supplementary reports, anomalies, tuning overrides, settings, detection thresholds, license usage, and Surfmeter's built-in AI assistant.

Client list responses default to 20 records and accept `offset` and `limit` (maximum 25). They include `total`, `returned`, `has_more`, and `next_offset` under `pagination`. Pass `next_offset` as the next call's `offset`; a null value marks the final page. Single-client lookup with `id` is unchanged.

Fleet-health responses use the same bounded pagination and can be filtered by `healthy`, `warning`, `critical`, or `unknown` state. Per-client system-status history defaults to 20 records and accepts a maximum of 100, with optional `start_time` and `end_time` filters.

Magic-link and session endpoints are intentionally not exposed. They are browser authentication mechanisms and are neither needed nor appropriate when the MCP server already authenticates with a management API key.

## Elasticsearch searches

`surfmeter_search_measurements` and `surfmeter_search_anomalies` accept Elasticsearch Query DSL under `body`.

Measurement searches also accept `index_scope` with `web`, `video`, `network`, `speedtest`, `conferencing`, or `gaming` to avoid searching unrelated index families.

Supplementary P.1203, web network-performance, and Lightweight Video Player reports use the parent measurement's numeric `id` field. Do not pass the subtype fields such as `video_measurement_id` or `web_measurement_id`.

Use `.keyword` for exact matching, aggregations, and sorting on text fields:

```json
{
  "body": {
    "size": 0,
    "query": {
      "term": {
        "type.keyword": "VideoMeasurement"
      }
    },
    "aggs": {
      "by_client": {
        "terms": {
          "field": "client_label.keyword"
        }
      }
    }
  }
}
```

The server parses normal JSON and Elasticsearch NDJSON scroll responses. Prefer server-side filtering and aggregation to downloading and filtering large datasets in the agent.

## Agent skill

The companion [Surfmeter skills repository](https://github.com/aveq-research/surfmeter-skills) teaches compatible coding agents how to invoke the API directly, and how to construct Elasticsearch requests.
Skills are orthogonal to MCP servers. You may choose to not load an MCP server's heavy tool definition in all sessions; skills are a good, lightweight alternative to that.

## Development

See [DEVELOPERS.md](DEVELOPERS.md) for contributor setup, build instructions, implementation notes, and testing.