From 9f347eee0613b9345c69fc529517ef3b203495f3 Mon Sep 17 00:00:00 2001 From: Eric Allam Date: Sun, 15 Mar 2026 22:18:10 +0000 Subject: [PATCH] docs(cli): Expand and improve the MCP server and dev CLI command Depends on #3224 --- docs/docs.json | 2 +- docs/management/query/dashboards.mdx | 4 + docs/management/query/schema.mdx | 4 + docs/mcp-introduction.mdx | 11 +++ docs/mcp-tools.mdx | 89 +++++++++++++++++++- docs/observability/query.mdx | 11 +-- docs/v3-openapi.yaml | 120 +++++++++++++++++++++++++++ 7 files changed, 234 insertions(+), 7 deletions(-) create mode 100644 docs/management/query/dashboards.mdx create mode 100644 docs/management/query/schema.mdx diff --git a/docs/docs.json b/docs/docs.json index 14d728e2db1..7b1fd6df201 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -323,7 +323,7 @@ }, { "group": "Query API", - "pages": ["management/query/execute"] + "pages": ["management/query/execute", "management/query/schema", "management/query/dashboards"] } ] }, diff --git a/docs/management/query/dashboards.mdx b/docs/management/query/dashboards.mdx new file mode 100644 index 00000000000..285e6c6e79b --- /dev/null +++ b/docs/management/query/dashboards.mdx @@ -0,0 +1,4 @@ +--- +title: "List dashboards" +openapi: "v3-openapi GET /api/v1/query/dashboards" +--- diff --git a/docs/management/query/schema.mdx b/docs/management/query/schema.mdx new file mode 100644 index 00000000000..eaf3d17271d --- /dev/null +++ b/docs/management/query/schema.mdx @@ -0,0 +1,4 @@ +--- +title: "Get query schema" +openapi: "v3-openapi GET /api/v1/query/schema" +--- diff --git a/docs/mcp-introduction.mdx b/docs/mcp-introduction.mdx index a00f3dda896..0ebbda607f7 100644 --- a/docs/mcp-introduction.mdx +++ b/docs/mcp-introduction.mdx @@ -14,6 +14,7 @@ The Trigger.dev MCP (Model Context Protocol) Server enables AI assistants to int - Get task information and trigger task runs - Deploy projects to different environments - Monitor run details and list runs with filtering options +- Query your data with TRQL and run built-in dashboard metrics ## Installation @@ -306,6 +307,7 @@ The `install-mcp` command supports these options: - `-p, --project-ref ` — Scope the MCP server to a specific project - `-t, --tag ` — CLI package version to use (default: latest) - `--dev-only` — Restrict to the dev environment only +- `--readonly` — Read-only mode. Hides write tools (`deploy`, `trigger_task`, `cancel_run`) so the AI cannot make changes to your account - `--yolo` — Install into all supported clients automatically - `--scope ` — `user`, `project`, or `local` - `--client ` — Install into specific client(s) @@ -336,6 +338,12 @@ Restrict to dev environment for a specific project: npx trigger.dev@latest install-mcp --dev-only --project-ref proj_abc123 ``` +Read-only mode (prevents AI from deploying or triggering tasks): + +```bash +npx trigger.dev@latest install-mcp --readonly +``` + To add these options to a manual config, append them to the `args` array: ```json @@ -358,6 +366,9 @@ Once installed, you can start using the MCP server by asking your AI assistant q - `"List all runs for my foobar task"` - `"Deploy my project to staging"` - `"Deploy my project to production"` +- `"How many runs failed in the last 7 days?"` +- `"Show me the overview dashboard metrics"` +- `"What tables can I query?"` ## Next Steps diff --git a/docs/mcp-tools.mdx b/docs/mcp-tools.mdx index fdcdb56f3d6..037d7e887ef 100644 --- a/docs/mcp-tools.mdx +++ b/docs/mcp-tools.mdx @@ -128,6 +128,93 @@ List all preview branches in the project. - `"What preview branches exist?"` - `"Show me preview deployments"` +## Profile Tools + +### whoami + +Show the current authenticated user, active CLI profile, email, and API URL. + +**Example usage:** +- `"Who am I logged in as?"` +- `"What profile am I using?"` + +### list_profiles + +List all configured CLI profiles and which one is currently active. + +**Example usage:** +- `"What profiles do I have?"` +- `"Show me my Trigger.dev profiles"` + +### switch_profile + +Switch the active CLI profile for this MCP session. This changes which Trigger.dev account and API URL are used for all subsequent tool calls. + +**Example usage:** +- `"Switch to my production profile"` +- `"Use the staging profile"` + +## Query and Analytics Tools + +### get_query_schema + +Get the schema for TRQL queries, including all available tables, their columns, data types, descriptions, and allowed values. Call this before using the query tool to understand what data is available. + +**Example usage:** +- `"What tables and columns can I query?"` +- `"Show me the query schema"` + +### query + +Execute a TRQL query against your Trigger.dev data. TRQL is a SQL-style query language for analyzing runs, metrics, and LLM usage. + +**Example usage:** +- `"How many runs failed in the last 7 days?"` +- `"Show me the top 10 most expensive tasks"` +- `"Query the average execution duration by task"` + +### list_dashboards + +List available built-in dashboards with their widgets. Each dashboard contains pre-built queries for common metrics. + +**Example usage:** +- `"What dashboards are available?"` +- `"Show me the dashboard widgets"` + +### run_dashboard_query + +Execute a single widget query from a built-in dashboard. Use `list_dashboards` first to see available dashboards and widget IDs. + +**Example usage:** +- `"Run the total runs widget from the overview dashboard"` +- `"Show me the LLM cost over time from the AI dashboard"` + +## Dev Server Tools + +### start_dev_server + +Start the Trigger.dev dev server (`trigger dev`) in the background. Waits up to 30 seconds for the worker to be ready. + +**Example usage:** +- `"Start the dev server"` +- `"Run trigger dev"` + +### stop_dev_server + +Stop the running Trigger.dev dev server. + +**Example usage:** +- `"Stop the dev server"` + +### dev_server_status + +Check the status of the dev server and view recent output. Shows whether it is stopped, starting, ready, or has errors. + +**Example usage:** +- `"Is the dev server running?"` +- `"Show me the dev server logs"` +- `"Are there any build errors?"` + - The deploy and list_preview_branches tools are not available when the MCP server is running with the `--dev-only` flag. + The deploy and list_preview_branches tools are not available when the MCP server is running with the `--dev-only` flag. The `--readonly` flag hides deploy, trigger_task, and cancel_run. diff --git a/docs/observability/query.mdx b/docs/observability/query.mdx index 01a3bcd4db9..d48b7f35f7e 100644 --- a/docs/observability/query.mdx +++ b/docs/observability/query.mdx @@ -7,6 +7,7 @@ description: "Query allows you to write custom queries against your data using T - `runs`: contains all task run data including status, timing, costs, and task output. Run metadata (key-value set in your task) is not available on the Query page. - `metrics`: contains metrics data for your runs including CPU, memory, and your custom metrics +- `llm_metrics`: contains LLM/AI metrics including token usage, costs, latency, and model performance data from GenAI spans ### `metrics` table columns @@ -14,7 +15,7 @@ description: "Query allows you to write custom queries against your data using T | :--- | :--- | :--- | | `metric_name` | string | Metric identifier (e.g., `process.cpu.utilization`) | | `metric_type` | string | `gauge`, `sum`, or `histogram` | -| `value` | number | The observed value | +| `metric_value` | number | The observed value | | `bucket_start` | datetime | 10-second aggregation bucket start time | | `run_id` | string | Associated run ID | | `task_identifier` | string | Task slug | @@ -34,7 +35,7 @@ Use `prettyFormat()` to format metric values for display: ```sql SELECT timeBucket(), - prettyFormat(avg(value), 'bytes') AS avg_memory + prettyFormat(avg(metric_value), 'bytes') AS avg_memory_usage FROM metrics WHERE metric_name = 'process.memory.usage' GROUP BY timeBucket @@ -225,7 +226,7 @@ Use `GROUP BY` with aggregate functions: ```sql SELECT task_identifier, - avg(value) AS avg_memory + avg(metric_value) AS avg_memory FROM metrics WHERE metric_name = 'process.memory.usage' GROUP BY task_identifier @@ -529,7 +530,7 @@ Track process CPU utilization bucketed over time. ```sql SELECT timeBucket(), - avg(value) AS avg_cpu + avg(metric_value) AS avg_cpu FROM metrics WHERE metric_name = 'process.cpu.utilization' GROUP BY timeBucket @@ -544,7 +545,7 @@ Average process memory usage per task identifier over the last 7 days. ```sql SELECT task_identifier, - avg(value) AS avg_memory + avg(metric_value) AS avg_memory FROM metrics WHERE metric_name = 'process.memory.usage' GROUP BY task_identifier diff --git a/docs/v3-openapi.yaml b/docs/v3-openapi.yaml index d6e46b3fc2f..f21ff305236 100644 --- a/docs/v3-openapi.yaml +++ b/docs/v3-openapi.yaml @@ -1148,6 +1148,126 @@ paths: "format": "json" }' + "/api/v1/query/schema": + get: + operationId: get_query_schema_v1 + summary: Get query schema + description: Get the schema for TRQL queries, including all available tables, their columns, data types, descriptions, and allowed values. + responses: + "200": + description: Schema retrieved successfully + content: + application/json: + schema: + type: object + properties: + tables: + type: array + items: + type: object + properties: + name: + type: string + description: Table name used in TRQL queries + description: + type: string + description: Description of the table + timeColumn: + type: string + description: The primary time column for this table + columns: + type: array + items: + type: object + properties: + name: + type: string + description: Column name + type: + type: string + description: ClickHouse data type + description: + type: string + description: Column description + example: + type: string + description: Example value + allowedValues: + type: array + items: + type: string + description: Allowed values for enum-like columns + coreColumn: + type: boolean + description: Whether this is a core column included in default queries + "401": + description: Unauthorized - API key is missing or invalid + tags: + - query + security: + - secretKey: [] + x-codeSamples: + - lang: curl + label: cURL + source: |- + curl "https://api.trigger.dev/api/v1/query/schema" \ + -H "Authorization: Bearer tr_dev_1234" + + "/api/v1/query/dashboards": + get: + operationId: list_dashboards_v1 + summary: List built-in dashboards + description: List available built-in dashboards with their widgets. Each dashboard contains pre-built TRQL queries for common metrics like run success rates, costs, and LLM usage. + responses: + "200": + description: Dashboards listed successfully + content: + application/json: + schema: + type: object + properties: + dashboards: + type: array + items: + type: object + properties: + key: + type: string + description: Dashboard identifier (e.g. "overview", "llm") + title: + type: string + description: Dashboard display title + widgets: + type: array + items: + type: object + properties: + id: + type: string + description: Widget identifier + title: + type: string + description: Widget display title + query: + type: string + description: The TRQL query this widget executes + type: + type: string + enum: [bignumber, chart, table] + description: Widget display type + "401": + description: Unauthorized - API key is missing or invalid + tags: + - query + security: + - secretKey: [] + x-codeSamples: + - lang: curl + label: cURL + source: |- + curl "https://api.trigger.dev/api/v1/query/dashboards" \ + -H "Authorization: Bearer tr_dev_1234" + "/api/v1/runs/{runId}/reschedule": parameters: - $ref: "#/components/parameters/runId"