Model Context Protocol

LogicStamp MCP Server

Beta v0.1.2

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

Native MCP integration with Claude Desktop, Claude Code, and other AI tools. Install and start using LogicStamp Context via MCP today!

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 Core Tools

logicstamp_refresh_snapshot

Analyze project and create snapshot

logicstamp_list_bundles

List available component bundles

logicstamp_read_bundle

Read full component contract + graph

logicstamp_compare_snapshot

Detect changes after edits

logicstamp_compare_modes

Generate token cost comparison across all modes

logicstamp_read_logicstamp_docs

Read LogicStamp documentation (use when confused)

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

Node.js 18.18.0 or higher
LogicStamp Context CLI - The stamp command must be installed and available in PATH

npm install -g logicstamp-context

Installation

For Claude Code Users

LogicStamp MCP server works with Claude Code - Anthropic's official CLI for Claude.

Option 1: Global Installation (Recommended)

Install globally to use LogicStamp in all your projects:

# Install the package (when published)
npm install -g logicstamp-mcp

# Add to Claude Code - available everywhere
claude mcp add --scope user --transport stdio logicstamp -- npx logicstamp-mcp

What this does: Adds LogicStamp to your global Claude Code configuration (~/.claude.json), makes the 6 LogicStamp tools available in every project, and server auto-starts when Claude Code needs it (no manual startup required).

Option 2: Per-Project Installation (For Teams)

Install per-project to share configuration with your team via git:

# Install the package
npm install -g logicstamp-mcp

# In your project directory
cd /path/to/your/project
claude mcp add --scope project --transport stdio logicstamp -- npx logicstamp-mcp

What this does: Creates .mcp.json in your project root, can be committed to git for team collaboration, and team members get the same MCP configuration.

Example .mcp.json:

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

Option 3: Local Development

For contributors or if you're developing the MCP server locally:

# Clone and build
git clone https://github.com/LogicStamp/logicstamp-mcp.git
cd logicstamp-mcp
npm install
npm run build

# Add via CLI (replace with your actual path)
claude mcp add --scope user --transport stdio logicstamp -- node /absolute/path/to/logicstamp-mcp/dist/index.js

# On Windows:
claude mcp add --scope user --transport stdio logicstamp -- node C:\Users\YourName\path\to\logicstamp-mcp\dist\index.js

For Claude Desktop Users

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

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

For Other MCP Clients

For any MCP-compatible client:

npx logicstamp-mcp

The server communicates via stdio and will automatically connect to the client.

All product names, framework names, and trademarks are the property of their respective owners. LogicStamp is an independent open-source project and is not affiliated with or endorsed by the listed AI assistants, tools, or frameworks.

Verifying Installation

After installation, verify the server is configured:

claude mcp list

You should see:

Checking MCP server health...

logicstamp: npx logicstamp-mcp - ✓ Connected

Quick Start with Claude Code

Once installed, start Claude Code in any React/TypeScript project:

cd /path/to/your/react-project
claude

Ask Claude to analyze your codebase:

You:

"Use LogicStamp to analyze the components in src/components"

Claude:

[Automatically uses logicstamp_refresh_snapshot and logicstamp_list_bundles]

The 6 LogicStamp tools will be available:

logicstamp_refresh_snapshot - Analyze project structure
logicstamp_list_bundles - List available components
logicstamp_read_bundle - Read component contracts
logicstamp_compare_snapshot - Detect changes after edits
logicstamp_compare_modes - Generate token cost comparison
logicstamp_read_logicstamp_docs - Read LogicStamp documentation

Usage Examples

Example: Analyzing with Style Metadata

To analyze components with style information (Tailwind classes, animations, color palettes):

1. USER:

"Analyze my components with style information"

2. AI → MCP:

logicstamp_refresh_snapshot({ includeStyle: true })

Response: { snapshotId: "snap_123", includeStyle: true, ... }

3. AI → MCP:

logicstamp_list_bundles(snapshotId)

Response: [{ bundlePath: "src/components/context.json", ... }]

4. AI → MCP:

logicstamp_read_bundle(snapshotId, bundlePath)

Response includes style metadata: Tailwind classes, SCSS modules, framer-motion usage, layout patterns, visual metadata (colors, spacing), and animation information.

5. AI:

Provides analysis including component structure (props, state, hooks), visual design (colors, spacing, typography), layout patterns (flex vs grid, responsive breakpoints), and animation usage.

Example Workflow: Safe Code Modification

Complete workflow for safely modifying code with verification:

1. USER:

"Add a --force flag to the clean command"

2-4. AI → MCP:

AI calls logicstamp_refresh_snapshot(), logicstamp_list_bundles(), and logicstamp_read_bundle() to understand current implementation.

5. AI:

Understands current implementation: cleanCommand signature, existing flags and options, file structure.

6. AI → IDE:

Edits src/cli/commands/clean.ts - Adds --force flag handling.

7. AI → MCP:

logicstamp_compare_snapshot()

Response shows: Modified files, added functions, semantic hash changes, token delta.

8. AI → USER:

Presents summary of changes and asks for approval: "Here's what changed: Modified: src/cli/commands/clean.ts, Added function: handleForceFlag, Semantic hash changed (expected), Token delta: +45. This matches the expected changes. Apply? (yes/no)"

Tool Reference

1. logicstamp_refresh_snapshot

Create a snapshot of the current codebase state.

Input:

{
  "profile": "llm-chat",      // optional: llm-chat | llm-safe | ci-strict
  "mode": "header",            // optional: none | header | full
  "includeStyle": false,       // optional: include style metadata
  "depth": 1,                  // optional: dependency depth (default: 1, recommended: 2 for React projects)
  "projectPath": "/abs/path",  // REQUIRED: absolute path to project root
  "cleanCache": false          // optional: force cache cleanup (default: false)
}

Note on Depth Parameter: RECOMMENDED: Start with depth: 2 for React projects. The default depth=1 only includes direct component dependencies (e.g., App → Hero). With depth=2, nested components are included (e.g., App → Hero → Button), ensuring you see the full component tree with contracts and styles. For React projects with component hierarchies, explicitly set depth: 2 in your first refresh_snapshot call.

Output:

{
  "snapshotId": "snap_1764033034172",
  "projectPath": "/path/to/project",
  "profile": "llm-chat",
  "mode": "header",
  "includeStyle": false,
  "summary": {
    "totalComponents": 32,
    "totalBundles": 30,
    "totalFolders": 14,
    "totalTokenEstimate": 19127,
    "tokenEstimates": {
      "gpt4oMini": 13895,
      "gpt4oMiniFullCode": 39141,
      "claude": 12351,
      "claudeFullCode": 34792
    },
    "missingDependencies": []
  },
  "folders": [...]
}

2. logicstamp_list_bundles

List available bundles for selective loading.

Input:

{
  "snapshotId": "snap_1764033034172",
  "folderPrefix": "src/components"  // optional
}

Output:

{
  "snapshotId": "snap_1764033034172",
  "totalBundles": 5,
  "bundles": [
    {
      "id": "bundle_Button",
      "rootComponent": "Button",
      "filePath": "src/components/Button.tsx",
      "folder": "src/components",
      "bundlePath": "src/components/context.json",
      "position": "1/5",
      "bundleHash": "uifb:6e122a4e538c640f09501037",
      "approxTokens": 549
    }
  ]
}

3. logicstamp_read_bundle

Read full component contract and dependency graph.

Input:

{
  "snapshotId": "snap_1764033034172",
  "bundlePath": "src/components/context.json",
  "rootComponent": "Button"  // optional
}

Note: If includeStyle: true was used in refresh_snapshot, the bundle contracts will include a style field with Tailwind classes, SCSS modules, framer-motion usage, layout patterns, visual metadata, and animation information.

Output:

{
  "snapshotId": "snap_1764033034172",
  "bundlePath": "src/components/context.json",
  "rootComponent": "Button",
  "bundle": {
    "type": "LogicStampBundle",
    "entryId": "...",
    "graph": {
      "nodes": [
        {
          "entryId": "...",
          "contract": {
            "type": "UIFContract",
            "kind": "react:component",
            "description": "Interactive button component",
            "logicSignature": {
              "props": {
                "onClick": { "type": "() => void" },
                "variant": { "type": "primary | secondary" }
              },
              "emits": {},
              "state": {}
            },
            "version": {
              "hooks": ["useState"],
              "components": [],
              "functions": ["handleClick"]
            }
          }
        }
      ],
      "edges": []
    }
  }
}

4. logicstamp_compare_snapshot

Detect changes after edits.

Input:

{
  "profile": "llm-chat",      // optional: analysis profile (default: llm-chat)
  "mode": "header",            // optional: code inclusion mode (default: header)
  "includeStyle": false,       // optional: include style metadata (only when forceRegenerate: true)
  "depth": 1,                  // optional: dependency depth (only when forceRegenerate: true)
  "forceRegenerate": false,    // optional: regenerate context before comparing (default: false)
  "projectPath": "/abs/path",  // optional: defaults to current working directory
  "baseline": "disk"           // optional: disk | snapshot | git:<ref> (default: disk)
}

Performance Notes: By default (forceRegenerate: false), this tool reads existing JSON files from disk (fast, no CLI calls). When forceRegenerate: true, it runs stamp context to regenerate context before comparing. If context_main.json is missing and forceRegenerate: false, the tool will fail with a clear error message.

Output:

{
  "baseline": "disk",
  "status": "diff",
  "summary": {
    "totalFolders": 14,
    "unchangedFolders": 12,
    "changedFolders": 2,
    "addedFolders": 0,
    "removedFolders": 0,
    "tokenDelta": {
      "gpt4oMini": 320,
      "claude": 270
    }
  },
  "folderDiffs": [
    {
      "path": "src/components",
      "status": "changed",
      "changes": [
        {
          "rootComponent": "Button",
          "type": "uif_contract_changed",
          "semanticHashBefore": "uif:637c3858",
          "semanticHashAfter": "uif:7f8d9e0a",
          "tokenDelta": 40,
          "details": {
            "modifiedFields": ["version.functions"],
            "addedFunctions": ["handleKeyDown"]
          }
        }
      ]
    }
  ]
}

Change Types:

The changes array can contain objects with different type values:

uif_contract_changed - Component contract changed (props, functions, imports, etc.)
hash_changed - Bundle hash changed but semantic hash unchanged
bundle_added - New component bundle added
bundle_removed - Component bundle removed
props_signature_changed - Props signature changed (reserved for future use)

Status Values:

pass - No changes detected
diff - Changes detected
error - Comparison failed (check error field for details)

Troubleshooting

MCP Server Not Found

Problem:

Claude Code says "LogicStamp tools not available"

Solution:

# Check if server is configured
claude mcp list

# If not listed, add it
claude mcp add --scope user --transport stdio logicstamp -- npx logicstamp-mcp

# Restart Claude Code or start a new conversation

Server Connection Failed

Problem:

claude mcp list shows logicstamp: ✗ Failed to connect

Solutions:

Check if the package is installed: npm list -g logicstamp-mcp
For local development, verify the path is correct
Check build output: npm run build
Try manual test: node dist/index.js

"Snapshot not found" Error

Problem:

Tools return "Snapshot ID not found"

Solution:

Always call logicstamp_refresh_snapshot first before using other tools.

"stamp: command not found"

Problem:

MCP server can't find the stamp CLI

Solution:

Install LogicStamp Context CLI globally:

npm install -g logicstamp-context
# Verify installation
stamp --version

Development

Build

npm install
npm run build

Run Locally

npm start

Watch Mode

npm run dev

Project Structure

logicstamp-mcp/
├── src/
│   ├── index.ts              # Entry point
│   ├── types/
│   │   └── schemas.ts        # TypeScript schemas
│   └── mcp/
│       ├── server.ts         # MCP server implementation
│       ├── state.ts          # Snapshot state management
│       └── tools/
│           ├── refresh-snapshot.ts
│           ├── list-bundles.ts
│           ├── read-bundle.ts
│           └── compare-snapshot.ts
├── dist/                     # Compiled output
├── package.json
├── tsconfig.json
└── README.md

Requirements for LogicStamp CLI

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

Note: The MCP does not require --json or --json-summary flags. It reads the JSON files that stamp context generates directly from disk.

LogicStamp MCP Server

Overview

Features

6 Core Tools

Key Benefits

Prerequisites

Installation

For Claude Code Users

Option 1: Global Installation (Recommended)

Option 2: Per-Project Installation (For Teams)

Option 3: Local Development

For Claude Desktop Users

For Other MCP Clients

Verifying Installation

Quick Start with Claude Code

Usage Examples

Example: Analyzing with Style Metadata

Example Workflow: Safe Code Modification

Tool Reference

1. logicstamp_refresh_snapshot

2. logicstamp_list_bundles

3. logicstamp_read_bundle

4. logicstamp_compare_snapshot

Troubleshooting

MCP Server Not Found

Server Connection Failed

"Snapshot not found" Error

"stamp: command not found"

Development

Build

Run Locally

Watch Mode

Project Structure

Requirements for LogicStamp CLI

Architecture

Design Principles

Security

Links