You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
mcp.WithDescription(`Report progress on a task.`),
19
-
mcp.WithString("summary", mcp.Description(`A summary of your progress on a task.
20
-
18
+
mcp.WithDescription(`Report progress on a user task in Coder.
19
+
Use this tool to keep the user informed about your progress with their request.
20
+
For long-running operations, call this periodically to provide status updates.
21
+
This is especially useful when performing multi-step operations like workspace creation or deployment.`),
22
+
mcp.WithString("summary", mcp.Description(`A concise summary of your current progress on the task.
23
+
21
24
Good Summaries:
22
25
- "Taking a look at the login page..."
23
26
- "Found a bug! Fixing it now..."
24
-
- "Investigating the GitHub Issue..."`), mcp.Required()),
25
-
mcp.WithString("link", mcp.Description(`A relevant link to your work. e.g. GitHub issue link, pull request link, etc.`), mcp.Required()),
26
-
mcp.WithString("emoji", mcp.Description(`A relevant emoji to your work.`), mcp.Required()),
27
-
mcp.WithBoolean("done", mcp.Description(`Whether the task the user requested is complete.`), mcp.Required()),
27
+
- "Investigating the GitHub Issue..."
28
+
- "Waiting for workspace to start (1/3 resources ready)"
29
+
- "Downloading template files from repository"`), mcp.Required()),
30
+
mcp.WithString("link", mcp.Description(`A relevant URL related to your work, such as:
31
+
- GitHub issue link
32
+
- Pull request URL
33
+
- Documentation reference
34
+
- Workspace URL
35
+
Use complete URLs (including https://) when possible.`), mcp.Required()),
36
+
mcp.WithString("emoji", mcp.Description(`A relevant emoji that visually represents the current status:
37
+
- 🔍 for investigating/searching
38
+
- 🚀 for deploying/starting
39
+
- 🐛 for debugging
40
+
- ✅ for completion
41
+
- ⏳ for waiting
42
+
Choose an emoji that helps the user understand the current phase at a glance.`), mcp.Required()),
43
+
mcp.WithBoolean("done", mcp.Description(`Whether the overall task the user requested is complete.
44
+
Set to true only when the entire requested operation is finished successfully.
45
+
For multi-step processes, use false until all steps are complete.`), mcp.Required()),
28
46
),
29
47
MakeHandler: handleCoderReportTask,
30
48
},
31
49
{
32
50
Tool: mcp.NewTool("coder_whoami",
33
-
mcp.WithDescription(`Get information about the currently logged-in Coder user.`),
51
+
mcp.WithDescription(`Get information about the currently logged-in Coder user.
52
+
Returns JSON with the user's profile including fields: id, username, email, created_at, status, roles, etc.
53
+
Use this to identify the current user context before performing workspace operations.
54
+
This tool is useful for verifying permissions and checking the user's identity.
55
+
56
+
Common errors:
57
+
- Authentication failure: The session may have expired
58
+
- Server unavailable: The Coder deployment may be unreachable`),
34
59
),
35
60
MakeHandler: handleCoderWhoami,
36
61
},
37
62
{
38
63
Tool: mcp.NewTool("coder_list_templates",
39
-
mcp.WithDescription(`List all templates on a given Coder deployment.`),
64
+
mcp.WithDescription(`List all templates available on the Coder deployment.
65
+
Returns JSON with detailed information about each template, including:
66
+
- Template name, ID, and description
67
+
- Creation/modification timestamps
68
+
- Version information
69
+
- Associated organization
70
+
71
+
Use this tool to discover available templates before creating workspaces.
72
+
Templates define the infrastructure and configuration for workspaces.
73
+
74
+
Common errors:
75
+
- Authentication failure: Check user permissions
76
+
- No templates available: The deployment may not have any templates configured`),
40
77
),
41
78
MakeHandler: handleCoderListTemplates,
42
79
},
43
80
{
44
81
Tool: mcp.NewTool("coder_list_workspaces",
45
-
mcp.WithDescription(`List workspaces on a given Coder deployment owned by the current user.`),
46
-
mcp.WithString(`owner`, mcp.Description(`The owner of the workspaces to list. Defaults to the current user.`), mcp.DefaultString(codersdk.Me)),
47
-
mcp.WithNumber(`offset`, mcp.Description(`The offset to start listing workspaces from. Defaults to 0.`), mcp.DefaultNumber(0)),
48
-
mcp.WithNumber(`limit`, mcp.Description(`The maximum number of workspaces to list. Defaults to 10.`), mcp.DefaultNumber(10)),
82
+
mcp.WithDescription(`List workspaces available on the Coder deployment.
83
+
Returns JSON with workspace metadata including status, resources, and configurations.
84
+
Use this before other workspace operations to find valid workspace names/IDs.
85
+
Results are paginated - use offset and limit parameters for large deployments.
86
+
87
+
Common errors:
88
+
- Authentication failure: Check user permissions
89
+
- Invalid owner parameter: Ensure the owner exists`),
90
+
mcp.WithString(`owner`, mcp.Description(`The username of the workspace owner to filter by.
91
+
Defaults to "me" which represents the currently authenticated user.
92
+
Use this to view workspaces belonging to other users (requires appropriate permissions).
93
+
Special value: "me" - List workspaces owned by the authenticated user.`), mcp.DefaultString(codersdk.Me)),
94
+
mcp.WithNumber(`offset`, mcp.Description(`Pagination offset - the starting index for listing workspaces.
95
+
Used with the 'limit' parameter to implement pagination.
96
+
For example, to get the second page of results with 10 items per page, use offset=10.
97
+
Defaults to 0 (first page).`), mcp.DefaultNumber(0)),
98
+
mcp.WithNumber(`limit`, mcp.Description(`Maximum number of workspaces to return in a single request.
99
+
Used with the 'offset' parameter to implement pagination.
100
+
Higher values return more results but may increase response time.
101
+
Valid range: 1-100. Defaults to 10.`), mcp.DefaultNumber(10)),
49
102
),
50
103
MakeHandler: handleCoderListWorkspaces,
51
104
},
52
105
{
53
106
Tool: mcp.NewTool("coder_get_workspace",
54
-
mcp.WithDescription(`Get information about a workspace on a given Coder deployment.`),
55
-
mcp.WithString("workspace", mcp.Description(`The workspace ID or name to get.`), mcp.Required()),
107
+
mcp.WithDescription(`Get detailed information about a specific Coder workspace.
108
+
Returns comprehensive JSON with the workspace's configuration, status, and resources.
109
+
Use this to check workspace status before performing operations like exec or start/stop.
110
+
The response includes the latest build status, agent connectivity, and resource details.
111
+
112
+
Common errors:
113
+
- Workspace not found: Check the workspace name or ID
114
+
- Permission denied: The user may not have access to this workspace`),
115
+
mcp.WithString("workspace", mcp.Description(`The workspace ID (UUID) or name to retrieve.
116
+
Can be specified as either:
117
+
- Full UUID: e.g., "8a0b9c7d-1e2f-3a4b-5c6d-7e8f9a0b1c2d"
118
+
- Workspace name: e.g., "dev", "python-project"
119
+
Use coder_list_workspaces first if you're not sure about available workspace names.`), mcp.Required()),
56
120
),
57
121
MakeHandler: handleCoderGetWorkspace,
58
122
},
59
123
{
60
124
Tool: mcp.NewTool("coder_workspace_exec",
61
-
mcp.WithDescription(`Execute a command in a remote workspace on a given Coder deployment.`),
62
-
mcp.WithString("workspace", mcp.Description(`The workspace ID or name in which to execute the command in. The workspace must be running.`), mcp.Required()),
63
-
mcp.WithString("command", mcp.Description(`The command to execute. Changing the working directory is not currently supported, so you may need to preface the command with 'cd /some/path && <my-command>'.`), mcp.Required()),
125
+
mcp.WithDescription(`Execute a shell command in a remote Coder workspace.
126
+
Runs the specified command and returns the complete output (stdout/stderr).
127
+
Use this for file operations, running build commands, or checking workspace state.
128
+
The workspace must be running with a connected agent for this to succeed.
129
+
130
+
Before using this tool:
131
+
1. Verify the workspace is running using coder_get_workspace
132
+
2. Start the workspace if needed using coder_start_workspace
133
+
134
+
Common errors:
135
+
- Workspace not running: Start the workspace first
136
+
- Command not allowed: Check security restrictions
137
+
- Agent not connected: The workspace may still be starting up`),
138
+
mcp.WithString("workspace", mcp.Description(`The workspace ID (UUID) or name where the command will execute.
139
+
Can be specified as either:
140
+
- Full UUID: e.g., "8a0b9c7d-1e2f-3a4b-5c6d-7e8f9a0b1c2d"
141
+
- Workspace name: e.g., "dev", "python-project"
142
+
The workspace must be running with a connected agent.
143
+
Use coder_get_workspace first to check the workspace status.`), mcp.Required()),
144
+
mcp.WithString("command", mcp.Description(`The shell command to execute in the workspace.
145
+
Commands are executed in the default shell of the workspace.
146
+
147
+
Examples:
148
+
- "ls -la" - List files with details
149
+
- "cd /path/to/directory && command" - Execute in specific directory
150
+
- "cat ~/.bashrc" - View a file's contents
151
+
- "python -m pip list" - List installed Python packages
152
+
153
+
Note: Commands are subject to security restrictions and validation.
154
+
Very long-running commands may time out.`), mcp.Required()),
64
155
),
65
156
MakeHandler: handleCoderWorkspaceExec,
66
157
},
67
158
{
68
159
Tool: mcp.NewTool("coder_start_workspace",
69
-
mcp.WithDescription(`Start a workspace on a given Coder deployment.`),
70
-
mcp.WithString("workspace", mcp.Description(`The workspace ID or name to start.`), mcp.Required()),
160
+
mcp.WithDescription(`Start a stopped Coder workspace.
161
+
Initiates the workspace build process to provision and start all resources.
162
+
Only works on workspaces that are currently stopped or failed.
163
+
Starting a workspace is an asynchronous operation - it may take several minutes to complete.
164
+
165
+
After calling this tool:
166
+
1. Use coder_report_task to inform the user that the workspace is starting
167
+
2. Use coder_get_workspace periodically to check for completion
168
+
169
+
Common errors:
170
+
- Workspace already running/starting: No action needed
171
+
- Quota limits exceeded: User may have reached resource limits
172
+
- Template error: The underlying template may have issues`),
173
+
mcp.WithString("workspace", mcp.Description(`The workspace ID (UUID) or name to start.
174
+
Can be specified as either:
175
+
- Full UUID: e.g., "8a0b9c7d-1e2f-3a4b-5c6d-7e8f9a0b1c2d"
176
+
- Workspace name: e.g., "dev", "python-project"
177
+
The workspace must be in a stopped state to be started.
178
+
Use coder_get_workspace first to check the current workspace status.`), mcp.Required()),
71
179
),
72
180
MakeHandler: handleCoderStartWorkspace,
73
181
},
74
182
{
75
183
Tool: mcp.NewTool("coder_stop_workspace",
76
-
mcp.WithDescription(`Stop a workspace on a given Coder deployment.`),
77
-
mcp.WithString("workspace", mcp.Description(`The workspace ID or name to stop.`), mcp.Required()),
184
+
mcp.WithDescription(`Stop a running Coder workspace.
185
+
Initiates the workspace termination process to shut down all resources.
186
+
Only works on workspaces that are currently running.
187
+
Stopping a workspace is an asynchronous operation - it may take several minutes to complete.
188
+
189
+
After calling this tool:
190
+
1. Use coder_report_task to inform the user that the workspace is stopping
191
+
2. Use coder_get_workspace periodically to check for completion
192
+
193
+
Common errors:
194
+
- Workspace already stopped/stopping: No action needed
195
+
- Cancellation failed: There may be issues with the underlying infrastructure
196
+
- User doesn't own workspace: Permission issues`),
197
+
mcp.WithString("workspace", mcp.Description(`The workspace ID (UUID) or name to stop.
198
+
Can be specified as either:
199
+
- Full UUID: e.g., "8a0b9c7d-1e2f-3a4b-5c6d-7e8f9a0b1c2d"
200
+
- Workspace name: e.g., "dev", "python-project"
201
+
The workspace must be in a running state to be stopped.
202
+
Use coder_get_workspace first to check the current workspace status.`), mcp.Required()),
0 commit comments