# Desktop Commander MCP Tool History: Data Structure and Recovery Guide

> Understand the Desktop Commander MCP tool history data structure found in tool-history.jsonl. Learn how to recover this data for debugging and client history retrieval.

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

---

**Desktop Commander MCP persists every tool invocation in a JSON Lines file at `~/.claude-server-commander/tool-history.jsonl`, maintaining a rolling buffer of 1,000 records that can be read directly from disk or retrieved via the `/clientHistory` HTTP endpoint for debugging.**

Desktop Commander MCP tracks all tool calls—such as `read_file`, `write_file`, and `edit_block`—in a structured **tool history** that enables session restoration and debugging. This history is implemented as an in-memory array backed by a persistent JSON Lines file, with schemas defined in the TypeScript source and exposed through a REST API. Understanding this architecture is essential for troubleshooting failed commands or reconstructing lost chat context.

## Data Structure of the Tool History

The history system centers on the **`ToolCallRecord`** interface, which standardizes how tool invocations are captured and stored.

### ToolCallRecord Schema

According to [`src/tools/schemas.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/schemas.ts) (section *Tool history schema*), each history entry conforms to the **Tool Call Record** schema with the following fields:

- **`id`**: Unique identifier for the specific tool invocation
- **`tool_name`**: The MCP tool being executed (e.g., `read_file`, `write_file`)
- **`args`**: Serialized arguments passed to the tool
- **`started_at`**: Timestamp when execution began
- **`finished_at`**: Timestamp when execution completed
- **`output`**: Return value or result of the tool call
- **`error`**: Error message if the invocation failed

This schema ensures that every tool interaction is fully reconstructible from the stored data.

### In-Memory Storage

In [`src/utils/toolHistory.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/toolHistory.ts) (line 55), the `ToolHistory` class maintains a **`ToolCallRecord[]`** array named `history` that serves as the runtime cache. The implementation enforces a **hard cap of 1,000 entries** (`MAX_ENTRIES`), automatically dropping older records when this limit is exceeded to prevent unbounded memory growth.

### Persistent Storage Format

The on-disk representation is a **JSON Lines** file (`tool-history.jsonl`) stored in the user's home directory at:

```text
~/.claude-server-commander/tool-history.jsonl

```

Each line represents one serialized `ToolCallRecord`, allowing for efficient append-only writes and straightforward line-by-line parsing during recovery.

## How to Recover Tool History for Debugging

When investigating crashed sessions or analyzing tool usage patterns, you can extract the history using two primary methods: direct file access or the HTTP API.

### Reading the JSON Lines File Directly

The history file is plain text with one JSON object per line. You can inspect it using standard Unix tools or Node.js scripts:

```bash
cat ~/.claude-server-commander/tool-history.jsonl

```

To extract the last five entries programmatically:

```typescript
import * as fs from 'fs';
import * as path from 'path';
import * as os from 'os';

const historyPath = path.join(os.homedir(), '.claude-server-commander', 'tool-history.jsonl');

const lines = fs.readFileSync(historyPath, 'utf-8')
  .trim()
  .split('\n')
  .slice(-5);

const recentCalls = lines.map(l => JSON.parse(l));
console.log('Recent tool calls:', recentCalls);

```

### Accessing History via the REST API

While the MCP server is running, [`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts) (lines 1141–1146) exposes the **`/clientHistory`** endpoint that returns the current history state. The handlers in [`src/handlers/history-handlers.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/handlers/history-handlers.ts) process these requests, returning metadata and the full record array:

```javascript
fetch('http://localhost:3000/clientHistory')
  .then(r => r.json())
  .then(data => {
    console.log('History metadata:', {
      total: data.totalEntries,
      oldest: data.oldestEntry,
      newest: data.newestEntry
    });
    console.log('Full history array:', data.history);
  });

```

This endpoint is particularly useful when the client needs to reconstruct the session state without direct filesystem access.

### Handling Corrupted or Stale Data

If the in-memory cache appears inconsistent with recent operations:

1. **Stop** the Desktop Commander MCP process
2. **Backup or delete** the `~/.claude-server-commander/tool-history.jsonl` file
3. **Restart** the server

The `ToolHistory` constructor in [`src/utils/toolHistory.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/toolHistory.ts) will recreate the file automatically and begin populating it with new tool calls, ensuring a clean state for debugging.

## Summary

- **Data Structure**: Desktop Commander MCP stores tool history as an array of `ToolCallRecord` objects defined in [`src/tools/schemas.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/schemas.ts), capturing tool names, arguments, timestamps, outputs, and errors
- **Storage Location**: History persists to `~/.claude-server-commander/tool-history.jsonl` as JSON Lines with a default limit of 1,000 entries managed in [`src/utils/toolHistory.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/toolHistory.ts)
- **Recovery Methods**: Access history directly via filesystem operations or through the `/clientHistory` HTTP endpoint implemented in [`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts) (lines 1141–1146) and handled by [`src/handlers/history-handlers.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/handlers/history-handlers.ts)
- **Debugging Workflow**: For stale data, delete the JSONL file and restart the server to force a fresh history initialization

## Frequently Asked Questions

### Where is the Desktop Commander MCP tool history stored on disk?

The tool history is stored in a JSON Lines file located at `~/.claude-server-commander/tool-history.jsonl` within the user's home directory. According to [`src/utils/toolHistory.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/toolHistory.ts) (line 55), this path is constructed at runtime, and the file contains one JSON object per line representing each `ToolCallRecord`.

### What is the maximum number of tool calls kept in the history?

The system maintains a rolling buffer of **1,000 entries** defined by the `MAX_ENTRIES` constant in [`src/utils/toolHistory.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/toolHistory.ts). When this limit is reached, older entries are automatically discarded to conserve memory and disk space while preserving the most recent activity.

### How can I programmatically access the tool history without filesystem access?

You can query the **`/clientHistory`** HTTP endpoint exposed by the server in [`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts). This endpoint returns a JSON object containing `totalEntries`, `oldestEntry`, `newestEntry`, and the full `history` array, as implemented in [`src/handlers/history-handlers.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/handlers/history-handlers.ts), making it accessible to clients running in sandboxed environments.

### What data fields are included in each tool history record?

Each record follows the `ToolCallRecord` schema from [`src/tools/schemas.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/schemas.ts) and includes: `id` (unique identifier), `tool_name` (command executed), `args` (parameters), `started_at`/`finished_at` (timestamps), `output` (results), and `error` (failure messages if applicable). These fields provide complete provenance for debugging tool execution flow.