# How the Desktop Commander Prompts System Works with GetPromptsArgsSchema

> Discover how the Desktop Commander prompts system utilizes GetPromptsArgsSchema to validate and retrieve onboarding prompts efficiently. Learn about the get prompts tool and its argument schema for cached catalog content.

- Repository: [Eduard Ruzga/DesktopCommanderMCP](https://github.com/wonderwhy-er/DesktopCommanderMCP)
- Tags: internals
- Published: 2026-07-10

---

**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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/prompts.ts) reads [`data/onboarding-prompts.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/prompts.ts).

## Tool Implementation and Validation

The `getPrompts()` function in [`src/tools/prompts.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/usageTracker.ts).

## Practical Implementation Examples

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

```typescript
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:

```typescript
// 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:

```typescript
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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts) exposes the tool using Zod-to-JSON Schema conversion for automatic client discovery
- **Usage tracking** via [`usageTracker.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/data/onboarding-prompts.json) at the repository root. The `loadPromptsData()` function in [`src/tools/prompts.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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.