logicstamp-mcp
OfficialClick on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@logicstamp-mcp show me the dependency graph for the Button component"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Model Context Protocol (MCP) server for LogicStamp Context, the Context Compiler for TypeScript - exposing deterministic architectural contracts to AI agents via secure, structured context delivery.
Example workflow: stamp context --strict-watch generates context bundles that MCP-powered assistants use to explain component architecture (ThemeContext shown here).
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
Related MCP server: reposynapse
⚡ Features
7 Tools
logicstamp_refresh_snapshot- Analyze project and create snapshotlogicstamp_list_bundles- List available component bundleslogicstamp_read_bundle- Read full component contract + graphlogicstamp_compare_snapshot- Detect changes after editslogicstamp_compare_modes- Generate token cost comparison across all modeslogicstamp_read_logicstamp_docs- Read LogicStamp documentationlogicstamp_watch_status- Check if watch mode is active (for incremental rebuilds)
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
Watch Mode Aware - Detects when
stamp context --watchis running and skips regeneration (context is already fresh)
Prerequisites
Node.js >= 20
LogicStamp Context CLI - The
stampcommand must be installed and available in PATHnpm 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.
Install prerequisites (if not already installed):
npm install -g logicstamp-context # Required: LogicStamp CLI npm install -g logicstamp-mcp # MCP serverConfigure 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": ["-y", "logicstamp-mcp"] } } }Note:
-ytellsnpxnot to prompt (MCP clients often run the server without a terminal, so prompts can hang). Some clients may require"type": "stdio"— if the above does not 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
Restart your MCP client (Cursor/Claude Desktop) or verify with
claude mcp list(Claude CLI)Start using LogicStamp:
cd /path/to/your/react-project claude # or open CursorAsk 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 7 tools. For complete API documentation with input/output examples, see the MCP Integration Guide.
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),skipIfWatchActive(optional)Returns:
snapshotId,summary,folders,watchMode(if active)Always call this first when analyzing a new repo
Note:
projectPathis REQUIRED - must be an absolute path to the project root. Omitting this parameter can cause the server to hang.Watch Mode Optimization: Set
skipIfWatchActive: trueto skip regeneration when watch mode is running. When watch mode (stamp context --watch) is active, context is already being kept fresh - no need to regenerateDepth Parameter: By default, dependency graphs include nested components (depth=2). To include only direct dependencies, explicitly set
depth: 1. The default depth=2 ensures nested components are included in dependency graphs.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:
bundlesarray with metadataCall 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 whenforceRegenerateistrue(default:false)depth(optional): Dependency traversal depth. Only used whenforceRegenerateistrue. IMPORTANT: By default, dependency graphs include nested components (depth=2). To include only direct dependencies, setdepth: 1. The default depth=2 ensures nested components are included in dependency graphs.forceRegenerate(optional): Force regeneration of context before comparing. Whenfalse, reads existingcontext_main.jsonfrom disk (fast). Whentrue, runsstamp contextto regenerate (default:false)projectPath(optional): Project path (defaults to current directory)baseline(optional): Comparison baseline:disk(default),snapshot, or custom pathcleanCache(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. SetforceRegenerate: trueto ensure fresh context or whencontext_main.jsonis 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
logicstamp_watch_status - Check if watch mode is active
Parameters:
projectPath(required),includeRecentLogs(optional),logLimit(optional)Returns:
watchModeActive,status(if active),recentLogs(if requested),messageUse this to check if
stamp context --watchis running before calling refresh_snapshotWhen watch mode is active: Context is being kept fresh automatically via incremental rebuilds - you can skip regeneration and just read existing bundles
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:
Calls
logicstamp_refresh_snapshotfirstUses bundles instead of raw source files when possible
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/cli/context - Complete documentation (landing page, best UX)
Fallback: CLI Repository Docs - GitHub docs (always available, versioned)
Key Topics (both primary and fallback links):
Topic | Primary (Landing Page) | Fallback (GitHub) |
Usage Guide | ||
UIF Contracts | ||
Schema Reference | ||
CLI Commands | ||
Compare Modes | ||
Limitations |
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_docstool 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-mcpTest 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_snapshotfirst before using other tools
For detailed troubleshooting, see:
Platform-specific troubleshooting in integration guides
MCP Integration Guide for architecture details
Development
Build
npm install
npm run buildRun 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.jsAfter global installation:
npx logicstamp-mcpNote: 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 devFor development details, see MCP Integration Guide.
Architecture
The MCP server follows these design principles:
Thin Wrapper - Shells out to existing
stampCLIStateful Snapshots - Tracks context before/after edits
Read-Only - Server never writes to project files
Token-Efficient - Selective bundle loading
For detailed architecture documentation, see MCP Integration Guide.
Requirements
The LogicStamp MCP server requires:
Node.js >= 20
TypeScript codebase (React, Next.js, Vue (TS/TSX), Express, or NestJS)
stamp contextcommand - Must be installed and available in PATH:The CLI generates
context_main.jsonfilesThe MCP server reads these JSON files directly (no special flags required)
Need Help?
Roadmap - logicstamp.dev/roadmap
License
The LogicStamp Fox mascot and related brand assets are © 2025 Amit Levi. These assets may not be used for third-party branding without permission.
Issues and PRs welcome! See CONTRIBUTING.md for guidelines.
This project follows a Code of Conduct.
Available Tools
7 toolslogicstamp_compare_modesA
Generates token cost comparison across all modes (none/header/header+style/full) to help choose optimal mode. Executes stamp context --compare-modes --stats and returns token counts (GPT-4o-mini/Claude), savings vs raw source (~70% for header) and vs full context, file stats. Modes: none (~79% savings), header (~65%, recommended), header+style (~52%), full (no savings). Use before generating context, when user asks about token budgets, or to evaluate style metadata impact. Performance: Takes 2-3x longer (regenerates with/without style for accuracy).
Inputs: projectPath, cleanCache.
logicstamp_compare_snapshotA
Compares current snapshot with baseline to detect changes. Reads context_main.json and folder context.json files. Detects: ADDED/REMOVED/CHANGED/UNCHANGED folders/components (props, hooks, imports, semantic hash changes). Returns structured diff with token deltas. Use after editing files to verify changes (like Jest snapshots - detects contract drift, not just file changes). Default (forceRegenerate=false): Reads from disk (fast, assumes fresh). Set forceRegenerate=true to regenerate before comparing. Style: Set includeStyle=true (with forceRegenerate=true) to include style metadata. Depth: Set depth when forceRegenerate=true (default=2 nested, 1=direct only). Baseline: "disk" (current snapshot, default), "snapshot" (stored), or "git:" (future). Error: If context_main.json missing and forceRegenerate=false, fails - run refresh_snapshot first or use forceRegenerate=true.
Inputs: profile, mode, includeStyle, depth, +4 more.
logicstamp_list_bundlesA
⚠️ CRITICAL: Do NOT use sleep() delays before calling this tool. When watch mode is active, bundles are already fresh - call this tool directly without any waiting. Lists all ROOT bundles from context_main.json. Returns bundle catalog (component names, file paths, bundle paths, token estimates). IMPORTANT: LogicStamp organizes components into ROOT components (have their own bundles, listed here) and DEPENDENCIES (included in importing root's bundle.graph.nodes[], not listed here). If a component isn't in this list, it's a dependency - find which root imports it, then read that root's bundle to see the dependency contract in bundle.graph.nodes[]. Use bundle paths in read_bundle to get component contracts. Watch mode: Use projectPath directly (no snapshotId needed). Filter: folderPrefix="src/components" to filter by directory. Next: read_bundle(snapshotId|projectPath, bundlePath). The tool handles race conditions internally - no external sleep() delays needed.
Inputs: snapshotId, projectPath, folderPrefix.
logicstamp_read_bundleA
⚠️ CRITICAL: Do NOT use sleep() delays before calling this tool. When watch mode is active, bundles are already fresh - call this tool directly without any waiting. Reads bundle/index file to get component contracts and dependency graphs. Reads context_main.json (project overview) or folder context.json (component contracts). These are pre-parsed summaries optimized for AI - PREFER over raw .ts/.tsx files. ROOT vs DEPENDENCY: Root components have their own bundles (use rootComponent param). Dependencies appear in bundle.graph.nodes[] of the root that imports them. If a component isn't found as root, it's a dependency - read bundles that might import it and check bundle.graph.nodes[] for the dependency contract. Bundle contains: entryId, graph.nodes[] (UIFContract for root + dependencies), graph.edges[] (dependencies), meta.missing[] (unresolved). UIFContract: kind, description, props, emits, state, exports, semanticHash, optional style metadata. Watch mode: Use projectPath directly (no snapshotId needed). Use bundlePath="context_main.json" for overview, or folder paths from list_bundles for details. The tool handles race conditions internally with retry logic (200-500ms delays + exponential backoff built-in). No external sleep() delays needed.
Inputs: bundlePath (required), snapshotId, projectPath, rootComponent.
logicstamp_read_logicstamp_docsA
Returns comprehensive LogicStamp documentation (logicstamp-for-llms.md guide, usage, UIF contracts, schema, CLI commands, limitations). Returns complete doc bundle with key concepts, workflow instructions, and best practices. Use when: unsure how LogicStamp works, starting new project, need bundle structure/contract format, or want recommended workflow. Escape hatch: if confused about LogicStamp, call this first. Explains: what LogicStamp is, why bundles over raw code, workflow (refresh → list → read), bundle structure, best practices.
Inputs: no named parameters.
logicstamp_refresh_snapshotA
⚠️ CRITICAL: Do NOT use sleep() delays. After calling this tool, bundles are immediately available. When watch mode is active, skip this tool entirely and read bundles directly - they're already fresh. ⚠️ FIRST: Call logicstamp_watch_status! If watch mode is ACTIVE → SKIP this tool, go to list_bundles → read_bundle (context is fresh). Use when: watch mode INACTIVE, first-time analysis, or after large changes. Default skipIfWatchActive=true (auto-skips regeneration if watch mode active). WHAT IT DOES: Runs stamp context to analyze React/TypeScript/Node.js codebases (Next.js, Express.js, NestJS) and generate structured context files (context_main.json + per-folder context.json bundles). These are STRUCTURED DATA, not raw source. SLOW compared to reading existing context. WHAT YOU GET: Summary statistics (component counts, token estimates, folder structure) and a snapshotId. If watch mode is active, also includes watchMode status. IMPORTANT: This summary does NOT include component details, props, dependencies, or style metadata. WHAT TO DO NEXT: list_bundles(snapshotId|projectPath) → read_bundle(snapshotId|projectPath, bundlePath). Use projectPath when watch mode is active (no snapshotId needed). STYLE METADATA: Set includeStyle=true to extract visual/design info (Tailwind/SCSS/animations/colors/spacing). Appears in bundle "style" field, NOT in summary. Use for design system analysis or when user asks about styling/colors/animations. DEPTH PARAMETER: Default depth=2 includes nested components (App → Hero → Button) with contracts and styles. Set depth=1 for direct dependencies only (App → Hero). PREFER BUNDLES OVER RAW CODE: These bundles are pre-parsed summaries optimized for AI - use them instead of reading raw .ts/.tsx files when possible. If you're unsure how LogicStamp works, call logicstamp_read_logicstamp_docs first.
Inputs: projectPath (required), profile, mode, includeStyle, +3 more.
logicstamp_watch_statusA
⚠️ CRITICAL: Do NOT use sleep() delays before calling LogicStamp tools when watch mode is active. Watch mode keeps bundles fresh automatically - just read them directly. ⚠️ CALL THIS FIRST before any other LogicStamp tool! Checks if watch mode (stamp context --watch) is active. If ACTIVE: SKIP refresh_snapshot, go to list_bundles → read_bundle (context fresh via incremental rebuilds). If INACTIVE: Call refresh_snapshot first. Enables zero-cost instant context access when watch mode running. Reads .logicstamp/context_watch-status.json and verifies process is running. Watch features: Incremental rebuilds (affected bundles only), change detection (props/hooks/state/components), debouncing (500ms), optional log file. Strict watch mode (stamp context --watch --strict-watch): Also detects breaking changes. Returns strictWatch=true when enabled. Detection: Reads strictWatch field from .logicstamp/context_watch-status.json file (when LogicStamp CLI includes it). Set includeRecentLogs=true to see recent regeneration events. When watch mode is active, bundles are already fresh - read them directly without any sleep() delays. The tools handle race conditions internally.
Inputs: projectPath (required), includeRecentLogs, logLimit.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool has a clearly distinct purpose: watch status check, refresh, list bundles, read bundles, compare modes, compare snapshots, and docs retrieval. No overlap or ambiguity.
All tools follow a consistent 'logicstamp_verb_noun' pattern (e.g., compare_modes, list_bundles, read_bundle). Naming is predictable and uniform.
7 tools cover the full workflow for code analysis (watch → refresh → list → read → compare) without excess. Well-scoped for the domain.
The tool surface provides complete coverage of the intended workflow: status checking, snapshot generation, bundle listing/reading, comparisons, and documentation. No obvious gaps.
Maintenance
Related MCP Connectors
The Cortex MCP server provides read-only access to real-time engineering context from the Cortex developer portal, allowing AI coding assistants to answer natural language questions about your organization's catalog (microservices, libraries, domains, teams, infrastructure), scorecards (engineering standards and best practices), initiatives (goals and deadlines), and Engineering Intelligence metrics. It includes tools for querying documentation, tracking personal entities, and accessing AI-assisted insights across the entire Cortex ecosystem.
An MCP server that gives your AI access to the source code and docs of all public github repos
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceAn MCP server that transforms codebases into intelligent, queryable knowledge bases, enabling AI assistants to perform semantic search, explore architecture, and analyze code relationships.166-
- AlicenseAqualityDmaintenanceUniversal MCP server that analyzes any codebase and provides structured context to AI assistants. Dynamic, accurate, and token-efficient.1835 npmMIT
- AlicenseNot gradedqualityBmaintenanceMCP server for local-first code intelligence, providing structural code graph, semantic search, and impact analysis to AI agents.2MIT

Vibgrate AI Contextofficial
AlicenseNot gradedqualityBmaintenanceLocal-first MCP server that gives AI assistants codebase intelligence—code graph, drift analysis, vulnerability attribution, and version-correct library docs—all from the user's machine.1,093 npm6Apache 2.0