{"_id":"@aveq-research/surfmeter-mcp","_rev":"2-3c09ecc22a8e135071f8ead1b9210553","name":"@aveq-research/surfmeter-mcp","dist-tags":{"latest":"0.2.1"},"versions":{"0.2.0":{"name":"@aveq-research/surfmeter-mcp","version":"0.2.0","license":"MIT","_id":"@aveq-research/surfmeter-mcp@0.2.0","maintainers":[{"name":"slhck","email":"werner.robitza@gmail.com"},{"name":"fohletex","email":"fohletex@posteo.net"}],"bin":{"surfmeter-mcp":"build/index.js"},"dist":{"shasum":"be1e29ff04dc3da85256d79c06f5148a56f96008","tarball":"https://registry.npmjs.org/@aveq-research/surfmeter-mcp/-/surfmeter-mcp-0.2.0.tgz","fileCount":21,"integrity":"sha512-6ZFB8/l92cnJV6y/PAiU3WzbYQH89IOJVnSsB0smwHdstDYPn83J0aljZoT58uGPER33LJNOQx2PgWeTeVfvKQ==","signatures":[{"sig":"MEUCIQD6bht3rHJzYkYVNYPqxJEMJAEEeUoZMu7U0bxs4FepKAIgMn1aOyR+3vr28GM49aHXOfqn+/i12CB17Bu88r60GqI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":94842},"type":"module","_from":"file:aveq-research-surfmeter-mcp-0.2.0.tgz","engines":{"node":">=20"},"scripts":{"test":"vitest run","build":"tsc && chmod 755 build/index.js","check":"tsc --noEmit","format":"biome format --write .","test:all":"pnpm format:check && pnpm check && pnpm test && pnpm build","format:check":"biome format .","test:integration":"vitest run test/integration"},"_npmUser":{"name":"slhck","email":"werner.robitza@gmail.com"},"_resolved":"/private/var/folders/3h/9h8lqbnx0p372m8qh7fpd1dh0000gn/T/78b4eb60082164abf8207db3c44108a9/aveq-research-surfmeter-mcp-0.2.0.tgz","_integrity":"sha512-6ZFB8/l92cnJV6y/PAiU3WzbYQH89IOJVnSsB0smwHdstDYPn83J0aljZoT58uGPER33LJNOQx2PgWeTeVfvKQ==","_npmVersion":"11.12.1","description":"MCP server for the AVEQ Surfmeter management API","directories":{},"_nodeVersion":"24.7.0","dependencies":{"zod":"^4.4.3","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.1.10","typescript":"^7.0.2","@types/node":"^24.10.0","@biomejs/biome":"2.4.7"},"_npmOperationalInternal":{"tmp":"tmp/surfmeter-mcp_0.2.0_1784919350477_0.6383608423631288","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"_id":"@aveq-research/surfmeter-mcp@0.2.1","bin":{"surfmeter-mcp":"build/index.js"},"bugs":{"url":"https://github.com/aveq-research/surfmeter-mcp/issues"},"dist":{"shasum":"cb853ffbdcb6fd95225987dab13252923cfe3127","tarball":"https://registry.npmjs.org/@aveq-research/surfmeter-mcp/-/surfmeter-mcp-0.2.1.tgz","fileCount":24,"integrity":"sha512-PmaOQtO9p+f3CJJ6OxuaqWw/apk2DbCFKEK52YNumlLFI//urapl1fEilNwzTR/mZQAgndMURJVpAzFFIDdMGg==","signatures":[{"sig":"MEUCIB0YHtSkdp5qNhXT7rm/T80vo+AfFt7+00Fs/E0UusQkAiEAqZeWZdkAgZiwqw2fVlqseBa57pX72GI7dIpmm7WN7M8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDUnt9jp8pS+48rKzhTwfQEUOkx9Lwm/SvE+hRLl0vB+wIhAKTaMRjLrhG4vTQ30kmRv1O4YSxndn3pFF6ZL2bnUEr6"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aveq-research%2fsurfmeter-mcp@0.2.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":111492},"name":"@aveq-research/surfmeter-mcp","type":"module","engines":{"node":">=20"},"gitHead":"b1906a2dde7ee12f2e503b398b48c212b21503f5","license":"MIT","scripts":{"test":"vitest run","build":"tsc && chmod 755 build/index.js","check":"tsc --noEmit","format":"biome format --write .","prepack":"pnpm build","test:all":"pnpm format:check && pnpm check && pnpm test && pnpm build","format:check":"biome format .","test:integration":"vitest run test/integration"},"version":"0.2.1","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:f73e60bd-dfe0-4096-8bba-65196eaa0315"}},"homepage":"https://github.com/aveq-research/surfmeter-mcp#readme","repository":{"url":"git+https://github.com/aveq-research/surfmeter-mcp.git","type":"git"},"_npmVersion":"12.0.2","description":"MCP server for the AVEQ Surfmeter management API","directories":{},"maintainers":[{"name":"slhck","email":"werner.robitza@gmail.com"},{"name":"fohletex","email":"fohletex@posteo.net"}],"_nodeVersion":"24.20.0","dependencies":{"zod":"^4.4.3","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"packageManager":"pnpm@10.28.2","devDependencies":{"vitest":"^4.1.10","typescript":"^7.0.2","@types/node":"^24.10.0","@biomejs/biome":"2.4.7"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/surfmeter-mcp_0.2.1_1789549377476_0.08670247553210553"}}},"time":{"created":"2026-07-24T18:55:50.210Z","modified":"2026-09-16T09:02:58.110Z","0.2.0":"2026-07-24T18:55:50.617Z","0.2.1":"2026-09-16T09:02:57.556Z"},"license":"MIT","description":"MCP server for the AVEQ Surfmeter management API","maintainers":[{"name":"slhck","email":"werner.robitza@gmail.com"},{"name":"fohletex","email":"fohletex@posteo.net"}],"readme":"# Surfmeter MCP Server\n\nA 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.\n\n## Requirements\n\n- Node.js 20 or newer\n- A Surfmeter management API key beginning with `client_admin-`\n- A reachable Surfmeter server\n\n## Installation\n\nInstall the MCP server globally:\n\n```bash\npnpm add --global @aveq-research/surfmeter-mcp\n```\n\n## Configuration\n\nThe server requires two environment variables:\n\n- `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`.\n- `API_KEY`: A Surfmeter management API key. It is sent in the `X-API-KEY` request header.\n- `API_TIMEOUT_MS`: Optional request timeout in milliseconds. The default is 30000.\n\nDo not put a real key in source control. `.env` is ignored, but MCP clients should normally inject the values through their server configuration.\n\n## MCP client configuration\n\nConfigure your MCP client to launch the installed `surfmeter-mcp` executable:\n\n```json\n{\n  \"mcpServers\": {\n    \"surfmeter\": {\n      \"command\": \"surfmeter-mcp\",\n      \"env\": {\n        \"API_ENDPOINT\": \"https://surfmeter-server.demo-analytics.aveq.info\",\n        \"API_KEY\": \"client_admin-replace-me\"\n      }\n    }\n  }\n}\n```\n\n## Tool surface\n\nThe server advertises ten tools. Five common operations are promoted directly:\n\n- `surfmeter_get_clients`: list a bounded page of clients or get one client\n- `surfmeter_update_client`: update client labels, tags, or groups\n- `surfmeter_search_measurements`: query and aggregate measurements\n- `surfmeter_search_anomalies`: query and aggregate anomaly episodes\n- `surfmeter_get_system_status`: read server metadata, license usage, fleet health, client status history, detection thresholds, or AI status\n\nThe complete management API remains available through a searchable internal action catalog:\n\n- `surfmeter_search_actions`: find operations from a natural-language intent\n- `surfmeter_describe_action`: retrieve one operation's exact parameter schema\n- `surfmeter_execute_read_action`: execute discovered read-only operations\n- `surfmeter_execute_write_action`: execute discovered non-destructive mutations\n- `surfmeter_execute_destructive_action`: execute deletes, revocations, merges, and client disabling\n\nFor example:\n\n```json\n{\n  \"query\": \"create a registration key\",\n  \"category\": \"write\"\n}\n```\n\nThe 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:\n\n```json\n{\n  \"action_id\": \"surfmeter_create_registration_key\",\n  \"params\": {\n    \"comment\": \"Video probes\",\n    \"capability_id\": 12\n  }\n}\n```\n\nThe 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.\n\nThe 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.\n\nClient 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.\n\nFleet-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.\n\nMagic-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.\n\n## Elasticsearch searches\n\n`surfmeter_search_measurements` and `surfmeter_search_anomalies` accept Elasticsearch Query DSL under `body`.\n\nMeasurement searches also accept `index_scope` with `web`, `video`, `network`, `speedtest`, `conferencing`, or `gaming` to avoid searching unrelated index families.\n\nSupplementary 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`.\n\nUse `.keyword` for exact matching, aggregations, and sorting on text fields:\n\n```json\n{\n  \"body\": {\n    \"size\": 0,\n    \"query\": {\n      \"term\": {\n        \"type.keyword\": \"VideoMeasurement\"\n      }\n    },\n    \"aggs\": {\n      \"by_client\": {\n        \"terms\": {\n          \"field\": \"client_label.keyword\"\n        }\n      }\n    }\n  }\n}\n```\n\nThe server parses normal JSON and Elasticsearch NDJSON scroll responses. Prefer server-side filtering and aggregation to downloading and filtering large datasets in the agent.\n\n## Agent skill\n\nThe 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.\nSkills 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.\n\n## Development\n\nSee [DEVELOPERS.md](DEVELOPERS.md) for contributor setup, build instructions, implementation notes, and testing.\n","readmeFilename":"README.md","homepage":"https://github.com/aveq-research/surfmeter-mcp#readme","repository":{"url":"git+https://github.com/aveq-research/surfmeter-mcp.git","type":"git"},"bugs":{"url":"https://github.com/aveq-research/surfmeter-mcp/issues"}}