feat(mcp): add $history variable and structured response format by andrewgazelka · Pull Request #17132 · nushell/nushell

andrewgazelka · 2025-12-08T18:01:25Z

Add $history variable that stores all previous command outputs
Access by index: $history.0, $history.1, etc.
Wrap all responses in structured record with:
- history_index: 0-based index of result in history
- cwd: current working directory after command
- output: command output (possibly truncated)
Truncate large outputs (>10k chars by default) and reference history
Configurable threshold via NU_MCP_OUTPUT_TRUNCATE env var
Remove moka caching (incompatible with history tracking)
Update instructions.md with history documentation

🤖 Generated with Claude Code

- Add `$history` variable that stores all previous command outputs - Access by index: `$history.0`, `$history.1`, etc. - Wrap all responses in structured record with: - `history_index`: 0-based index of result in history - `cwd`: current working directory after command - `output`: command output (possibly truncated) - Truncate large outputs (>10k chars by default) and reference history - Configurable threshold via `NU_MCP_OUTPUT_TRUNCATE` env var - Remove moka caching (incompatible with history tracking) - Update instructions.md with history documentation 🤖 Generated with [Claude Code](https://claude.com/claude-code)

- Rename NU_MCP_OUTPUT_TRUNCATE to NU_MCP_OUTPUT_LIMIT - Read from $env.NU_MCP_OUTPUT_LIMIT first (nushell native) - Fall back to process env var if not set in nushell - Add test for nushell env var configuration

crates/nu-mcp/src/instructions.md

crates/nu-mcp/src/evaluation.rs

…ions - Remove process env var fallback for NU_MCP_OUTPUT_LIMIT - Only use nushell's $env.NU_MCP_OUTPUT_LIMIT (typed int) - Convert output_limit and register_history_variable to free-standing functions - Use inline paths instead of grouped imports (per Rust conventions) - Update instructions.md to clarify $history is list<any> and limit is bytes 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

crates/nu-mcp/src/instructions.md

Include unit (bytes) in the env var name for clarity. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- NU_MCP_OUTPUT_LIMIT now accepts filesize (e.g., 10kb) - No default fallback - truncation only happens when explicitly configured - Returns Option<usize> instead of silently defaulting

Response format now has distinct fields: - Normal: {cwd, history_index, output} - Truncated: {cwd, history_index, note}

🤖 Generated with [Claude Code](https://claude.com/claude-code)

fdncred · 2025-12-08T18:40:53Z

I'm not sure how I feel about this history functionality taking infinite memory. Yes, we can truncate each at 10k or whatever is set but a bazillion 10k's will still be too much memory. There should be a way to reclaim unused or old items.

Previously truncation only occurred when NU_MCP_OUTPUT_LIMIT was explicitly set. Now defaults to 10kb, with 0 to disable truncation. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

andrewgazelka · 2025-12-08T19:37:54Z

I'm not sure how I feel about this history functionality taking infinite memory. Yes, we can truncate each at 10k or whatever is set but a bazillion 10k's will still be too much memory. There should be a way to reclaim unused or old items.

it is just a variable so the model could technically modify it itself I think? have any specific ideas? we could alternateively also have $history only store the last x entries

andrewgazelka · 2025-12-08T20:40:37Z

Claude: Re: memory concerns - a few options to consider:

Ring buffer: Store only the last N entries (e.g., 100). Simple and predictable.
Max total size: Cap total history memory (e.g., 10MB), evicting oldest entries when exceeded.
User-controlled: Let users clear history via $history = [] or add a $env.NU_MCP_HISTORY_LIMIT env var.
LRU eviction: Evict least-recently-accessed entries (more complex to implement).

Given this is for MCP (AI tool use), conversations tend to be short-lived. A simple ring buffer of ~50-100 entries would likely cover most use cases while bounding memory. What do you think?

fdncred · 2025-12-08T21:05:52Z

I'd vote for a ring buffer for X items of Y count/bytes/filesize but $history would probably also need a timedate stamp to know which item is the latest.

Addresses reviewer feedback about unbounded memory growth: - History is now stored as a ring buffer (VecDeque) with configurable limit - Default limit is 100 entries, configurable via NU_MCP_HISTORY_LIMIT env var - Each history entry is now a record with `timestamp` and `value` fields - Oldest entries are evicted when the limit is reached Breaking change: History entries are now accessed via $history.N.value instead of $history.N directly. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

- Move timestamp from history entries to the response record - History now stores just values directly ($history.0 instead of $history.0.value) - Response includes: cwd, history_index, timestamp, output/note - Ring buffer behavior unchanged (default 100 entries, configurable) 🤖 Generated with [Claude Code](https://claude.com/claude-code)

crates/nu-mcp/src/evaluation.rs

- Replace inline paths with proper use statements at file top - Extract history-related code into dedicated history.rs module - History struct now encapsulates ring buffer and variable registration - Cleaner separation of concerns between evaluation and history management 🤖 Generated with [Claude Code](https://claude.com/claude-code)

andrewgazelka · 2025-12-10T00:16:52Z

@fdncred All review threads addressed and resolved. Let me know if there's anything else needed for approval!

ayax79 · 2025-12-10T06:56:24Z

@andrewgazelka I am doing a bit of testing. If all goes well, I'll merge tomorrow.

ayax79 · 2025-12-10T17:33:29Z

working well so far, thanks!

andrewgazelka added 3 commits December 8, 2025 09:59

Merge upstream/main and integrate persistent REPL state with history

b037e7a

refactor(mcp): use idiomatic nushell env var for output limit

7570fe7

- Rename NU_MCP_OUTPUT_TRUNCATE to NU_MCP_OUTPUT_LIMIT - Read from $env.NU_MCP_OUTPUT_LIMIT first (nushell native) - Fall back to process env var if not set in nushell - Add test for nushell env var configuration

fdncred reviewed Dec 8, 2025

View reviewed changes

crates/nu-mcp/src/instructions.md Outdated Show resolved Hide resolved

update

7b75bec

andrewgazelka commented Dec 8, 2025

View reviewed changes

crates/nu-mcp/src/evaluation.rs Outdated Show resolved Hide resolved

update docs

d3bf1e3

andrewgazelka force-pushed the feature/mcp-history-variable branch from 7ffbdbb to d3bf1e3 Compare December 8, 2025 18:18

andrewgazelka commented Dec 8, 2025

View reviewed changes

crates/nu-mcp/src/evaluation.rs Show resolved Hide resolved

andrewgazelka and others added 2 commits December 8, 2025 10:21

update

416e658

andrewgazelka commented Dec 8, 2025

View reviewed changes

crates/nu-mcp/src/instructions.md Outdated Show resolved Hide resolved

andrewgazelka and others added 2 commits December 8, 2025 10:25

refactor(mcp): rename env var to NU_MCP_OUTPUT_LIMIT_BYTES

4c3a61d

Include unit (bytes) in the env var name for clarity. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

refactor(mcp): use filesize type for output limit, no fallback

fb1d8ce

- NU_MCP_OUTPUT_LIMIT now accepts filesize (e.g., 10kb) - No default fallback - truncation only happens when explicitly configured - Returns Option<usize> instead of silently defaulting

andrewgazelka force-pushed the feature/mcp-history-variable branch from 966252f to fb1d8ce Compare December 8, 2025 18:30

andrewgazelka added 2 commits December 8, 2025 10:31

refactor(mcp): use note field for truncation instead of output

c18d590

Response format now has distinct fields: - Normal: {cwd, history_index, output} - Truncated: {cwd, history_index, note}

style: fix formatting in evaluation.rs

d2462eb

🤖 Generated with [Claude Code](https://claude.com/claude-code)

andrewgazelka marked this pull request as ready for review December 8, 2025 18:36

feat(mcp): default output limit to 10kb

ec9f639

Previously truncation only occurred when NU_MCP_OUTPUT_LIMIT was explicitly set. Now defaults to 10kb, with 0 to disable truncation. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

andrewgazelka added 2 commits December 9, 2025 01:47

fdncred reviewed Dec 9, 2025

View reviewed changes

crates/nu-mcp/src/evaluation.rs Show resolved Hide resolved

ayax79 merged commit 11d71fe into nushell:main Dec 10, 2025
17 checks passed

github-actions bot added this to the v0.110.0 milestone Dec 10, 2025

fdncred added the A:MCP Model Context Protocol (nu-mcp) label Dec 12, 2025

andrewgazelka mentioned this pull request Dec 13, 2025

[MCP] Self-sufficient nushell for remote AI coding sessions #17160

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(mcp): add $history variable and structured response format#17132

feat(mcp): add $history variable and structured response format#17132
ayax79 merged 15 commits intonushell:mainfrom
andrewgazelka:feature/mcp-history-variable

andrewgazelka commented Dec 8, 2025 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

fdncred commented Dec 8, 2025

Uh oh!

andrewgazelka commented Dec 8, 2025

Uh oh!

andrewgazelka commented Dec 8, 2025

Uh oh!

fdncred commented Dec 8, 2025 •

edited

Loading

Uh oh!

Uh oh!

andrewgazelka commented Dec 10, 2025

Uh oh!

ayax79 commented Dec 10, 2025

Uh oh!

ayax79 commented Dec 10, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

andrewgazelka commented Dec 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

fdncred commented Dec 8, 2025

Uh oh!

andrewgazelka commented Dec 8, 2025

Uh oh!

andrewgazelka commented Dec 8, 2025

Uh oh!

fdncred commented Dec 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

andrewgazelka commented Dec 10, 2025

Uh oh!

ayax79 commented Dec 10, 2025

Uh oh!

ayax79 commented Dec 10, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

andrewgazelka commented Dec 8, 2025 •

edited

Loading

fdncred commented Dec 8, 2025 •

edited

Loading