Skip to main content
Glama
logicstamp-mcp

logicstamp-mcp

Official
by LogicStamp

Version Beta License Node CI

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.


LogicStamp MCP Workflow 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

  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

  7. logicstamp_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 --watch is running and skips regeneration (context is already fresh)

Prerequisites

  1. Node.js >= 20

  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": ["-y", "logicstamp-mcp"]
        }
      }
    }

    Note: -y tells npx not 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:

  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 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: projectPath is REQUIRED - must be an absolute path to the project root. Omitting this parameter can cause the server to hang.

  • Watch Mode Optimization: Set skipIfWatchActive: true to skip regeneration when watch mode is running. When watch mode (stamp context --watch) is active, context is already being kept fresh - no need to regenerate

  • Depth 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: 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 include nested components (depth=2). To include only direct dependencies, set depth: 1. The default depth=2 ensures nested components are included in dependency graphs.

    • 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

logicstamp_watch_status - Check if watch mode is active

  • Parameters: projectPath (required), includeRecentLogs (optional), logLimit (optional)

  • Returns: watchModeActive, status (if active), recentLogs (if requested), message

  • Use this to check if stamp context --watch is running before calling refresh_snapshot

  • When 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:

  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)

Canonical LogicStamp Docs (Redundant Sources)

Full CLI & Context Documentation:

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:

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.

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

The LogicStamp MCP server requires:

  • Node.js >= 20

  • TypeScript codebase (React, Next.js, Vue (TS/TSX), Express, or NestJS)

  • stamp context command - Must be installed and available in PATH:

    • The CLI generates context_main.json files

    • The MCP server reads these JSON files directly (no special flags required)

Need Help?

License

MIT


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.

Links: Website · GitHub · CLI · Changelog

Available Tools

7 tools
logicstamp_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

    A4.7/5.0

    Scored across 7 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    All tools follow a consistent 'logicstamp_verb_noun' pattern (e.g., compare_modes, list_bundles, read_bundle). Naming is predictable and uniform.

    Tool Count5/5

    7 tools cover the full workflow for code analysis (watch → refresh → list → read → compare) without excess. Well-scoped for the domain.

    Completeness5/5

    The tool surface provides complete coverage of the intended workflow: status checking, snapshot generation, bundle listing/reading, comparisons, and documentation. No obvious gaps.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that transforms codebases into intelligent, queryable knowledge bases, enabling AI assistants to perform semantic search, explore architecture, and analyze code relationships.
      166
      -
    • A
      license
      A
      quality
      D
      maintenance
      Universal MCP server that analyzes any codebase and provides structured context to AI assistants. Dynamic, accurate, and token-efficient.
      18
      35 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server for local-first code intelligence, providing structural code graph, semantic search, and impact analysis to AI agents.
      2
      MIT