Skip to content

refactor(mcp): trim model-facing instructions #320

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Waishnav wants to merge 2 commits into from
Open

refactor(mcp): trim model-facing instructions #320

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c4ab2ef
refactor(mcp): trim server model instructions
Waishnav Sep 7, 2026
7191afb
refactor(mcp): simplify tool descriptions
Waishnav Sep 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions src/artifact-tools.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,10 +98,10 @@ export function registerArtifactTools(
{
title: "Download attached or generated file",
description:
"Stream one MCP-host-provided native file to a requested relative path inside a workspace. Existing destinations, arbitrary URLs, absolute paths, traversal, symlinked parents, source filesystem paths, and malformed file objects are rejected.",
"Save an attached or generated file to a relative path inside a workspace. The destination must not already exist.",
inputSchema: {
file: openAIFileReferenceInputSchema.describe(
"Native file value authorized and supplied by the MCP host.",
"Attached or generated file to save.",
),
workspace_id: z.string().min(1).describe(
"Workspace to use. Reuse the current project's workspace_id.",
Expand Down
14 changes: 7 additions & 7 deletions src/server.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -126,15 +126,15 @@ function serverInstructions(
): string {
const artifactInstruction =
config.artifactsEnabled && isArtifactDownloadSupportedPlatform()
? " When the user supplies or generates a file that is not present on the DevSpace host, use download_artifact with its native file value, the existing workspace ID, and a suitable relative destination path chosen from the user's request and project structure. The tool refuses to overwrite an existing destination and returns the normalized workspace-relative path. Use normal workspace tools when explicit inspection, replacement, movement, renaming, or deletion is needed. Do not recreate binary files with write/edit calls or place signed URLs, native file objects, base64 content, or invented host paths in shell commands or logs."
? " When the user provides an attached or generated file that needs to be added to the workspace, pass the provided file directly to download_artifact with the existing workspace_id and a suitable relative destination path. Do not reconstruct attached files manually."
: "";
const showChangesInstruction =
" If the turn successfully modifies files by creating, editing, overwriting, deleting, moving, or applying patches, call show_changes exactly once for that workspace after the final related file change and before your final response so the user can inspect the aggregate diff for that turn. Do not call it after every individual file change.";
" If files are modified, call show_changes once after the final related change and before the final response.";
const skills = config.skillsEnabled
? `When ${toolNames.openWorkspace} returns available skills and a task matches a skill, use ${toolNames.read} to read that skill's path before proceeding. Skill paths may be outside the workspace, and ${toolNames.read} permits files within advertised skill directories. `
? `When ${toolNames.openWorkspace} returns available skills and a task matches one, use ${toolNames.read} with the returned skill path before proceeding. `
: "";
const agents = `Follow instructions returned by ${toolNames.openWorkspace}. Before working under a path listed in available_agents_files, use ${toolNames.read} to inspect that instruction file and follow it. `;
const common = `Use DevSpace for coding work. Call ${toolNames.openWorkspace} once for each project folder or isolated worktree, then keep using its workspace_id. During continued work in the same project or worktree, do not call ${toolNames.openWorkspace} again. Open another workspace only when changing projects, switching checkout/worktree mode, creating another isolated worktree, or when the current workspace_id is rejected.`;
const common = `Call ${toolNames.openWorkspace} when starting work in a project folder or isolated worktree without a usable workspace_id, then reuse the returned workspace_id for subsequent operations in that workspace.`;

return `${common} ${toolSurface.instructions({ agents, skills })}${artifactInstruction}${showChangesInstruction}`;
}
Expand Down Expand Up @@ -619,10 +619,10 @@ function registerMcpSurface(
title: "Read file",
description:
[
"Read a file in a workspace. Use this for file inspection instead of shell commands like cat or sed.",
"Read all or part of a file in a workspace.",
"Use this tool to inspect relevant AGENTS.md or CLAUDE.md files listed by open_workspace before working in nested directories.",
config.skillsEnabled
? "If available skills were returned and a task matches one, read that skill's path before proceeding. Skill paths may be outside the workspace; files within advertised skill directories are readable."
? "If available skills were returned and a task matches one, read the returned skill path before proceeding."
: "",
]
.filter(Boolean)
Expand All @@ -635,7 +635,7 @@ function registerMcpSurface(
.string()
.describe(
config.skillsEnabled
? "File path to read, relative to the workspace root. May also be an advertised skill path from open_workspace skills."
? "File path relative to the workspace root, or a skill path returned by open_workspace."
: "File path to read, relative to the workspace root.",
),
offset: z
Expand Down
9 changes: 5 additions & 4 deletions src/tool-surfaces/claude.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ import {
textBlock,
} from "./shared.js";

const CLAUDE_INSTRUCTIONS = `Use ${toolNames.read} for direct file reads, ${toolNames.edit} for targeted modifications, ${toolNames.write} only for new files or complete rewrites, and ${toolNames.shell} for inspection, tests, builds, and other commands. Shell commands run with the local user's authority and are not sandboxed; workspace validation only selects their initial working directory. Follow instructions returned by ${toolNames.openWorkspace}; read applicable instruction and skill files before working in their scope.`;
const CLAUDE_INSTRUCTIONS = `Follow instructions returned by ${toolNames.openWorkspace}; read applicable instruction and skill files before working in their scope.`;

export function claudeInstructions({
agents,
Expand All @@ -36,7 +36,7 @@ export function registerClaudeTools(context: ToolRegistrationContext): void {
registerShellTool(context);
}

const CLAUDE_SHELL_DESCRIPTION = `Run a shell command with the local user's authority. Commands are not sandboxed; workspace validation only selects the initial working directory. Use this for file inspection, tests, builds, package scripts, and other commands.`;
const CLAUDE_SHELL_DESCRIPTION = "Run a shell command in a workspace with the user's local permissions.";

@greptile-apps greptile-apps Bot Sep 7, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 security Shell containment is ambiguous

The shell descriptions now say commands run “in a workspace” but omit that only the initial working directory is validated. Both handlers execute unrestricted commands with the user’s local permissions, so a model may infer workspace containment and use absolute paths or parent traversal that modifies resources outside the workspace. Keep an explicit statement that shell execution is not sandboxed; the same issue appears in src/tool-surfaces/codex.ts:142.

How this was verified: Both command handlers validate the initial working directory but execute the raw command without restricting absolute paths, parent traversal, or access to other local resources.

@Waishnav Waishnav Sep 7, 2026

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it's fine buddy


function registerClaudeMutationTools(context: ToolRegistrationContext): void {
const { server, config, workspaces } = context;
Expand All @@ -45,7 +45,7 @@ function registerClaudeMutationTools(context: ToolRegistrationContext): void {
toolNames.write,
{
title: "Write file",
description: `Create or completely overwrite a file in a workspace. Prefer ${toolNames.edit} for targeted changes to existing files.`,
description: "Create or completely overwrite a file in a workspace.",
inputSchema: {
workspace_id: z.string().describe(workspaceIdDescription),
path: z
Expand Down Expand Up @@ -101,7 +101,8 @@ function registerClaudeMutationTools(context: ToolRegistrationContext): void {
toolNames.edit,
{
title: "Edit file",
description: `Edit one file in a workspace by replacing exact text blocks. Prefer this over ${toolNames.write} for targeted changes. Each old_text must match a unique, non-overlapping region of the original file; merge nearby changes into one edit and keep old_text as small as possible while still unique.`,
description:
"Edit one file in a workspace by replacing exact text blocks. Each old_text must match a unique, non-overlapping region of the original file.",
inputSchema: {
workspace_id: z.string().describe(workspaceIdDescription),
path: z
Expand Down
6 changes: 3 additions & 3 deletions src/tool-surfaces/codex.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ import {

type CodexRegistration = (context: ToolRegistrationContext) => void;

const CODEX_INSTRUCTIONS = `Use ${toolNames.read} for direct file reads, apply_patch for all file modifications, exec_command for inspection, tests, builds, and other commands, and write_stdin to poll or interact with running processes. Commands run with the local user's authority and are not sandboxed; workspace validation only selects their initial working directory. Follow instructions returned by ${toolNames.openWorkspace}; read applicable instruction and skill files before working in their scope.`;
const CODEX_INSTRUCTIONS = `Follow instructions returned by ${toolNames.openWorkspace}; read applicable instruction and skill files before working in their scope.`;

export function codexInstructions(): string {
return CODEX_INSTRUCTIONS;
Expand Down Expand Up @@ -84,7 +84,7 @@ function registerApplyPatchTool(context: ToolRegistrationContext): void {
{
title: "Apply patch",
description:
"Apply one Codex-style patch in a workspace. Supports adding, overwriting, updating, deleting, and moving files. Use this for all file modifications. Paths must be relative to the workspace.",
"Apply one Codex-style patch to add, overwrite, update, delete, or move workspace files. Paths must be relative to the workspace.",
inputSchema: {
workspace_id: z.string().describe(workspaceIdDescription),
patch: z
Expand Down Expand Up @@ -146,7 +146,7 @@ function registerCodexProcessTools(context: ToolRegistrationContext): void {
{
title: "Execute command",
description:
"Run a command with the local user's authority. Commands are not sandboxed; workspace validation only selects the initial working directory. Returns the result when it exits during the yield window, otherwise returns a session_id to continue with write_stdin. Use this for file inspection, tests, builds, package scripts, and long-running processes.",
"Run a shell command in a workspace with the user's local permissions. Returns the result when it exits during the yield window, otherwise returns a session_id for write_stdin.",
inputSchema: {
workspace_id: z.string().describe(workspaceIdDescription),
cmd: z.string().min(1).describe("Shell command to execute."),
Expand Down
Loading