API Reference

MCP Reference

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

Overview

The LogicStamp Context MCP server provides 7 core tools for analyzing 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_watch_status - Check if watch mode is active (optimize refresh calls)
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": 2,                  // optional: dependency depth (default: 2)
  "projectPath": "/abs/path",  // REQUIRED: absolute path to project root
  "cleanCache": false,         // optional: force cache cleanup (default: false)
  "skipIfWatchActive": false   // optional: skip regeneration if watch mode is active (default: false)
}

Note on Depth Parameter: The default depth=2 includes nested components (e.g., App → Hero → Button), ensuring you see the full component tree with contracts and styles. Depth=1 only includes direct component dependencies (e.g., App → Hero). For React projects with component hierarchies, the default depth=2 is recommended.

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",
            "interface": {
              "props": {
                "onClick": { "type": "() => void" },
                "variant": { "type": "primary | secondary" }
              },
              "emits": {},
              "state": {}
            },
            "composition": {
              "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": 2,                  // optional: dependency depth (default: 2, 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": ["composition.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)

5. logicstamp_compare_modes

Generate token cost comparison across all available context generation modes. Use this to optimize token budgets before committing to a mode.

Input Parameters:

{
  "projectPath": "/abs/path",  // optional: defaults to current working directory
  "cleanCache": false          // optional: force cache cleanup (default: false)
}

Response:

{
  "projectPath": "/path/to/project",
  "tokenEstimation": {
    "method": "GPT-4o (tiktoken) | Claude (tokenizer)"
  },
  "comparisonVsRawSource": {
    "rawSource": { "tokensGPT4o": 273006, "tokensClaude": 289573, "savingsPercent": 0 },
    "header": { "tokensGPT4o": 82917, "tokensClaude": 90131, "savingsPercent": 70 },
    "headerStyle": { "tokensGPT4o": 170466, "tokensClaude": 184864, "savingsPercent": 38 }
  },
  "modeBreakdown": {
    "none": { "tokensGPT4o": 49751, "tokensClaude": 54079, "savingsVsFull": 86 },
    "header": { "tokensGPT4o": 82917, "tokensClaude": 90131, "savingsVsFull": 77 },
    "headerStyle": { "tokensGPT4o": 170466, "tokensClaude": 184864, "savingsVsFull": 52 },
    "full": { "tokensGPT4o": 355923, "tokensClaude": 379704, "savingsVsFull": 0 }
  },
  "stats": { "totalFiles": 150, "totalTS": 100, "totalTSX": 50 }
}

Use Cases: Optimize token budgets before committing to a mode, evaluate style overhead (token impact of including style metadata), compare against raw source (calculate savings from using LogicStamp), and plan AI workflows (choose the most cost-effective mode).

6. logicstamp_read_logicstamp_docs

Read LogicStamp documentation to understand how the tool works and how to use it effectively. This is your escape hatch when confused about LogicStamp.

Input Parameters:

{} // No parameters required

Response:

{
  "type": "LogicStampDocs",
  "version": "1.0",
  "docs": {
    "forLLMs": "# LogicStamp for LLMs\n..."
  },
  "canonicalDocs": {
    "landingPage": "https://logicstamp.dev/docs/logicstamp-context/context",
    "cliRepo": "https://github.com/LogicStamp/logicstamp-context",
    "usage": { "primary": "https://logicstamp.dev/docs/...", "fallback": "https://github.com/..." },
    // ... more canonical links
  },
  "summary": {
    "purpose": "LogicStamp is a CLI tool + MCP server that scans TypeScript/Next.js codebases...",
    "howToUse": [
      "1. Call logicstamp_refresh_snapshot to generate context files and get a snapshotId",
      "2. Call logicstamp_list_bundles with the snapshotId to discover available bundles",
      "3. Call logicstamp_read_bundle with bundlePath to get component contracts",
      "4. Prefer reading bundles over raw source files",
      "5. Only read raw .ts/.tsx files when you need exact implementation details"
    ],
    "keyConcepts": [
      "Bundles are pre-parsed, structured summaries (not raw code)",
      "context_main.json is the main index",
      "Each folder gets a context.json file with bundles",
      "Use header mode (default) for most cases (~70% token savings)"
    ]
  }
}

When to Use: When confused about LogicStamp, before starting with a new project, when you need to understand bundle structure or contract format, or when you want to understand the recommended workflow. This is your go-to tool when LogicStamp concepts are unclear.

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 (contracts only, strict deps, fails on missing deps)

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. Default depth=2 includes nested components (e.g., App → Hero → Button), ensuring you see the full component tree with contracts and styles. Depth=1 only includes direct dependencies (e.g., App → Hero). 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.

skipIfWatchActive

For refresh_snapshot only. When true, skips expensive regeneration if watch mode (stamp context --watch) is active. If watch mode is active, reads existing context files (fast path). If watch mode is NOT active, performs normal regeneration (slow path). Use this to avoid redundant regeneration when watch mode is already keeping context fresh.

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)

7. logicstamp_watch_status

Check if watch mode (stamp context --watch) is currently active for a project. Use this before calling refresh_snapshot to determine whether to use skipIfWatchActive: true.

Input Parameters:

{
  "projectPath": "/abs/path",      // REQUIRED: absolute path to project root
  "includeRecentLogs": false,      // optional: include recent watch log entries (default: false)
  "logLimit": 5                    // optional: max number of log entries (default: 5)
}

Response:

{
  "projectPath": "/path/to/project",
  "watchModeActive": true,
  "status": {
    "active": true,
    "projectRoot": "/path/to/project",
    "pid": 12345,
    "startedAt": "2025-01-20T10:30:00.000Z",
    "outputDir": "/path/to/project"
  },
  "recentLogs": null,
  "message": "Watch mode is ACTIVE. Context bundles are being kept fresh automatically..."
}

Workflow: Check watch status first, then use skipIfWatchActive: true in refresh_snapshot if watch mode is active. This avoids redundant regeneration and speeds up MCP responses.

Next Steps

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

5. logicstamp_compare_modes

6. logicstamp_read_logicstamp_docs

Parameters Reference

profile

mode

includeStyle

depth

projectPath

forceRegenerate

skipIfWatchActive

baseline

7. logicstamp_watch_status

Next Steps

Product

Resources

Organization

Legal