How the Desktop Commander Prompts System Works with GetPromptsArgsSchema

The Desktop Commander MCP server validates and retrieves onboarding prompts through the get_prompts tool, which uses GetPromptsArgsSchema to enforce that callers provide a get_prompt action and a valid promptId before returning content from a cached JSON catalog.

DesktopCommanderMCP provides an integrated prompts system that surfaces pre-built onboarding templates through the Model Context Protocol. The GetPromptsArgsSchema acts as the gatekeeper for this system, ensuring that all requests to the get_prompts tool contain properly formatted parameters before the server retrieves content from the static JSON catalog.

Understanding the GetPromptsArgsSchema Definition

In src/tools/schemas.ts, the argument validation logic is defined as a Zod schema called GetPromptsArgsSchema. This schema enforces strict typing on incoming tool calls to prevent malformed requests from reaching the business logic.

Required Parameters

The schema mandates two fields:

• action: A string enum that currently only accepts the value 'get_prompt'
• promptId: A string representing the UUID of the specific prompt to retrieve

According to the DesktopCommanderMCP source code in src/tools/schemas.ts, these constraints ensure that the tool receives only actionable, identifiable requests.

Loading and Caching Prompt Data

Before the tool can serve content, the system loads the prompt catalog from disk. The loadPromptsData() function in src/tools/prompts.ts reads data/onboarding-prompts.json once and caches the results in memory. This prevents redundant file system operations during high-frequency tool invocations, as implemented in src/tools/prompts.ts.

Tool Implementation and Validation

The getPrompts() function in src/tools/prompts.ts serves as the entry point for all prompt-related requests. It first validates the incoming arguments against GetPromptsArgsSchema, then dispatches to the appropriate handler based on the action type.

The get_prompt Action

When validation passes and action equals 'get_prompt', the function calls getPrompt(promptId) to extract the specific entry from the cached catalog and return its content according to the implementation in src/tools/prompts.ts.

Backward Compatibility Handling

The codebase maintains references to legacy actions like list_prompts, but these currently return deprecation errors rather than active functionality. This ensures that outdated client implementations receive clear migration signals instead of silent failures.

Server Registration

The get_prompts tool is registered in src/server.ts as part of the available tools list. The registration uses zodToJsonSchema(GetPromptsArgsSchema) to automatically generate the JSON Schema description that clients receive when discovering server capabilities, as seen in the DesktopCommanderMCP source.

Usage Tracking and Onboarding Flow

Beyond serving content, the prompts system tracks engagement through src/utils/usageTracker.ts. When a user successfully invokes a prompt, the tracker sets promptsUsed = true, which suppresses the onboarding banner in subsequent sessions according to the implementation in src/utils/usageTracker.ts.

Practical Implementation Examples

Retrieve a specific onboarding prompt (e.g., "Organize my Downloads folder"):

import { getPrompts } from './tools/prompts.js';

// Action must be 'get_prompt' and promptId must match an entry in onboarding-prompts.json
const result = await getPrompts({
  action: 'get_prompt',
  promptId: 'onb2_01',   // ID for "Organize my Downloads folder"
});

console.log(result.content[0].text);

Server-side tool definition showing schema integration:

// Inside server.ts – the tool definition
{
  name: "get_prompts",
  description: `Retrieve a specific Desktop Commander onboarding prompt …`,
  inputSchema: zodToJsonSchema(GetPromptsArgsSchema), // <- schema link
  annotations: { title: "Get Prompts", readOnlyHint: true },
}

Client-side invocation from a UI widget:

await callTool('get_prompts', {
  action: 'get_prompt',
  promptId: 'onb2_03',   // "Create organized knowledge base"
});

Summary

• GetPromptsArgsSchema enforces strict validation on get_prompts tool calls, requiring a 'get_prompt' action and a valid promptId
• Prompt data is loaded once from data/onboarding-prompts.json and cached via loadPromptsData() to optimize performance
• The getPrompts() function dispatches validated requests to getPrompt() to retrieve specific content from the catalog
• Server registration in src/server.ts exposes the tool using Zod-to-JSON Schema conversion for automatic client discovery
• Usage tracking via usageTracker.ts prevents redundant onboarding prompts by setting promptsUsed = true after first invocation

Frequently Asked Questions

What actions are supported by GetPromptsArgsSchema?

Currently, only the 'get_prompt' action is fully supported. While legacy actions like list_prompts exist in the codebase for backward compatibility, they return deprecation errors and should not be used in new implementations.

Where does DesktopCommanderMCP store the actual prompt content?

The prompt definitions reside in data/onboarding-prompts.json at the repository root. The loadPromptsData() function in src/tools/prompts.ts reads this file once at startup and caches the contents in memory to serve subsequent requests without disk I/O.

How does the server prevent invalid prompt requests?

All incoming requests pass through GetPromptsArgsSchema validation in src/tools/schemas.ts before reaching the business logic. The Zod schema enforces that the action field equals 'get_prompt' and that promptId is a string, rejecting malformed parameters with validation errors.

Why does the onboarding banner disappear after using a prompt?

The usageTracker.ts utility monitors prompt engagement and sets a promptsUsed flag to true upon successful invocation. This state suppresses the onboarding interface in future sessions, creating a cleaner user experience for returning users.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}