LogicStamp MCP Server

Model Context Protocol (MCP) server for LogicStamp Context - enabling AI assistants to safely analyze and understand React/TypeScript codebases.

Overview

This MCP server provides AI assistants with structured access to your codebase through LogicStamp Context's analysis engine. It acts as a thin wrapper around the stamp CLI, offering:

• Snapshot-based analysis - Capture codebase state before making edits
• Component contracts - Extract props, state, hooks, and dependencies
• Style metadata - Extract Tailwind classes, SCSS modules, framer-motion animations, color palettes, layout patterns
• Dependency graphs - Understand component relationships
• Drift detection - Verify changes after modifications
• Token optimization - Control context size with configurable code inclusion modes

Features

6 Tools

1. logicstamp_refresh_snapshot - Analyze project and create snapshot
2. logicstamp_list_bundles - List available component bundles
3. logicstamp_read_bundle - Read full component contract + graph
4. logicstamp_compare_snapshot - Detect changes after edits
5. logicstamp_compare_modes - Generate token cost comparison across all modes
6. logicstamp_read_logicstamp_docs - Read LogicStamp documentation

Key Benefits

• Context-Aware Edits - AI reads actual component contracts before modifying
• Self-Verification - AI verifies its own changes via drift detection
• Token-Efficient - Only load bundles relevant to the task
• Safe by Default - Changes must pass drift check before approval

Prerequisites

1. Node.js >= 18.18.0 (Node 20+ recommended for best performance and features)
2. LogicStamp Context CLI - The stamp command must be installed and available in PATH

   npm install -g logicstamp-context
   

Quick Start

Setup is done once - After configuring the MCP server, it will be available in all your projects. The MCP client automatically starts the server when needed - you don't need to start it manually.

1. Install prerequisites (if not already installed):

   npm install -g logicstamp-context  # Required: LogicStamp CLI
   npm install -g logicstamp-mcp       # MCP server
   

2. Configure your MCP client (one-time setup) - Create a config file for your platform:

   For Cursor: Create ~/.cursor/mcp.json (macOS/Linux) or %USERPROFILE%\.cursor\mcp.json (Windows)

   For Claude CLI: Create ~/.claude.json (macOS/Linux) or %USERPROFILE%\.claude.json (Windows)

   For Claude Desktop: Create ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)

   Add this configuration:

   {
     "mcpServers": {
       "logicstamp": {
         "command": "npx",
         "args": ["logicstamp-mcp"]
       }
     }
   }
   

   Note: Some clients may require "type": "stdio" - if the above doesn't work, add it to the config. See integration guides for platform-specific details:

   • Claude CLI Integration - For Claude Code users
   • Claude Desktop Integration - For Claude Desktop users
   • Cursor Integration - For Cursor IDE users

3. Restart your MCP client (Cursor/Claude Desktop) or verify with claude mcp list (Claude CLI)

4. Start using LogicStamp:

   cd /path/to/your/react-project
   claude  # or open Cursor
   

   Ask your AI assistant: "Can you analyze my React project using LogicStamp?"

For detailed setup instructions, see the Quick Start Guide.

Usage Example

You: "Analyze the Button component in my project"

AI:
1. Uses logicstamp_refresh_snapshot to create snapshot
2. Uses logicstamp_list_bundles to find Button component
3. Uses logicstamp_read_bundle to read Button's contract
4. Provides detailed analysis of Button's props, state, hooks, etc.

For more examples and workflows, see Usage Examples in the MCP Integration Guide.

Tool Reference

The MCP server provides 6 tools. For complete API documentation with input/output examples, see the MCP Integration Guide.

Quick Reference

logicstamp_refresh_snapshot - Create a snapshot of the current codebase state (STEP 1)

• Parameters: profile (optional), mode (optional), includeStyle (optional), depth (optional), projectPath (required), cleanCache (optional)
• Returns: snapshotId, summary, folders
• Always call this first when analyzing a new repo
• Note: projectPath is REQUIRED - must be an absolute path to the project root. Omitting this parameter can cause the server to hang.
• Depth Parameter: By default, dependency graphs only include direct dependencies (depth=1). To include nested components, explicitly set depth: 2 or higher. The LLM does NOT automatically detect when depth=2 is needed.
• Cache is automatically cleaned if corruption is detected

logicstamp_list_bundles - List available bundles for selective loading (STEP 2)

• Parameters: snapshotId (required), folderPrefix (optional)
• Returns: bundles array with metadata
• Call this after refresh_snapshot to discover available bundles

logicstamp_read_bundle - Read full component contract and dependency graph (STEP 3)

• Parameters: snapshotId (required), bundlePath (required), rootComponent (optional)
• Returns: Complete bundle with contracts and dependency graph
• This is where the valuable data is - prefer bundles over raw source files

logicstamp_compare_snapshot - Detect changes after edits

• Parameters:
  • profile (optional): Analysis profile (default: llm-chat)
  • mode (optional): Code inclusion mode (default: header)
  • includeStyle (optional): Include style metadata in comparison. Only takes effect when forceRegenerate is true (default: false)
  • depth (optional): Dependency traversal depth. Only used when forceRegenerate is true. IMPORTANT: By default, dependency graphs only include direct dependencies (depth=1). To include nested components, you MUST explicitly set depth: 2 or higher. The LLM does NOT automatically detect when depth=2 is needed - it must be explicitly requested.
  • forceRegenerate (optional): Force regeneration of context before comparing. When false, reads existing context_main.json from disk (fast). When true, runs stamp context to regenerate (default: false)
  • projectPath (optional): Project path (defaults to current directory)
  • baseline (optional): Comparison baseline: disk (default), snapshot, or custom path
  • cleanCache (optional): Force cache cleanup (default: false, auto-detects corruption)
• Returns: Comparison result with change details
• Note: By default (forceRegenerate: false), reads from disk for fast comparison. Set forceRegenerate: true to ensure fresh context or when context_main.json is missing.

logicstamp_compare_modes - Generate token cost comparison across all modes

• Parameters: projectPath (optional), cleanCache (optional)
• Returns: Token counts for all modes (none/header/header+style/full), savings percentages, file statistics
• Use this to understand token costs before generating context or when user asks about token budgets/optimization

logicstamp_read_logicstamp_docs - Read LogicStamp documentation

• Parameters: None
• Returns: Complete LogicStamp documentation bundle
• Use this when confused - explains LogicStamp, workflow, and best practices

Startup Ritual

When starting work with a new project, use the Startup Ritual to guide the AI through the recommended workflow. This ensures the AI:

1. Calls logicstamp_refresh_snapshot first
2. Uses bundles instead of raw source files when possible
3. Follows the recommended LogicStamp workflow

Documentation

MCP-Specific Docs (This Repo)

• Quick Start Guide - Get up and running in minutes
• Startup Ritual - Recommended message to paste when starting with a new project
• MCP Integration Guide - Complete API reference and architecture
• Integration Guides - Platform-specific setup (Claude CLI, Claude Desktop, Cursor)

Canonical LogicStamp Docs (Redundant Sources)

Full CLI & Context Documentation:

• Primary: logicstamp.dev/docs/logicstamp-context/context - Complete documentation (landing page, best UX)
• Fallback: CLI Repository Docs - GitHub docs (always available, versioned)

Key Topics (both primary and fallback links):

Note:

• Docs are maintained in the CLI repo and synced to the landing page
• If the landing page is unavailable, use the GitHub links as fallback
• The logicstamp_read_logicstamp_docs tool returns an embedded LLM-focused doc snapshot (docs/logicstamp-for-llms.md) for offline use

Troubleshooting

Common Issues

"stamp: command not found"

• Install LogicStamp Context CLI: npm install -g logicstamp-context

Server doesn't show up

• Verify installation: npm list -g logicstamp-mcp
• Test server manually: npx logicstamp-mcp (should wait for stdin, press Ctrl+C to exit)
• Check configuration in your MCP client (see integration guides)
• Restart your MCP client completely

"Snapshot not found"

• Always call logicstamp_refresh_snapshot first before using other tools

For detailed troubleshooting, see:

• Troubleshooting in Quick Start Guide
• Platform-specific troubleshooting in integration guides
• MCP Integration Guide for architecture details

Development

Build

npm install
npm run build

Run the Server

Important: You don't need to start the MCP server manually. Once configured, your MCP client (Cursor, Claude Desktop, etc.) automatically starts the server when needed. The commands below are only for testing/debugging.

For testing/debugging only:

After building from source:

npm start
# or directly
node dist/index.js

After global installation:

npx logicstamp-mcp

Note: The server runs via stdio (standard input/output) and waits for MCP protocol messages. When configured with an MCP client (Claude CLI, Cursor, etc.), the client automatically starts the server - you don't need to run it manually. The commands above are useful for:

• Testing the server during development
• Debugging connection issues
• Verifying the server starts correctly

When running manually, the server will wait for stdin input. Press Ctrl+C to exit.

Watch Mode

npm run dev

For development details, see MCP Integration Guide and Contributing Guide.

Architecture

The MCP server follows these design principles:

1. Thin Wrapper - Shells out to existing stamp CLI
2. Stateful Snapshots - Tracks context before/after edits
3. Read-Only - Server never writes to project files
4. Token-Efficient - Selective bundle loading

For detailed architecture documentation, see MCP Integration Guide.

Requirements

This MCP server requires:

• stamp context command - Must be installed and available in PATH
• The CLI generates context_main.json files (already JSON format)
• The MCP reads these JSON files directly - no special JSON output flags needed

License

MIT

Branding & Attribution

The LogicStamp Fox mascot and related brand assets are © 2025 Amit Levi.

These assets may not be used for third-party branding, logos, or commercial identity without permission. They are included in this repository for documentation and non-commercial use within the LogicStamp ecosystem only.

Contributing

Contributions welcome! Please see CONTRIBUTING.md for guidelines.

Changelog

See CHANGELOG.md for a detailed list of changes and version history.

Links

• LogicStamp Context
• Model Context Protocol