API Reference

MCP Reference

Complete API documentation for all LogicStamp Context MCP server tools, parameters, and responses.

Overview

The LogicStamp Context MCP server provides 6 core tools for analyzing React/TypeScript codebases:

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)

1. logicstamp_refresh_snapshot

Create a snapshot of the current codebase state. This is typically the first tool you call before using other tools.

Input Parameters:

{
  "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.

Response:

{
  "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": [...]
}

Note: Save the snapshotId - you'll need it for subsequent tool calls. Snapshots are stored in memory and expire after a TTL period.

2. logicstamp_list_bundles

List available bundles for selective loading. Use this to discover which components are available before reading specific bundles.

Input Parameters:

{
  "snapshotId": "snap_1764033034172",
  "folderPrefix": "src/components"  // optional: filter by folder path
}

Response:

{
  "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
    }
  ]
}

Tip: Use folderPrefix to filter bundles by directory path. Use bundlePath from the response in logicstamp_read_bundle.

3. logicstamp_read_bundle

Read full component contract and dependency graph. This returns the complete UIF contract with props, state, hooks, dependencies, and optionally style metadata.

Input Parameters:

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

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.

Response:

{
  "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. Use this to verify modifications and detect drift. Compares current codebase state against a baseline (disk, snapshot, or git ref).

Input Parameters:

{
  "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.

Response:

{
  "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)

Parameters Reference

profile

Preset configuration optimized for different use cases:

llm-chat (default) - Balanced mode for AI chat interfaces
llm-safe - Conservative mode for token-limited contexts
ci-strict - Strict validation mode for CI/CD

mode

Code inclusion mode:

none - Contracts only, no source code (maximum compression)
header (default) - Contracts plus JSDoc headers and function signatures
full - Complete source code included

includeStyle

When true, extracts style metadata including:

Tailwind CSS classes
SCSS/CSS modules
framer-motion animations
Color palettes and spacing patterns
Layout patterns (flex/grid, responsive breakpoints)

Note: For compare_snapshot, this only takes effect when forceRegenerate: true. If forceRegenerate: false, compares whatever style metadata exists on disk (may be incomplete).

depth

Dependency traversal depth. RECOMMENDED: Start with depth: 2 for React projects. Default depth=1 only includes direct 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. Only used when forceRegenerate: true in compare_snapshot.

projectPath

REQUIRED for refresh_snapshot - Absolute path to project root. When stamp init has been run, MCP clients may omit this parameter, causing hangs. This parameter is REQUIRED for the tool to work correctly. The server will resolve relative paths to absolute paths automatically. For compare_snapshot, defaults to current working directory.

forceRegenerate

For compare_snapshot only. When true, runs stamp context to regenerate context before comparing. When false (default), reads existing context_main.json from disk (fast path, assumes context is fresh). If context_main.json is missing and forceRegenerate: false, fails with a clear error message.

baseline

Comparison baseline for logicstamp_compare_snapshot:

disk (default) - Compare against context files on disk
snapshot - Compare against a previous snapshot ID
git:<ref> - Compare against a git commit (e.g., git:main)

Ready to Use the MCP Tools?

Check out the installation guide to get started, or explore the overview page for usage examples and workflows.

Installation Guide MCP Overview

MCP Reference

Overview

1. logicstamp_refresh_snapshot

2. logicstamp_list_bundles

3. logicstamp_read_bundle

4. logicstamp_compare_snapshot

Parameters Reference

profile

mode

includeStyle

depth

projectPath

forceRegenerate

baseline

Ready to Use the MCP Tools?

Product

Contact

Legal