Desktop Commander MCP Tool History: Data Structure and Recovery Guide

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 (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 (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:

~/.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:

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

To extract the last five entries programmatically:

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 (lines 1141–1146) exposes the /clientHistory endpoint that returns the current history state. The handlers in src/handlers/history-handlers.ts process these requests, returning metadata and the full record array:

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 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, 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
• Recovery Methods: Access history directly via filesystem operations or through the /clientHistory HTTP endpoint implemented in src/server.ts (lines 1141–1146) and handled by 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 (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. 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. This endpoint returns a JSON object containing totalEntries, oldestEntry, newestEntry, and the full history array, as implemented in 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 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.

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