Add support for running a local MCP server via the dev CLI command
#1785
Conversation
…LI command This just adds the main components for the MCP server. It hooks on the existing `dev` command and can be enabled by passing the `--mcp` flag. Currently only the `trigger-task` tool is exposed, which enables users trigger tasks via MCP and see the resulting run. Still WIP :)
|
WalkthroughThis change introduces new dependencies and type definitions into the CLI package, along with modifications to the API client. Updates include the addition of a new import and comment in the CLI’s API client, removal of an extraneous comment in the development command, and an enhanced shutdown process for the MCP server. Further, the MCP server functionality is extended with task listing and event listening, a new API method and route are added for run events, and documentation plus a configuration file for MCP are incorporated. Changes
Sequence Diagram(s)sequenceDiagram
participant DevSession
participant MCPServer
DevSession->>MCPServer: stopMcpServer()
MCPServer-->>DevSession: Acknowledge shutdown
sequenceDiagram
participant Client
participant ApiClient
participant Backend
Client->>ApiClient: listRunEvents(runId)
ApiClient->>Backend: GET /api/v1/runs/{runId}/events
Backend-->>ApiClient: Return event data (BigInt as string)
ApiClient-->>Client: Send run events JSON
Possibly related PRs
Suggested reviewers
Poem
Warning There were issues while running some tools. Please review the errors and either fix the tool’s configuration or disable the tool if it’s a critical failure. 🔧 ESLint
Scope: all 2 workspace projects ✨ Finishing Touches
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
V2 is the way to go for the future.
This can be used in combination with the trigger-task tool from LLMs to show details about the run after triggering the task.
This enables some basic level of debugging capabilities in combinatio with the other MCP tools
This enables LLMs to figure out which task you are referring to, without needing to specify the full task ID
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🔭 Outside diff range comments (1)
packages/cli-v3/src/dev/mcpServer.ts (1)
136-226:⚠️ Potential issueCode duplication in the file.
There appear to be duplicate code blocks in the file:
- The
app = polka()declaration appears twice (lines 136 and 223)- The
/sseroute handler is duplicated- There are fragments of code outside proper function definitions (lines 140-152)
This looks like a merge conflict or incomplete refactoring. The duplicate code should be removed to avoid confusion and potential runtime errors.
-const app = polka(); -app.get("/sse", (_req, res) => { - mcpTransport = new SSEServerTransport("/messages", res); - }, - async ({ runId }) => { - const result = await sdkApiClient.retrieveRun(runId); - - return { - content: [ - { - type: "text", - text: JSON.stringify(result, null, 2), - }, - ], - }; - } -);Keep only the complete implementation starting at line 223.
🧹 Nitpick comments (5)
packages/cli-v3/README.md (1)
22-52: Comprehensive documentation of the MCP server feature.The documentation clearly explains what the MCP server is, how to use it, and its integration with the Trigger.dev CLI. This will help users understand and utilize this new feature.
There are two minor grammatical issues to fix:
-The Trigger.dev CLI can expose an MCP server and enable you interact with Trigger.dev in agentic LLM workflows. +The Trigger.dev CLI can expose an MCP server and enable you to interact with Trigger.dev in agentic LLM workflows. -By default it runs on port `3333`. You can change this by passing the `--mcp-port` flag: +By default, it runs on port `3333`. You can change this by passing the `--mcp-port` flag:🧰 Tools
🪛 LanguageTool
[uncategorized] ~27-~27: Possible missing preposition found.
Context: ...can expose an MCP server and enable you interact with Trigger.dev in agentic LLM workflo...(AI_HYDRA_LEO_MISSING_TO)
[uncategorized] ~37-~37: Did you mean: “By default,”?
Context: ...ommand:bash trigger dev --mcpBy default it runs on port3333. You can change ...(BY_DEFAULT_COMMA)
packages/cli-v3/src/apiClient.ts (1)
52-53: Consider making accessToken required as suggested.The TODO comment recommends making the
accessTokenparameter required. This is a good suggestion for future improvement as most API methods require it and check for its presence.When implementing this change in the future, you would need to:
- Remove the optional marker from the parameter
- Update all callers to ensure they provide an access token
- Remove the null checks before API calls since the parameter would be guaranteed
- constructor( - public readonly apiURL: string, - // TODO: consider making this required - public readonly accessToken?: string - ) { + constructor( + public readonly apiURL: string, + public readonly accessToken: string + ) {apps/webapp/app/routes/api.v1.runs.$runId.events.ts (3)
41-41: Consider implementing field filtering.The TODO comment correctly identifies that returning the whole events might not be optimal. Consider:
- Defining a specific response schema with only the necessary fields
- Implementing field selection parameters (similar to GraphQL)
- Creating a dedicated DTO (Data Transfer Object) for the response
44-51: Good handling of BigInt serialization, but consider a utility function.The JSON serialization with BigInt handling is implemented correctly, but this pattern might be needed in multiple places.
Consider extracting this to a reusable utility function:
// Utility function in a shared location export function serializeWithBigInt(data: any): any { return JSON.parse( JSON.stringify(data, (_, value) => typeof value === "bigint" ? value.toString() : value ) ); } // Then in your code return json( { events: runEvents.map(event => serializeWithBigInt(event)), }, { status: 200 } );
52-54: Consider adding error handling for the response.While the current implementation returns a 200 status for successful responses, consider adding explicit error handling for cases where event retrieval might fail.
A try/catch block around the event retrieval logic could help handle unexpected errors gracefully:
try { const runEvents = await eventRepository.getRunEvents( getTaskEventStoreTableForRun(run), run.friendlyId, run.createdAt, run.completedAt ?? undefined ); // Process and return events... } catch (error) { console.error("Failed to retrieve run events:", error); return json({ error: "Failed to retrieve run events" }, { status: 500 }); }
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
pnpm-lock.yamlis excluded by!**/pnpm-lock.yaml
📒 Files selected for processing (22)
packages/cli-v3/package.json(3 hunks)packages/cli-v3/src/apiClient.ts(2 hunks)packages/cli-v3/src/commands/dev.ts(2 hunks)packages/cli-v3/src/dev/devSession.ts(3 hunks)packages/cli-v3/src/dev/mcpServer.ts(1 hunks)packages/core/src/v3/apiClient/index.ts(1 hunks)packages/cli-v3/src/dev/mcpServer.ts(1 hunks)packages/cli-v3/src/dev/mcpServer.ts(3 hunks)packages/cli-v3/src/dev/mcpServer.ts(3 hunks)packages/cli-v3/src/commands/dev.ts(2 hunks)packages/cli-v3/src/dev/devSession.ts(1 hunks)packages/cli-v3/src/dev/mcpServer.ts(2 hunks)packages/cli-v3/src/dev/devSession.ts(2 hunks)packages/cli-v3/src/dev/mcpServer.ts(1 hunks)packages/cli-v3/src/dev/mcpServer.ts(1 hunks)apps/webapp/app/routes/api.v1.runs.$runId.events.ts(1 hunks)packages/cli-v3/src/dev/mcpServer.ts(1 hunks)packages/core/src/v3/apiClient/index.ts(1 hunks)packages/cli-v3/src/dev/mcpServer.ts(3 hunks).cursor/mcp.json(1 hunks)packages/cli-v3/README.md(1 hunks)packages/cli-v3/src/commands/dev.ts(0 hunks)
🧰 Additional context used
🪛 LanguageTool
packages/cli-v3/README.md
[uncategorized] ~27-~27: Possible missing preposition found.
Context: ...can expose an MCP server and enable you interact with Trigger.dev in agentic LLM workflo...
(AI_HYDRA_LEO_MISSING_TO)
[uncategorized] ~37-~37: Did you mean: “By default,”?
Context: ...ommand: bash trigger dev --mcp By default it runs on port 3333. You can change ...
(BY_DEFAULT_COMMA)
🔇 Additional comments (18)
.cursor/mcp.json (1)
1-7: Well-structured configuration file for the MCP server.This configuration file correctly sets up the MCP server configuration for the Cursor editor, specifying the SSE endpoint URL for Trigger.dev at the default port 3333.
packages/core/src/v3/apiClient/index.ts (1)
407-417:❓ Verification inconclusive
API client method added for fetching run events.
The
listRunEventsmethod implementation follows the existing patterns in the API client, but uses a placeholder schema.The TODO comment indicates a need for a proper schema definition for the response. Consider adding a specific type for run events in a future update:
🏁 Script executed:
#!/bin/bash # Look for any existing run event schema definitions that could be reused echo "Searching for potential run event schemas..." rg -t ts "RunEvent" --glob "packages/core/src/v3/schemas/**/*.ts"Length of output: 164
Action Required: Verify Run Event Schema Definition
The
listRunEventsmethod implementation is consistent with our existing API client patterns, but it still uses a placeholder schema (z.any()). Our search for a dedicatedRunEventschema in thepackages/core/src/v3/schemas/directory did not return any results. Please manually verify if a dedicated schema for run events can be added or reused in the future.
- The function follows the established API client patterns.
- No existing reusable
RunEventschema was found, so replacingz.any()remains a future improvement.packages/cli-v3/package.json (3)
52-52: Added type definitions for polka.The type definition for
polkais appropriately added to support TypeScript development with the lightweight server library.
79-79: Added MCP SDK dependency.The Model Context Protocol SDK is added as a dependency to support the integration of the MCP server functionality.
119-119: Added polka server dependency.The lightweight
polkaserver library is added to support the SSE transport for the MCP server.packages/cli-v3/src/dev/mcpServer.ts (3)
3-3: Updated zod import to include additional utility functions.The import for
zodhas been updated to explicitly includeoptionalandunionfunctions that are used in the schema definitions.
64-64: Enhanced description for the list-runs tool.The description has been improved to provide more details about what information is returned by the tool.
116-135: Added new tool for retrieving run details.The new
get-runtool follows the established pattern and provides a convenient way to fetch detailed information about a specific task run.packages/cli-v3/src/dev/devSession.ts (2)
64-65: Good implementation of port configuration for MCP server.The change correctly passes the configured port from command line arguments to the MCP server. This aligns well with the CLI options defined in the
dev.tsfile.
205-205: Good cleanup of MCP server resources.The
stopMcpServerfunction is properly called during the cleanup process, ensuring that the MCP server is shut down when the dev session ends.packages/cli-v3/src/commands/dev.ts (2)
24-24: Well-defined port configuration with sensible defaults.Using
z.coerce.number()ensures type safety while allowing string inputs from the command line to be properly converted to numbers. The default value of 3333 is consistent with the documentation.
54-55: Clear CLI options for MCP server configuration.The CLI options have clear descriptions and consistent default values. The
--mcpflag enables the server, and--mcp-portallows customization of the port.packages/cli-v3/src/apiClient.ts (1)
34-34: Added import for ListRunResponse.The addition of this import suggests preparation for MCP server functionality to list task runs, which aligns with the PR objectives.
apps/webapp/app/routes/api.v1.runs.$runId.events.ts (5)
33-39: The resource retrieval logic looks good.The implementation properly retrieves run events using the event repository with appropriate parameters, including handling the case where completedAt might be null.
18-22: Good use of the authorization model with proper resource definition.The authorization configuration is well-structured with appropriate scopes and resource definitions. The inclusion of
shouldRetryNotFoundis a good practice for handling potential race conditions.
1-7: Imports are appropriately structured.The imports are well-organized and include all necessary dependencies for the functionality provided by this route.
8-10: Parameter validation is correctly implemented.The Zod schema correctly validates the runId parameter, and the comment provides useful context about what the ID represents.
17-17:❓ Verification inconclusive
Review CORS strategy setting.
The "all" CORS strategy allows access from any origin. Consider if this level of access is necessary or if a more restrictive policy would be more appropriate for this endpoint.
🏁 Script executed:
#!/bin/bash # Check how CORS is configured in other API routes echo "Checking CORS configuration patterns in other API routes:" rg "corsStrategy" --type ts "apps/webapp/app/routes" -A 1 -B 1 | head -n 20Length of output: 1444
CORS Strategy Consistency and Security Check
The
corsStrategy: "all"setting on line 17 inapps/webapp/app/routes/api.v1.runs.$runId.events.tsis consistent with similar configurations in other API routes (e.g., inapps/webapp/app/routes/api.v1.runs.tsand various realtime routes). Please verify that allowing all origins is intentional for this endpoint and aligns with your security requirements. If a more restrictive CORS policy is appropriate for handling sensitive data or operations, consider updating the setting accordingly.
| runId: z.string(), // This is the run friendly ID | ||
| }); | ||
|
|
||
| // TODO: paginate the results |
There was a problem hiding this comment.
Don't forget to implement pagination.
The TODO comment correctly identifies the need for pagination. Without it, large result sets could cause performance issues or timeout errors, especially if runs can generate many events.
Consider implementing standard pagination parameters (limit/offset or cursor-based) and returning metadata about total count and next page.
Changes in this PR:
--mcpflag to thedevcommand to control the behavior. By default the MCP server does not run.--mcp-portflag to configure the MCP server. By default it runs on3333.polkaserver (very lightweight version of express).More flows can be supported in the future, such as task payload parsing in the MCP tools, custom prompts to support typical workflows, more actions, etc...
This PR already enables a lot of interesting agentic LLM flows, such as:
...and more. Check out the screenshots below for a preview :)
Refs #1780
✅ Checklist
Testing
Tested only manually so far.
Changelog
Screenshots
Summary by CodeRabbit
New Features
Documentation