diff --git a/docs/docs.json b/docs/docs.json index 8a9c6ebdc5..5cd39f727e 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -165,6 +165,10 @@ } ] }, + { + "group": "MCP Server", + "pages": ["mcp-introduction", "mcp-tools", "mcp-agent-rules"] + }, { "group": "Using the Dashboard", "pages": ["run-tests", "troubleshooting-alerts", "replaying", "bulk-actions"] @@ -298,7 +302,6 @@ "guides/ai-agents/verify-news-article" ] }, - "guides/cursor-rules", "guides/frameworks/drizzle", "guides/frameworks/prisma", "guides/frameworks/sequin", @@ -620,6 +623,14 @@ "source": "/management/projects/runs", "destination": "/management/overview" }, + { + "source": "/guides/cursor-rules", + "destination": "/mcp-agent-rules" + }, + { + "source": "/agents/rules/overview", + "destination": "/mcp-agent-rules" + }, { "source": "/upgrade-to-v4", "destination": "/migrating-from-v3" diff --git a/docs/images/claude-code-subagent.png b/docs/images/claude-code-subagent.png new file mode 100644 index 0000000000..0adf0d5c3c Binary files /dev/null and b/docs/images/claude-code-subagent.png differ diff --git a/docs/mcp-agent-rules.mdx b/docs/mcp-agent-rules.mdx new file mode 100644 index 0000000000..664d8bcf29 --- /dev/null +++ b/docs/mcp-agent-rules.mdx @@ -0,0 +1,118 @@ +--- +title: "Agent rules" +sidebarTitle: "Agent rules" +description: "Learn how to use the Trigger.dev agent rules with the MCP server" +tag: "new" +--- + +## What are Trigger.dev agent rules? + +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. + +## Installation + +Install the agent rules with the following command: + +```bash +npx trigger.dev@latest install-rules +``` + +## Available rule sets + +We provide five specialized rule sets, each optimized for different aspects of Trigger.dev development: + +| Rule set | Tokens | Description | GitHub | +|:---------|:-------|:------------|:------------| +| **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) | +| **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) | +| **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) | +| **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) | +| **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) | + +## Claude Code subagent + +For Claude Code users, we provide a subagent called `trigger-dev-expert` that's an expert at writing well-structured Trigger.dev code. + +### Installation + +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. + +![Claude Code subagent installation](/images/claude-code-subagent.png) + +### Usage + +Activate the subagent in your prompts by requesting it explicitly: + +```markdown +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 +``` + +The subagent works best when combined with the appropriate rule sets installed alongside it, providing both high-level architectural guidance and detailed implementation knowledge. + +## Supported AI clients + +The Trigger.dev rules work across a wide range of AI coding assistants and editors: + +| Client | Rule activation | Docs | +|:--------|:----------------|:--------------| +| **Cursor** | Automatic when working in trigger directories | [Link](https://docs.cursor.com/en/context/rules#rules/) | +| **Claude Code** | Context-aware activation + custom subagent | [Link](https://docs.anthropic.com/en/docs/claude-code) | +| **VSCode Copilot** | Integration with GitHub Copilot chat | [Link](https://code.visualstudio.com/docs/copilot/overview) | +| **Windsurf** | Automatic activation in Trigger.dev projects | [Link](https://docs.windsurf.com/windsurf/cascade/memories#rules) | +| **Gemini CLI** | Command-line integration | [Link](https://ai.google.dev/gemini-api/docs) | +| **Cline** | Automatic context detection | [Link](https://github.com/cline/cline) | +| **Sourcegraph AMP** | Code intelligence integration | [Link](https://sourcegraph.com/docs) | +| **Kilo** | Custom rule integration | [Link](https://kilocode.ai/docs/advanced-usage/custom-rules) | +| **Ruler** | Rule management | [Link](https://github.com/intellectronica/ruler) | +| **AGENTS.md** | Universal format for OpenAI Codex, Jules, OpenCode, etc. | | + +### Rule activation behavior + +Different AI tools handle rules differently: + +- **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 +- **Context-Aware**: Claude Code intelligently applies rules based on the current context and file types +- **Manual Integration**: AGENTS.md clients and others append rules to configuration files for manual activation + +## Keeping rules updated + +Trigger.dev rules are regularly updated to reflect new features, API changes, and best practices. The CLI includes automatic update detection. + +### Automatic update notifications + +When running `npx trigger.dev@latest dev`, you'll receive notifications when newer rule versions are available with a simple update command. + +### Manual updates + +Update rules anytime with: + +```bash +npx trigger.dev@latest install-rules +``` + +The update process replaces existing rules without creating duplicates, keeping your configuration files clean and organized. + +### Why updates matter + +- **Current API patterns**: Access the latest Trigger.dev APIs and features +- **Performance optimizations**: Benefit from improved patterns and practices +- **Deprecated pattern avoidance**: Prevent AI assistants from generating outdated code +- **New feature support**: Immediate access to newly released capabilities + +## Getting started + +1. Install the rules: + +```bash +npx trigger.dev@latest install-rules +``` + +2. Follow the prompts to install the rules for your AI client. + +3. Consider installing the `trigger-dev-expert` subagent if using Claude Code. + +## Next steps + +- [Install the MCP server](/mcp-introduction) for complete Trigger.dev integration +- [Explore MCP tools](/mcp-tools) for project management and task execution + diff --git a/docs/mcp-introduction.mdx b/docs/mcp-introduction.mdx new file mode 100644 index 0000000000..d9dc3474e1 --- /dev/null +++ b/docs/mcp-introduction.mdx @@ -0,0 +1,187 @@ +--- +title: "MCP Introduction" +sidebarTitle: "Introduction" +description: "Learn how to install and configure the Trigger.dev MCP Server" +tag: "new" +--- + +## What is the Trigger.dev MCP Server? + +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: + +- Search Trigger.dev documentation +- Initialize new Trigger.dev projects +- List and manage your projects and organizations +- Get task information and trigger task runs +- Deploy projects to different environments +- Monitor run details and list runs with filtering options + +## Installation + +### Automatic Installation (Recommended) + +The easiest way to install the Trigger.dev MCP Server is using the interactive installation wizard: + +```bash +npx trigger.dev@latest install-mcp +``` + +This command will guide you through: + +1. Selecting which MCP clients to configure +2. Choosing installation scope (user, project, or local) +3. Automatically configuring the selected clients + +## Command Line Options + +The `install-mcp` command supports the following options: + +### Core Options + +- `-p, --project-ref ` - Scope the MCP server to a specific Trigger.dev project by providing its project ref +- `-t, --tag ` - The version of the trigger.dev CLI package to use for the MCP server (default: latest or v4-beta) +- `--dev-only` - Restrict the MCP server to the dev environment only +- `--yolo` - Install the MCP server into all supported clients automatically +- `--scope ` - Choose the scope of the MCP server: `user`, `project`, or `local` +- `--client ` - Choose specific client(s) to install into + +### Configuration Options + +- `--log-file ` - Configure the MCP server to write logs to a file +- `-a, --api-url ` - Configure a custom Trigger.dev API URL +- `-l, --log-level ` - Set CLI log level (debug, info, log, warn, error, none) + +## Authentication + +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. + +### Examples + +Install for all supported clients: + +```bash +npx trigger.dev@latest install-mcp --yolo +``` + +Install for specific clients: + +```bash +npx trigger.dev@latest install-mcp --client claude-code cursor --scope user +``` + +Install with development environment restriction: + +```bash +npx trigger.dev@latest install-mcp --dev-only --project-ref proj_abc123 +``` + +## Supported MCP Clients + +The Trigger.dev MCP Server supports the following clients: + +| Client | Scope Options | Configuration File | Documentation | +| -------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| **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) | +| **Cursor** | user, project | `~/.cursor/mcp.json` (user) or `./.cursor/mcp.json` (project) | [Cursor MCP Docs](https://docs.cursor.com/features/mcp) | +| **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) | +| **Zed** | user | `~/.config/zed/settings.json` | [Zed Context Servers Docs](https://zed.dev/docs/context-servers) | +| **Windsurf** | user | `~/.codeium/windsurf/mcp_config.json` | [Windsurf MCP Docs](https://docs.codeium.com/windsurf/mcp) | +| **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) | +| **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) | +| **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) | +| **OpenAI Codex CLI** | user | `~/.codex/config.toml` | See OpenAI Codex CLI documentation for MCP configuration | +| **Sourcegraph AMP** | user | `~/.config/amp/settings.json` | [Sourcegraph AMP MCP Docs](https://docs.sourcegraph.com/amp/mcp) | +| **opencode** | user, project | `~/.config/opencode/opencode.json` (user) or `./opencode.json` (project) | [opencode MCP Docs](https://opencode.ai/docs/mcp-servers/) | + +## Manual Configuration + +If your client isn't directly supported by the installer, you can configure it manually. The MCP server uses the following configuration: + +**Server Name:** `trigger` + +**Command:** `npx` + +**Arguments:** `["trigger.dev@latest", "mcp"]` + +### Example JSON Configuration + +```json +{ + "mcpServers": { + "trigger": { + "command": "npx", + "args": ["trigger.dev@latest", "mcp"] + } + } +} +``` + +### Example TOML Configuration (for Codex CLI) + +```toml +[mcp_servers.trigger] +command = "npx" +args = ["trigger.dev@latest", "mcp"] +``` + +### Additional Options + +You can add these optional arguments to customize the server behavior: + +- `--log-file ` - Log to a specific file +- `--api-url ` - Use a custom Trigger.dev API URL +- `--dev-only` - Restrict to dev environment only +- `--project-ref ` - Scope to a specific project + +## Environment-Specific Configuration + +### Development Only + +To restrict the MCP server to only work with the development environment: + +```json +{ + "mcpServers": { + "trigger": { + "command": "npx", + "args": ["trigger.dev@latest", "mcp", "--dev-only"] + } + } +} +``` + +### Project-Scoped + +To scope the server to a specific project: + +```json +{ + "mcpServers": { + "trigger": { + "command": "npx", + "args": ["trigger.dev@latest", "mcp", "--project-ref", "proj_your_project_ref"] + } + } +} +``` + +## Verification + +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. + +## Getting Started + +Once installed, you can start using the MCP server by asking your AI assistant questions like: + +- `"Search the trigger docs for a ffmpeg example"` +- `"Initialize trigger.dev in my project"` +- `"Get all tasks in my project"` +- `"Trigger my foobar task with a sample payload"` +- `"Get the details of the latest run for my foobar task"` +- `"List all runs for my foobar task"` +- `"Deploy my project to staging"` +- `"Deploy my project to production"` + +## Next Steps + +- [Explore available MCP tools](/mcp-tools) diff --git a/docs/mcp-tools.mdx b/docs/mcp-tools.mdx new file mode 100644 index 0000000000..0163de97a4 --- /dev/null +++ b/docs/mcp-tools.mdx @@ -0,0 +1,527 @@ +--- +title: "MCP Tools" +sidebarTitle: "Tools" +description: "Learn about the tools available in the Trigger.dev MCP Server" +tag: "new" +--- + +The Trigger.dev MCP Server provides a comprehensive set of tools that enable AI assistants to interact with your Trigger.dev projects. These tools cover everything from project management to task execution and monitoring. + +## Documentation and Search Tools + +### search_docs + +Search across the Trigger.dev documentation to find relevant information, code examples, API references, and guides. + + + The search query to find information in the Trigger.dev documentation + + +**Usage Examples:** + +- "How do I create a scheduled task?" +- "webhook examples" +- "deployment configuration" +- "error handling patterns" + + +```json Example Usage +{ + "tool": "search_docs", + "arguments": { + "query": "webhook examples" + } +} +``` + + +## Project Management Tools + +### list_projects + +List all projects in your Trigger.dev account. + +**No parameters required** + + + Array of project objects containing project details, IDs, and metadata + + + +```json Example Response +{ + "projects": [ + { + "id": "proj_abc123", + "name": "My App", + "slug": "my-app", + "organizationId": "org_xyz789" + } + ] +} +``` + + +### list_orgs + +List all organizations you have access to. + +**No parameters required** + + + Array of organization objects containing organization details and metadata + + +### create_project_in_org + +Create a new project in an organization. + + + The organization to create the project in, can either be the organization slug or the ID. Use the + `list_orgs` tool to get a list of organizations and ask the user to select one. + + + + The name of the project to create + + + +```json Example Usage +{ + "tool": "create_project_in_org", + "arguments": { + "orgParam": "my-org", + "name": "New Project" + } +} +``` + + +### initialize_project + +Initialize Trigger.dev in your project with automatic setup and configuration. + + + The organization to create the project in, can either be the organization slug or the ID. Use the + `list_orgs` tool to get a list of organizations and ask the user to select one. + + + + The trigger.dev project ref, starts with `proj_`. We will attempt to automatically detect the + project ref if running inside a directory that includes a trigger.config.ts file. + + + + The name of the project to create. If projectRef is not provided, we will use this name to create + a new project in the organization you select. + + + + The current working directory of the project + + +## Task Management Tools + +### get_tasks + +Get all tasks in a project. + + + The trigger.dev project ref, starts with `proj_`. We will attempt to automatically detect the + project ref if running inside a directory that includes a trigger.config.ts file. + + + + The path to the trigger.config.ts file. Only used when the trigger.config.ts file is not at the + root dir (like in a monorepo setup). If not provided, we will try to find the config file in the + current working directory. + + + + The environment to get tasks for. Options: `dev`, `staging`, `prod`, `preview` + + + + The branch to get tasks for, only used for preview environments + + + +```json Example Usage +{ + "tool": "get_tasks", + "arguments": { + "projectRef": "proj_abc123", + "environment": "dev" + } +} +``` + + +### trigger_task + +Trigger a task to run. + + + The trigger.dev project ref, starts with `proj_`. We will attempt to automatically detect the + project ref if running inside a directory that includes a trigger.config.ts file. + + + + The path to the trigger.config.ts file. Only used when the trigger.config.ts file is not at the + root dir (like in a monorepo setup). + + + + The environment to trigger the task in. Options: `dev`, `staging`, `prod`, `preview` + + + + The branch to trigger the task in, only used for preview environments + + + + The ID/slug of the task to trigger. Use the `get_tasks` tool to get a list of tasks and ask the + user to select one if it's not clear which one to use. + + + + The payload to trigger the task with, must be a valid JSON string + + + + Additional options for the task run + + + The name of the queue to trigger the task in, by default will use the queue configured in the + task + + + The delay before the task run is executed + + + The idempotency key to use for the task run + + + The machine preset to use for the task run. Options: `micro`, `small-1x`, `small-2x`, + `medium-1x`, `medium-2x`, `large-1x`, `large-2x` + + + The maximum number of attempts to retry the task run + + + The maximum duration in seconds of the task run + + + Tags to add to the task run. Must be less than 128 characters and cannot have more than 5 + + + The time to live of the task run. If the run doesn't start executing within this time, it will + be automatically cancelled. + + + + + +```json Example Usage +{ + "tool": "trigger_task", + "arguments": { + "projectRef": "proj_abc123", + "taskId": "email-notification", + "payload": "{\"email\": \"user@example.com\", \"subject\": \"Hello World\"}", + "options": { + "tags": ["urgent"], + "maxAttempts": 3 + } + } +} +``` + + +## Run Monitoring Tools + +### get_run_details + +Get the details of a specific task run. + + + The trigger.dev project ref, starts with `proj_`. We will attempt to automatically detect the + project ref if running inside a directory that includes a trigger.config.ts file. + + + + The path to the trigger.config.ts file. Only used when the trigger.config.ts file is not at the + root dir (like in a monorepo setup). + + + + The environment to get the run details from. Options: `dev`, `staging`, `prod`, `preview` + + + + The branch to get the run details from, only used for preview environments + + + + The ID of the run to get the details of, starts with `run_` + + + + Enable debug mode to get more detailed information about the run, including the entire trace (all logs and spans for the run and any child run). Set this to true if prompted to debug a run. + + +### cancel_run + +Cancel a running task. + + + The ID of the run to cancel, starts with `run_` + + + + The trigger.dev project ref, starts with `proj_`. We will attempt to automatically detect the + project ref if running inside a directory that includes a trigger.config.ts file. + + + + The path to the trigger.config.ts file. Only used when the trigger.config.ts file is not at the + root dir (like in a monorepo setup). + + + + The environment to cancel the run in. Options: `dev`, `staging`, `prod`, `preview` + + + + The branch to cancel the run in, only used for preview environments + + + +```json Example Usage +{ + "tool": "cancel_run", + "arguments": { + "runId": "run_abc123", + "projectRef": "proj_abc123" + } +} +``` + + +### list_runs + +List all runs for a project with comprehensive filtering options. + + + The trigger.dev project ref, starts with `proj_`. We will attempt to automatically detect the + project ref if running inside a directory that includes a trigger.config.ts file. + + + + The path to the trigger.config.ts file. Only used when the trigger.config.ts file is not at the + root dir (like in a monorepo setup). + + + + The environment to list runs from. Options: `dev`, `staging`, `prod`, `preview` + + + + The branch to list runs from, only used for preview environments + + + + The cursor to use for pagination, starts with `run_` + + + + The number of runs to list in a single page. Up to 100 + + + + Filter for runs with this run status. Options: `PENDING_VERSION`, `QUEUED`, `DEQUEUED`, + `EXECUTING`, `WAITING`, `COMPLETED`, `CANCELED`, `FAILED`, `CRASHED`, `SYSTEM_FAILURE`, `DELAYED`, + `EXPIRED`, `TIMED_OUT` + + + + Filter for runs that match this task identifier + + + + Filter for runs that match this version, e.g. `20250808.3` + + + + Filter for runs that include this tag + + + + Filter for runs created after this ISO 8601 timestamp + + + + Filter for runs created before this ISO 8601 timestamp + + + + Filter for runs created in the last N time period. Examples: `7d`, `30d`, `365d` + + + + Filter for runs that match this machine preset. Options: `micro`, `small-1x`, `small-2x`, + `medium-1x`, `medium-2x`, `large-1x`, `large-2x` + + + +```json Example Usage +{ + "tool": "list_runs", + "arguments": { + "projectRef": "proj_abc123", + "status": "COMPLETED", + "limit": 10, + "period": "7d" + } +} +``` + + +## Deployment Tools + +### deploy + +Deploy a project to staging or production environments. + + + The trigger.dev project ref, starts with `proj_`. We will attempt to automatically detect the + project ref if running inside a directory that includes a trigger.config.ts file. + + + + The path to the trigger.config.ts file. Only used when the trigger.config.ts file is not at the + root dir (like in a monorepo setup). + + + + The environment to deploy to. Options: `staging`, `prod`, `preview` + + + + The branch to deploy, only used for preview environments + + + + Skip promoting the deployment to the current deployment for the environment + + + + Skip syncing environment variables when using the syncEnvVars extension + + + + Skip checking for @trigger.dev package updates + + + +```json Example Usage +{ + "tool": "deploy", + "arguments": { + "projectRef": "proj_abc123", + "environment": "prod", + "skipUpdateCheck": true + } +} +``` + + +### list_deployments + +List deployments for a project with comprehensive filtering options. + + + The trigger.dev project ref, starts with `proj_`. We will attempt to automatically detect the + project ref if running inside a directory that includes a trigger.config.ts file. + + + + The path to the trigger.config.ts file. Only used when the trigger.config.ts file is not at the + root dir (like in a monorepo setup). + + + + The environment to list deployments for. Options: `staging`, `prod`, `preview` + + + + The branch to list deployments from, only used for preview environments + + + + The deployment ID to start the search from, to get the next page + + + + The number of deployments to return, defaults to 20 (max 100) + + + + Filter deployments that are in this status. Options: `PENDING`, `BUILDING`, `DEPLOYING`, `DEPLOYED`, `FAILED`, `CANCELED`, `TIMED_OUT` + + + + The date to start the search from, in ISO 8601 format + + + + The date to end the search, in ISO 8601 format + + + + The period to search within. Examples: `1d`, `7d`, `3h` + + + +```json Example Usage +{ + "tool": "list_deployments", + "arguments": { + "projectRef": "proj_abc123", + "environment": "prod", + "status": "DEPLOYED", + "limit": 10 + } +} +``` + + +### list_preview_branches + +List all preview branches in the project. + + + The trigger.dev project ref, starts with `proj_`. We will attempt to automatically detect the + project ref if running inside a directory that includes a trigger.config.ts file. + + + + The path to the trigger.config.ts file. Only used when the trigger.config.ts file is not at the + root dir (like in a monorepo setup). If not provided, we will try to find the config file in the + current working directory. + + + +```json Example Usage +{ + "tool": "list_preview_branches", + "arguments": { + "projectRef": "proj_abc123" + } +} +``` + + + + The deploy tool and list_preview_branches tool are not available when the MCP server is running with the `--dev-only` flag. +