v0.2.1

This release improves watch mode reliability, adds safeguards for AI assistant workflows, and expands test coverage for validation and error handling paths.

---

Added

Watch Mode Reliability

• Retry logic for bundle reads during watch mode
• Initial delay: 200ms (watch) / 500ms (strict watch)
• Up to 3 retries with exponential backoff
• Prevents race conditions while bundles are written
• Applies to:
  • logicstamp_read_bundle
  • logicstamp_list_bundles

AI Assistant Safety Warnings

• Added ⚠️ “Do NOT use sleep() delays” warning to relevant MCP tools
• Tools updated:
  • logicstamp_watch_status
  • logicstamp_list_bundles
  • logicstamp_read_bundle
  • logicstamp_refresh_snapshot
• Tool outputs now include warnings when watch mode is active
• Documentation updated accordingly

Test Coverage

• Expanded validation and error-handling test coverage
• Added tests for:
  • filesystem root detection
  • invalid docPath
  • depth validation
  • bundle hash comparisons
  • missing contract handling
  • cache corruption detection
• Exported readDocFile helper for defensive validation testing

---

🐞 Fixed

TypeScript File Validation

• Fixed issue where TypeScript source files could trigger misleading JSON parse errors in retry logic
• Retry logic now detects TypeScript files (starting with import or export) before JSON parsing
• Ensures proper error messages when users accidentally point to source files instead of bundle JSON

---

🔗 Related PRs

• #35 – Watch mode retry logic & AI assistant delay warnings
• #36 – Branch coverage expansion and validation tests

---

🔀 Compare changes

👉 Full changelog

v0.2.0

This release aligns MCP with the LogicStamp CLI runtime (Node.js 20+), improves watch mode reliability (including strict watch awareness), and significantly strengthens test coverage.

---

⚠️ Breaking Change

Node.js 20+ Required

• Minimum Node.js version is now >= 20
• Aligns MCP with logicstamp-context
• Users on Node.js 18 must upgrade

---

⚙️ Improvements

Watch Mode Enhancements

• Added strictWatch detection in watch status output
• Improved distinction between ROOT components and DEPENDENCIES
• Cleanup of stale watch status files when processes exit
• Updated schemas to reflect strict watch field

Documentation Updates

• Updated Node.js requirement across all docs
• Improved README structure and clarity
• Clarified skipIfWatchActive behavior
• Updated roadmap formatting

Expanded Test Coverage

• Added comprehensive watch mode tests
• Improved validation and error-path coverage
• Strengthened bundle and docs reading validation
• All tests passing

---

🔗 Related PRs

• #26 – Watch mode improvements & strict watch detection
• #27 – Node.js requirement alignment & documentation updates
• #28 – README & roadmap improvements
• #29 – Test coverage expansion

---

🔀 Compare changes

👉 Full changelog

v0.1.6

This release optimizes MCP tool descriptions for better LLM comprehension and improves code maintainability through refactoring.

---

⚙️ Changed

Tool Description Optimization

• Optimized all 7 MCP tool descriptions for better LLM comprehension
  • Reduced description length by ~40-50% while preserving all critical information
  • Removed redundancy (duplicate "WHAT IT DOES" sections, repeated watch mode explanations)
  • Consolidated related information into more scannable formats
  • Improved structure: Warning → What → Returns → When → Next → Options → Docs
  • All implementation details preserved - no functional changes
  • Watch mode workflows now clearly documented in all relevant tools
  • Makes it easier for LLMs to understand and use LogicStamp correctly

Code Refactoring

• Extracted duplicated isProcessRunning function into shared utility
  • Created src/mcp/utils/process-utils.ts with shared process checking logic
  • Removed duplicate implementations from watch-status.ts, read-bundle.ts, refresh-snapshot.ts, and list-bundles.ts
  • Improves code maintainability and makes future platform-specific fixes easier
  • No functional changes - behavior remains identical

---

📚 Documentation

• Updated version references to 0.1.6 across all documentation
• Enhanced documentation with watch mode integration details
• Added comprehensive watch status command documentation (docs/commands/watch-status.md)

---

✅ Non-Breaking Release

• Tool description changes are documentation-only
• Code refactoring maintains identical behavior
• No API or output format changes

---

🔗 Related PR

• #24 – Release v0.1.6

👉 Full changelog

v0.1.5 - MCP Watch Mode Awareness

Added

Watch Mode Awareness (MCP)

• Introduced watch mode awareness to the MCP server
• MCP can now detect and integrate with stamp context --watch
• Enables zero-cost, incremental workflows where context is kept continuously fresh
• Prevents unnecessary regeneration when watch mode is active

New Tool: logicstamp_watch_status

• Added a dedicated tool to inspect active watch mode state
• Reports:
  • active status
  • watcher PID
  • startedAt timestamp
  • whether context is being kept fresh
• Optional inclusion of recent watch logs:
  • files changed
  • modified contracts
  • modified bundles
• Enables AI assistants to decide whether regeneration can be skipped

Watch Mode Direct Access (No Snapshot Required)

• logicstamp_list_bundles and logicstamp_read_bundle now support direct access when watch mode is active
• New projectPath parameter allows usage without a snapshotId
• Snapshot creation can be skipped entirely in watch mode
• Tools automatically detect watch mode and indicate it in responses
• Enables the optimal workflow:
  watch_status → list_bundles(projectPath) → read_bundle(projectPath)

New Types

• Added TypeScript types for watch mode integration:
• WatchStatus
• WatchLogEntry
• WatchStatusInput
• WatchStatusOutput

---

Changed

Tooling & Workflow Defaults

• Increased MCP tool count from 6 → 7
• logicstamp_refresh_snapshot now defaults skipIfWatchActive to true when watch mode is active
• Previously required explicit opt-in
• Can be overridden with skipIfWatchActive: false
• All tool descriptions rewritten to explicitly guide LLMs to:
• Call logicstamp_watch_status first
• Follow the correct watch-aware workflow

Unified Watch-Aware Flow

• Tool descriptions now clearly document:
  watch_status
  ├─ (active) list_bundles → read_bundle
  └─ (inactive) refresh_snapshot → list_bundles → read_bundle
• logicstamp_refresh_snapshot responses now include structured watchMode metadata

---

Improved

• Significant performance improvement when watch mode is active
• Zero-cost context reads when context is already fresh
• Cleaner separation between snapshot-based and watch-based workflows
• More deterministic and predictable MCP behavior for long-running sessions

---

Docs & Maintenance

• Updated README with watch-aware MCP workflows
• Updated CHANGELOG for v0.1.5
• Updated integration and usage guides to reflect new tools and defaults
• Expanded tests to cover:
• watch mode detection
• skip logic
• error handling and edge cases

---

🔗 Related PRs

• #22
• #23

Impact:
This release enables MCP clients and AI assistants to operate against continuously refreshed context without regeneration overhead. When watch mode is active, LogicStamp MCP provides instant, zero-cost access to up-to-date context, making it suitable for long-running interactive and agent-driven workflows.

All changes are backward compatible. Watch mode remains opt-in, no schemas or public APIs were broken, and snapshot-based workflows continue to work unchanged.

---

Changelog

👉 Full changelog

v0.1.4 - Enhanced error messages & Comprehensive test coverage

Description

Added

• Comprehensive Test Coverage - Added 26 new tests significantly improving code coverage from ~78% to ~86%

  • Coverage Improvements: Overall coverage increased from ~78% to ~86% (statements, branches, lines)
  • Cache Cleanup Tests (10 tests) - Added tests for cache corruption detection, stale path detection, and cleanup logic
    • Tests for corrupted cache detection (invalid JSON in context_main.json)
    • Tests for stale cache detection (mismatched project paths in config files)
    • Tests for valid cache preservation and explicit cleanup
  • Parameter Validation Tests (7 tests) - Added comprehensive validation tests for depth parameter
    • Invalid depth values (non-integer, zero, negative)
    • Valid depth values (1, 3, default 2)
    • String-to-number conversion handling
  • Error Code Preservation Tests (4 tests) - Added tests ensuring error information is properly preserved
    • Error code preservation from exec errors
    • stdout/stderr preservation in error objects
    • ENOENT error handling for missing files
  • Server Error Handling Tests (4 tests) - Added tests for server-level error handling
    • Tool execution error wrapping in MCP format
    • Non-Error exception handling
    • Graceful error handling for all tools
  • Documentation Error Handling Tests (2 tests) - Added tests for error message structure and consistency
  • File Coverage Improvements:
    • compare-modes.ts: 60% → ~95% statements (+35%)
    • refresh-snapshot.ts: ~67% → ~96% statements (+29%)
  • Total test count: 163 → 189 tests (+26 tests)
  • All tests passing with improved confidence in error handling and edge cases

• Enhanced Error Messages - Improved error messages throughout all MCP tools to be more actionable and helpful

  • All error messages now include context about what was attempted and why it failed
  • Added suggestions for common errors (e.g., "Run logicstamp_refresh_snapshot first" when snapshot is missing)
  • Included relevant file paths and next steps in error messages
  • Error messages now guide users toward solutions instead of just reporting failures
  • Enhanced messages in: logicstamp_refresh_snapshot, logicstamp_list_bundles, logicstamp_read_bundle, logicstamp_compare_snapshot, logicstamp_compare_modes, logicstamp_read_logicstamp_docs
  • Example improvement: "context_main.json not found" → "context_main.json not found in /path/to/project. This file is required for comparison but hasn't been generated yet. Options: (1) Run logicstamp_refresh_snapshot first to generate context files, (2) Use forceRegenerate: true in this call to regenerate automatically before comparing, (3) Run 'stamp context' manually from the project directory."

• Code of Conduct - Added Contributor Covenant Code of Conduct to establish community standards and promote a respectful, inclusive environment

  • Available at CODE_OF_CONDUCT.md

• Roadmap - Added roadmap document outlining planned enhancements and future features to guide project development

  • Available at ROADMAP.md

Fixed

• Version Consistency - Fixed version mismatches across codebase to ensure all version references match package.json
  • README.md - Updated version badge from 0.1.2 to 0.1.4
  • src/mcp/server.ts - Updated server version from 0.1.2 to 0.1.4 (was incorrectly 0.1.2 for version 0.1.3)
  • docs/mcp_integration.md - Updated example config version from 0.1.2 to 0.1.4
  • All version references now consistently match package.json version 0.1.4
  • Prevents confusion when users check version information across different sources

Impact: This release significantly improves code quality, developer experience, and project governance.

• Test coverage increased from ~78% to ~86% with 26 new tests
• All MCP tools now provide actionable, context-rich error messages
• Version references are now synchronized across the entire codebase
• Community governance documents (Code of Conduct and Roadmap) added
• All changes are additive and fully backward compatible
• Existing functionality remains unchanged, only improved

Changelog

👉 Full changelog

v0.1.3 - Enhanced depth parameter and context_main.json read fix

Description

Changed

• Default Depth Parameter - Changed default dependency traversal depth from 1 to 2 across all tools
  • Default depth now includes nested components (e.g., App → Hero → Button) instead of only direct dependencies
  • Applies to logicstamp_refresh_snapshot, logicstamp_compare_snapshot, and all analysis profiles (llm-chat, llm-safe, ci-strict)
  • Ensures full component trees are captured by default, including contracts and styles for nested components
  • Set depth: 1 explicitly if you only need direct dependencies
  • Updated all documentation, tool descriptions, and examples to reflect the new default
  • This change ensures React projects with component hierarchies get complete dependency graphs without requiring explicit depth configuration

Fixed

• logicstamp_read_bundle context_main.json Support - Fixed issue where reading context_main.json returned incomplete data
  • Now correctly detects and parses context_main.json as LogicStampIndex instead of LogicStampBundle[]
  • Returns full index content including summary, folders array, and all metadata
  • Updated output schema to support both bundle (for bundle files) and index (for context_main.json)
  • Updated documentation to clarify the difference between reading index files vs bundle files
  • Added test coverage for reading context_main.json

Upgrade Notes

• Depth Parameter: The default depth has changed from 1 to 2. If you relied on the previous default behavior (only direct dependencies), explicitly set depth: 1 in your tool calls to maintain the old behavior
• context_main.json: Reading context_main.json now returns a different structure (index field instead of bundle field), but this fixes previously broken functionality and returns complete index data

Full Changelog

See CHANGELOG.md for complete details.

v0.1.2 - Node.js requirement update and depth parameter improvements

What's Changed

Changed

• Node.js Requirement Update - Updated minimum Node.js version requirement from >=18.0.0 to >=18.18.0 to align with logicstamp-context CLI requirements
  • Node 20+ is now recommended for best performance and features
  • Updated all documentation, prerequisites, and integration guides

Added

• Enhanced Depth Parameter Documentation - Added comprehensive recommendations for using depth: 2 with React/TypeScript projects
  • RECOMMENDED: Start with depth: 2 for React/TypeScript projects to capture nested components (e.g., App → Hero → Button)
  • Clarified that default depth: 1 only includes direct dependencies
  • Added guidance across all documentation that LLMs must explicitly request depth: 2 upfront
  • Updated tool descriptions to recommend depth: 2 for React projects

Fixed

• Version Consistency - Fixed version mismatches across codebase
  • Updated version badge in README from 0.1.1 to 0.1.2
  • Updated server version reporting from 0.1.0 to 0.1.2
  • Updated example configurations to show correct version
  • All version references now consistently match package.json

Upgrade Notes

• Node.js: Ensure you're running Node.js >= 18.18.0 (Node 20+ recommended)
• Depth Parameter: For React/TypeScript projects, explicitly set depth: 2 when calling logicstamp_refresh_snapshot to capture nested component hierarchies

Full Changelog

See CHANGELOG.md for complete details.

v0.1.1 - Fix projectPath Parameter Documentation

Fixed

• Documentation Fix - Corrected projectPath parameter documentation for logicstamp_refresh_snapshot
  • Updated docs to correctly mark projectPath as required (was incorrectly marked as optional)
  • Added explanation of why projectPath is required (prevents hangs when stamp init has been run)
  • Updated all examples to include projectPath parameter
  • Fixes issue where users following documentation would encounter errors when omitting projectPath

v0.1.0 - Initial Release

Description

The first release of LogicStamp MCP Server! This MCP server enables AI assistants to safely analyze and understand React/TypeScript codebases through LogicStamp Context.

What's Included

6 MCP Tools

• logicstamp_refresh_snapshot - Create snapshots of codebase state
• logicstamp_list_bundles - List available component bundles
• logicstamp_read_bundle - Read full component contracts and dependency graphs
• logicstamp_compare_snapshot - Detect changes after edits (drift detection)
• logicstamp_compare_modes - Generate token cost comparisons across modes
• logicstamp_read_logicstamp_docs - Access LogicStamp documentation

Key Features

• Component Contract Extraction - Extract props, state, hooks, and dependencies
• Style Metadata Support - Extract Tailwind classes, SCSS modules, framer-motion animations, color palettes, layout patterns
• Dependency Graph Analysis - Understand component relationships
• Token Optimization - Configurable code inclusion modes (none/header/full)
• Smart Cache Management - Automatic detection and cleanup of corrupted cache
• Comprehensive Testing - 150+ tests covering unit, integration, and E2E scenarios

Quick Start

npm install -g logicstamp-mcp

See the README for setup instructions:
https://github.com/LogicStamp/logicstamp-mcp#quick-start

Documentation

• Quick Start Guide
• Integration Guides - Claude CLI, Claude Desktop, Cursor IDE
• MCP Integration Guide - Complete API reference

Requirements

• Node.js >=18.0.0
• LogicStamp Context CLI (npm install -g logicstamp-context)

🔒 Safety First

All tools are read-only - they analyze but never modify your codebase.

---

Full Changelog: See CHANGELOG.md for complete details.