mirror of
https://github.com/hyperdxio/hyperdx
synced 2026-04-21 13:37:15 +00:00
9781ae6387
## Summary Adds an MCP (Model Context Protocol) server to the HyperDX API, enabling AI assistants (Claude, Cursor, OpenCode, etc.) to query observability data, manage dashboards, and explore data sources directly via standardized tool calls. Key changes: - **MCP server** (`packages/api/src/mcp/`) — Streamable HTTP transport at `/api/mcp`, authenticated via Personal API Access Key - **Tools** — `hyperdx_list_sources`, `hyperdx_query`, `hyperdx_get_dashboard`, `hyperdx_save_dashboard`, `hyperdx_delete_dashboard`, `hyperdx_query_tile` - **Dashboard prompts** — Detailed prompt templates that guide LLMs in generating valid, high-quality dashboards - **Shared logic** — Refactored dashboard validation/transformation out of the external API router into reusable utils (`packages/api/src/routers/external-api/v2/utils/dashboards.ts`) - **Documentation** — `MCP.md` with setup instructions for Claude Code, OpenCode, Cursor, MCP Inspector, and other clients - **Tests** — Unit tests for dashboard tools, query tools, tracing, and response trimming ### Screenshots https://github.com/user-attachments/assets/8c5aa582-c79e-47e0-8f75-e03feabdf8a6 ### How to test locally 1. Start the dev stack: `yarn dev` 2. Connect an MCP client (e.g. MCP Inspector): ```bash cd packages/api && yarn dev:mcp ``` Then configure the inspector: - **Transport Type:** Streamable HTTP - **URL:** `http://localhost:8080/api/mcp` - **Header:** `Authorization: Bearer <your-personal-access-key>` - Click **Connect** 3. Alternatively, connect via Claude Code or OpenCode: ```bash claude mcp add --transport http hyperdx http://localhost:8080/api/mcp \ --header "Authorization: Bearer <your-personal-access-key>" ``` 4. Try listing sources, querying data, or creating/updating a dashboard through the connected AI assistant. 5. Run unit tests: ```bash cd packages/api && yarn ci:unit ``` ### References - Linear Issue: HDX-3710
152 lines
4.6 KiB
Markdown
152 lines
4.6 KiB
Markdown
# Contributing
|
|
|
|
## Architecture Overview
|
|
|
|
|
|
|
|
Service Descriptions:
|
|
|
|
- OpenTelemetry Collector (otel-collector): Receives OpenTelemetry data from
|
|
instrumented applications and forwards it to ClickHouse for storage. Includes
|
|
OpAMP supervisor that dynamically pulls configuration from HyperDX API.
|
|
- ClickHouse (ch-server): ClickHouse database, stores all telemetry.
|
|
- MongoDB (db): Stores user/saved search/alert/dashboard data.
|
|
- HyperDX API (api): Node.js API, executes ClickHouse queries on behalf of the
|
|
frontend and serves the frontend. serves the frontend. Can also run alert
|
|
checker.
|
|
- HyperDX UI (app): Next.js frontend, serves the UI.
|
|
|
|
## Development
|
|
|
|
Pre-requisites:
|
|
|
|
- Docker
|
|
- Node.js (`>=22`)
|
|
- Yarn (v4)
|
|
|
|
You can get started by deploying a complete development stack in dev mode.
|
|
|
|
```bash
|
|
yarn dev
|
|
```
|
|
|
|
This will start the Node.js API, Next.js frontend locally and the OpenTelemetry
|
|
collector and ClickHouse server in Docker.
|
|
|
|
Each worktree automatically gets unique ports so multiple developers (or agents)
|
|
can run `yarn dev` simultaneously without conflicts. A dev portal at
|
|
http://localhost:9900 auto-starts and shows all running stacks with their
|
|
assigned ports. Check the portal to find the URL for your instance.
|
|
|
|
To stop the stack:
|
|
|
|
```bash
|
|
yarn dev:down
|
|
```
|
|
|
|
To enable self-instrumentation and demo logs, you can set the `HYPERDX_API_KEY`
|
|
to your ingestion key (visit the Team settings page after creating your account).
|
|
|
|
To do this, create a `.env.local` file in the root of the project and add the
|
|
following:
|
|
|
|
```sh
|
|
HYPERDX_API_KEY=<YOUR_INGESTION_API_KEY_HERE>
|
|
```
|
|
|
|
Then restart the stack using `yarn dev`.
|
|
|
|
The core services are all hot-reloaded, so you can make changes to the code and
|
|
see them reflected in real-time.
|
|
|
|
### Volumes
|
|
|
|
The development stack mounts volumes locally for persisting storage under
|
|
`.volumes`. Each worktree gets its own volume directory (e.g.
|
|
`.volumes/ch_data_dev_89`). Clear the `.volumes` directory to reset ClickHouse
|
|
and MongoDB storage.
|
|
|
|
### Windows
|
|
|
|
If you are running WSL 2, Hot module reload on Nextjs (Frontend) does not work
|
|
out of the box on windows when run natively on docker. The fix here is to open
|
|
project directory in WSL and run the above docker compose commands directly in
|
|
WSL. Note that the project directory should not be under /mnt/c/ directory. You
|
|
can clone the git repo in /home/{username} for example.
|
|
|
|
To develop from WSL, follow instructions
|
|
[here](https://code.visualstudio.com/docs/remote/wsl).
|
|
|
|
## Testing
|
|
|
|
All test environments use slot-based port isolation, so they can run
|
|
simultaneously with the dev stack and across multiple worktrees.
|
|
|
|
### E2E Tests
|
|
|
|
E2E tests run against a full local stack (MongoDB + ClickHouse + API). Docker
|
|
must be running.
|
|
|
|
```bash
|
|
# Run all E2E tests
|
|
make e2e
|
|
|
|
# Run a specific spec file (dev mode: hot reload, containers kept running)
|
|
make dev-e2e FILE=search
|
|
|
|
# Run with grep pattern
|
|
make dev-e2e FILE=search GREP="filter"
|
|
|
|
# Run via script directly for more control
|
|
./scripts/test-e2e.sh --ui --last-failed
|
|
```
|
|
|
|
Tests live in `packages/app/tests/e2e/`. Page objects are in `page-objects/`,
|
|
shared components in `components/`.
|
|
|
|
### Integration Tests
|
|
|
|
```bash
|
|
# Build dependencies (run once before first test run)
|
|
make dev-int-build
|
|
|
|
# Run a specific test file
|
|
make dev-int FILE=checkAlerts
|
|
```
|
|
|
|
### Unit Tests
|
|
|
|
To run unit tests or update snapshots, you can go to the package you want (ex.
|
|
common-utils) to test and run:
|
|
|
|
```bash
|
|
yarn dev:unit
|
|
```
|
|
|
|
## AI-Assisted Development
|
|
|
|
HyperDX includes an [MCP server](https://modelcontextprotocol.io/) that lets AI assistants query observability data, manage dashboards, and
|
|
explore data sources. See [MCP.md](/MCP.md) for setup instructions.
|
|
|
|
The repo also ships with configuration for AI coding assistants that enables interactive browser-based E2E test generation and debugging via
|
|
the [Playwright MCP server](https://github.com/microsoft/playwright-mcp).
|
|
|
|
### Claude Code
|
|
|
|
The project includes agents and skills for test generation, healing, and planning under `.claude/`. These are loaded automatically when you open the project in Claude Code. No additional setup required.
|
|
|
|
### Cursor
|
|
|
|
A Playwright MCP server config is included at `.cursor/mcp.json`. To activate it:
|
|
|
|
1. Open **Cursor Settings → Tools & MCP**
|
|
2. The `playwright-test` server should appear automatically from the project config
|
|
3. Enable it
|
|
|
|
This gives Cursor's AI access to a live browser for test exploration and debugging.
|
|
|
|
## Additional support
|
|
|
|
If you need help getting started,
|
|
[join our Discord](https://discord.gg/FErRRKU78j) and we're more than happy to
|
|
get you set up!
|