Skip to content

Commit 96243ef

Browse files
ericallamsamejr
ericallam
and
samejr
authored
docs: MCP Server 2.0 (#2385)
* Add MCP Server documentation to documentation site This change introduces comprehensive documentation for the Trigger.dev MCP Server, covering its installation, usage, and available tools. The addition is necessary to provide users with detailed guidance on leveraging the MCP Server for managing Trigger.dev projects, tasks, and deployment processes. - Updated `docs.json` to include a new section for the MCP Server documentation, improving navigation and accessibility. - Added `mcp-introduction.mdx` as an introductory guide to the MCP Server, detailing its purpose and installation steps. - Included `mcp-tools.mdx`, a document outlining each tool available in the MCP Server, complete with descriptions and example usages. - The new content is aimed at improving user understanding and efficiency in using Trigger.dev's MCP Server capabilities. * Refactor MCP installation documentation The changes were necessary to streamline the MCP installation guidance and align our documentation with the latest client support capabilities. Removing the manual installation section and redundant information helps reduce confusion for users. - Updated installation instructions to lead with auto-configuration for supported clients. - Cleaned up the options and examples sections to enhance clarity. - Reformatted client configuration details for better readability. - Removed outdated links in the "Next Steps" section, focusing on more direct resources such as available MCP tools. * mcp docs edits * Add debugMode to get_run_details * add cancel_run * Add list deployments tools * Add list preview branches tool * Docs: adds agent rules page * Adds redirect for the CLI path to work * Adds subagent install image --------- Co-authored-by: James Ritchie <james@trigger.dev>
1 parent ad26cde commit 96243ef

File tree

5 files changed

+844
-1
lines changed

5 files changed

+844
-1
lines changed

‎docs/docs.json‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -165,6 +165,10 @@
165165
}
166166
]
167167
},
168+
{
169+
"group": "MCP Server",
170+
"pages": ["mcp-introduction", "mcp-tools", "mcp-agent-rules"]
171+
},
168172
{
169173
"group": "Using the Dashboard",
170174
"pages": ["run-tests", "troubleshooting-alerts", "replaying", "bulk-actions"]
@@ -298,7 +302,6 @@
298302
"guides/ai-agents/verify-news-article"
299303
]
300304
},
301-
"guides/cursor-rules",
302305
"guides/frameworks/drizzle",
303306
"guides/frameworks/prisma",
304307
"guides/frameworks/sequin",
@@ -620,6 +623,14 @@
620623
"source": "/management/projects/runs",
621624
"destination": "/management/overview"
622625
},
626+
{
627+
"source": "/guides/cursor-rules",
628+
"destination": "/mcp-agent-rules"
629+
},
630+
{
631+
"source": "/agents/rules/overview",
632+
"destination": "/mcp-agent-rules"
633+
},
623634
{
624635
"source": "/upgrade-to-v4",
625636
"destination": "/migrating-from-v3"

‎docs/images/claude-code-subagent.png‎

107 KB
Loading

‎docs/mcp-agent-rules.mdx‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
---
2+
title: "Agent rules"
3+
sidebarTitle: "Agent rules"
4+
description: "Learn how to use the Trigger.dev agent rules with the MCP server"
5+
tag: "new"
6+
---
7+
8+
## What are Trigger.dev agent rules?
9+
10+
Trigger.dev agent rules are comprehensive instruction sets that guide AI assistants to write optimal Trigger.dev code. These rules ensure your AI assistant understands best practices, current APIs, and recommended patterns when working with Trigger.dev projects.
11+
12+
## Installation
13+
14+
Install the agent rules with the following command:
15+
16+
```bash
17+
npx trigger.dev@latest install-rules
18+
```
19+
20+
## Available rule sets
21+
22+
We provide five specialized rule sets, each optimized for different aspects of Trigger.dev development:
23+
24+
| Rule set | Tokens | Description | GitHub |
25+
|:---------|:-------|:------------|:------------|
26+
| **Basic tasks** | 1,200 | Essential rules for writing basic Trigger.dev tasks and fundamental patterns | [View](https://github.com/triggerdotdev/trigger.dev/blob/main/rules/4.0.0/basic-tasks.md) |
27+
| **Advanced tasks** | 3,000 | Comprehensive rules for complex workflows, error handling, and advanced task patterns | [View](https://github.com/triggerdotdev/trigger.dev/blob/main/rules/4.0.0/advanced-tasks.md) |
28+
| **Scheduled tasks** | 780 | Specialized guidance for cron jobs, scheduled workflows, and time-based triggers | [View](https://github.com/triggerdotdev/trigger.dev/blob/main/rules/4.0.0/scheduled-tasks.md) |
29+
| **Configuration** | 1,900 | Complete guide for trigger.config.ts setup, environment configuration, and project structure | [View](https://github.com/triggerdotdev/trigger.dev/blob/main/rules/4.0.0/config.md) |
30+
| **Realtime** | 1,700 | Using Trigger.dev Realtime features and frontend integration patterns | [View](https://github.com/triggerdotdev/trigger.dev/blob/main/rules/4.0.0/realtime.md) |
31+
32+
## Claude Code subagent
33+
34+
For Claude Code users, we provide a subagent called `trigger-dev-expert` that's an expert at writing well-structured Trigger.dev code.
35+
36+
### Installation
37+
38+
The subagent is available as an option when running the rules installation command. Select "Claude Code" as your client and choose to include the subagent when prompted.
39+
40+
![Claude Code subagent installation](/images/claude-code-subagent.png)
41+
42+
### Usage
43+
44+
Activate the subagent in your prompts by requesting it explicitly:
45+
46+
```markdown
47+
use the trigger-dev-expert subagent to create a trigger.dev job that accepts a video url, processes it with ffmpeg to extract the audio, runs the audio through a text-to-speech API like openai, and then uploads both the transcription and the audio to s3
48+
```
49+
50+
The subagent works best when combined with the appropriate rule sets installed alongside it, providing both high-level architectural guidance and detailed implementation knowledge.
51+
52+
## Supported AI clients
53+
54+
The Trigger.dev rules work across a wide range of AI coding assistants and editors:
55+
56+
| Client | Rule activation | Docs |
57+
|:--------|:----------------|:--------------|
58+
| **Cursor** | Automatic when working in trigger directories | [Link](https://docs.cursor.com/en/context/rules#rules/) |
59+
| **Claude Code** | Context-aware activation + custom subagent | [Link](https://docs.anthropic.com/en/docs/claude-code) |
60+
| **VSCode Copilot** | Integration with GitHub Copilot chat | [Link](https://code.visualstudio.com/docs/copilot/overview) |
61+
| **Windsurf** | Automatic activation in Trigger.dev projects | [Link](https://docs.windsurf.com/windsurf/cascade/memories#rules) |
62+
| **Gemini CLI** | Command-line integration | [Link](https://ai.google.dev/gemini-api/docs) |
63+
| **Cline** | Automatic context detection | [Link](https://github.com/cline/cline) |
64+
| **Sourcegraph AMP** | Code intelligence integration | [Link](https://sourcegraph.com/docs) |
65+
| **Kilo** | Custom rule integration | [Link](https://kilocode.ai/docs/advanced-usage/custom-rules) |
66+
| **Ruler** | Rule management | [Link](https://github.com/intellectronica/ruler) |
67+
| **AGENTS.md** | Universal format for OpenAI Codex, Jules, OpenCode, etc. | |
68+
69+
### Rule activation behavior
70+
71+
Different AI tools handle rules differently:
72+
73+
- **Automatic Activation**: Cursor, Windsurf, VSCode Copilot, and Cline automatically apply relevant rules when working in Trigger.dev projects or when `trigger.config.ts` is detected
74+
- **Context-Aware**: Claude Code intelligently applies rules based on the current context and file types
75+
- **Manual Integration**: AGENTS.md clients and others append rules to configuration files for manual activation
76+
77+
## Keeping rules updated
78+
79+
Trigger.dev rules are regularly updated to reflect new features, API changes, and best practices. The CLI includes automatic update detection.
80+
81+
### Automatic update notifications
82+
83+
When running `npx trigger.dev@latest dev`, you'll receive notifications when newer rule versions are available with a simple update command.
84+
85+
### Manual updates
86+
87+
Update rules anytime with:
88+
89+
```bash
90+
npx trigger.dev@latest install-rules
91+
```
92+
93+
The update process replaces existing rules without creating duplicates, keeping your configuration files clean and organized.
94+
95+
### Why updates matter
96+
97+
- **Current API patterns**: Access the latest Trigger.dev APIs and features
98+
- **Performance optimizations**: Benefit from improved patterns and practices
99+
- **Deprecated pattern avoidance**: Prevent AI assistants from generating outdated code
100+
- **New feature support**: Immediate access to newly released capabilities
101+
102+
## Getting started
103+
104+
1. Install the rules:
105+
106+
```bash
107+
npx trigger.dev@latest install-rules
108+
```
109+
110+
2. Follow the prompts to install the rules for your AI client.
111+
112+
3. Consider installing the `trigger-dev-expert` subagent if using Claude Code.
113+
114+
## Next steps
115+
116+
- [Install the MCP server](/mcp-introduction) for complete Trigger.dev integration
117+
- [Explore MCP tools](/mcp-tools) for project management and task execution
118+

‎docs/mcp-introduction.mdx‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
---
2+
title: "MCP Introduction"
3+
sidebarTitle: "Introduction"
4+
description: "Learn how to install and configure the Trigger.dev MCP Server"
5+
tag: "new"
6+
---
7+
8+
## What is the Trigger.dev MCP Server?
9+
10+
The Trigger.dev MCP (Model Context Protocol) Server enables AI assistants to interact directly with your Trigger.dev projects. It provides a comprehensive set of tools to:
11+
12+
- Search Trigger.dev documentation
13+
- Initialize new Trigger.dev projects
14+
- List and manage your projects and organizations
15+
- Get task information and trigger task runs
16+
- Deploy projects to different environments
17+
- Monitor run details and list runs with filtering options
18+
19+
## Installation
20+
21+
### Automatic Installation (Recommended)
22+
23+
The easiest way to install the Trigger.dev MCP Server is using the interactive installation wizard:
24+
25+
```bash
26+
npx trigger.dev@latest install-mcp
27+
```
28+
29+
This command will guide you through:
30+
31+
1. Selecting which MCP clients to configure
32+
2. Choosing installation scope (user, project, or local)
33+
3. Automatically configuring the selected clients
34+
35+
## Command Line Options
36+
37+
The `install-mcp` command supports the following options:
38+
39+
### Core Options
40+
41+
- `-p, --project-ref <project ref>` - Scope the MCP server to a specific Trigger.dev project by providing its project ref
42+
- `-t, --tag <package tag>` - The version of the trigger.dev CLI package to use for the MCP server (default: latest or v4-beta)
43+
- `--dev-only` - Restrict the MCP server to the dev environment only
44+
- `--yolo` - Install the MCP server into all supported clients automatically
45+
- `--scope <scope>` - Choose the scope of the MCP server: `user`, `project`, or `local`
46+
- `--client <clients...>` - Choose specific client(s) to install into
47+
48+
### Configuration Options
49+
50+
- `--log-file <log file>` - Configure the MCP server to write logs to a file
51+
- `-a, --api-url <value>` - Configure a custom Trigger.dev API URL
52+
- `-l, --log-level <level>` - Set CLI log level (debug, info, log, warn, error, none)
53+
54+
## Authentication
55+
56+
You can use the MCP server without authentication with the `search_docs` tool, but for any other tool call you will need to authenticate the MCP server via the same method as the [Trigger.dev CLI](/cli-login-commands).The first time you attempt to use a tool that requires authentication, you will be prompted to authenticate the MCP server via the MCP client.
57+
58+
### Examples
59+
60+
Install for all supported clients:
61+
62+
```bash
63+
npx trigger.dev@latest install-mcp --yolo
64+
```
65+
66+
Install for specific clients:
67+
68+
```bash
69+
npx trigger.dev@latest install-mcp --client claude-code cursor --scope user
70+
```
71+
72+
Install with development environment restriction:
73+
74+
```bash
75+
npx trigger.dev@latest install-mcp --dev-only --project-ref proj_abc123
76+
```
77+
78+
## Supported MCP Clients
79+
80+
The Trigger.dev MCP Server supports the following clients:
81+
82+
| Client | Scope Options | Configuration File | Documentation |
83+
| -------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
84+
| **Claude Code** | user, project, local | `~/.claude.json` or `./.mcp.json` (project/local scope) | [Claude Code MCP Docs](https://docs.anthropic.com/en/docs/claude-code/mcp) |
85+
| **Cursor** | user, project | `~/.cursor/mcp.json` (user) or `./.cursor/mcp.json` (project) | [Cursor MCP Docs](https://docs.cursor.com/features/mcp) |
86+
| **VSCode** | user, project | `~/Library/Application Support/Code/User/mcp.json` (user) or `./.vscode/mcp.json` (project) | [VSCode MCP Docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) |
87+
| **Zed** | user | `~/.config/zed/settings.json` | [Zed Context Servers Docs](https://zed.dev/docs/context-servers) |
88+
| **Windsurf** | user | `~/.codeium/windsurf/mcp_config.json` | [Windsurf MCP Docs](https://docs.codeium.com/windsurf/mcp) |
89+
| **Gemini CLI** | user, project | `~/.gemini/settings.json` (user) or `./.gemini/settings.json` (project) | [Gemini CLI MCP Tutorial](https://medium.com/@joe.njenga/gemini-cli-mcp-tutorial-setup-commands-practical-use-step-by-step-example-b57f55db5f4a) |
90+
| **Charm Crush** | user, project, local | `~/.config/crush/crush.json` (user), `./crush.json` (project), or `./.crush.json` (local) | [Charm MCP Docs](https://github.com/charmbracelet/mcp) |
91+
| **Cline** | user | `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` | [Cline MCP Docs](https://github.com/saoudrizwan/claude-dev#mcp) |
92+
| **OpenAI Codex CLI** | user | `~/.codex/config.toml` | See OpenAI Codex CLI documentation for MCP configuration |
93+
| **Sourcegraph AMP** | user | `~/.config/amp/settings.json` | [Sourcegraph AMP MCP Docs](https://docs.sourcegraph.com/amp/mcp) |
94+
| **opencode** | user, project | `~/.config/opencode/opencode.json` (user) or `./opencode.json` (project) | [opencode MCP Docs](https://opencode.ai/docs/mcp-servers/) |
95+
96+
## Manual Configuration
97+
98+
If your client isn't directly supported by the installer, you can configure it manually. The MCP server uses the following configuration:
99+
100+
**Server Name:** `trigger`
101+
102+
**Command:** `npx`
103+
104+
**Arguments:** `["trigger.dev@latest", "mcp"]`
105+
106+
### Example JSON Configuration
107+
108+
```json
109+
{
110+
"mcpServers": {
111+
"trigger": {
112+
"command": "npx",
113+
"args": ["trigger.dev@latest", "mcp"]
114+
}
115+
}
116+
}
117+
```
118+
119+
### Example TOML Configuration (for Codex CLI)
120+
121+
```toml
122+
[mcp_servers.trigger]
123+
command = "npx"
124+
args = ["trigger.dev@latest", "mcp"]
125+
```
126+
127+
### Additional Options
128+
129+
You can add these optional arguments to customize the server behavior:
130+
131+
- `--log-file <path>` - Log to a specific file
132+
- `--api-url <url>` - Use a custom Trigger.dev API URL
133+
- `--dev-only` - Restrict to dev environment only
134+
- `--project-ref <ref>` - Scope to a specific project
135+
136+
## Environment-Specific Configuration
137+
138+
### Development Only
139+
140+
To restrict the MCP server to only work with the development environment:
141+
142+
```json
143+
{
144+
"mcpServers": {
145+
"trigger": {
146+
"command": "npx",
147+
"args": ["trigger.dev@latest", "mcp", "--dev-only"]
148+
}
149+
}
150+
}
151+
```
152+
153+
### Project-Scoped
154+
155+
To scope the server to a specific project:
156+
157+
```json
158+
{
159+
"mcpServers": {
160+
"trigger": {
161+
"command": "npx",
162+
"args": ["trigger.dev@latest", "mcp", "--project-ref", "proj_your_project_ref"]
163+
}
164+
}
165+
}
166+
```
167+
168+
## Verification
169+
170+
After installation, restart your MCP client and look for a server named "trigger". The server should connect automatically and provide access to all Trigger.dev tools.
171+
172+
## Getting Started
173+
174+
Once installed, you can start using the MCP server by asking your AI assistant questions like:
175+
176+
- `"Search the trigger docs for a ffmpeg example"`
177+
- `"Initialize trigger.dev in my project"`
178+
- `"Get all tasks in my project"`
179+
- `"Trigger my foobar task with a sample payload"`
180+
- `"Get the details of the latest run for my foobar task"`
181+
- `"List all runs for my foobar task"`
182+
- `"Deploy my project to staging"`
183+
- `"Deploy my project to production"`
184+
185+
## Next Steps
186+
187+
- [Explore available MCP tools](/mcp-tools)

0 commit comments

Comments
 (0)