Logicstamp Context

The Context Compiler for TypeScript.

Supports: React · Next.js · Vue (TS/TSX) · Express · NestJS

LogicStamp Context is a CLI that compiles TypeScript codebases into deterministic, diffable architectural contracts and dependency graphs - a compact, structured source of truth for AI coding workflows.

Includes watch mode, strict, auditable diffs, and real-time breaking change detection. Use with logicstamp-mcp to feed structured context into Claude, Cursor, and other MCP-compatible assistants.

[](https://www.npmjs.com/package/logicstamp-context)

[](LICENSE)

[](https://github.com/LogicStamp/logicstamp-context/actions)

📑 Table of Contents

• [The Problem](#the-problem)
• [Quick Start](#quick-start)
• [Why Structured Context?](#why-structured-context)
• [Features](#-features)
• [Watch Mode](#watch-mode)
• [How it Works](#how-it-works)
• [MCP Server](#mcp-server)
• [Security](#security)
• [Usage](#usage)
• [Framework Support](#framework-support)
• [Documentation](#documentation)
• [Known Limitations](#known-limitations)
• [Benchmarks](#benchmarks)
• [Requirements](#requirements)
• [Need Help?](#need-help)
• [License](#license)

The Problem

AI coding assistants read your source code - but they don’t understand its structure. They hallucinate props, miss dependencies, and can’t detect when a breaking change impacts consumers.

Example: your Button accepts variant and disabled, but the AI suggests isLoading because it saw that pattern elsewhere. Without a structured contract, there is no reliable source of truth.

LogicStamp Context derives that layer from your TypeScript - explicit interfaces and dependency structure for tools to consume instead of inferring from implementation.

Key Capabilities:

• Contracts, not raw source code - Props, hooks, routes, and dependency edges extracted for tools
• Deterministic & diffable - Same code → same bundles
• Stays current - Watch mode keeps context aligned with your codebase
• MCP-ready - Works with Claude, Cursor, and MCP-compatible assistants

See the full list in [Features](#-features).

Example workflow: stamp context --strict-watch generates context bundles that MCP-powered assistants use to explain component architecture (ThemeContext shown here).

TypeScript Code  →  Compilation  →  Deterministic Contracts  →  AI Assistant
   (.ts/.tsx)        (ts-morph)       (context.json bundles)     (Claude, Cursor)

---

Quick Start

No install required:

npx -y logicstamp-context@latest context

Scans your repo and writes context.json files + context_main.json for AI tools.

What you get:

• 📁 context.json files - one per folder with components, preserving your directory structure
• 📋 context_main.json - index file with project overview and folder metadata

Installation

For ongoing use, install the CLI globally:

npm install -g logicstamp-context

The stamp command is then available everywhere. Initialize and generate context:

stamp init        # sets up .gitignore, scans for secrets
stamp context

> ℹ️ Note: Without a global install, use npx -y logicstamp-context@latest context. After npm install -g logicstamp-context, use stamp context.

📋 For detailed setup instructions, see the Getting Started Guide.

Why Structured Context?

| Without LogicStamp Context | With LogicStamp Context | |-------------------|-----------------| | AI parses ~200 lines of implementation to infer a component's interface | AI reads a ~20-line interface contract | | Props/hooks inferred (often wrong) | Props/hooks explicit and verified | | No way to know if context is stale | Watch mode catches changes in real-time | | Different prompts = different understanding | Deterministic: same code = same contract | | Manual context gathering: "Here's my Button component..." | Structured contracts: AI understands architecture automatically |

Key insight: AI assistants don’t need your implementation - they need your interfaces. LogicStamp extracts what matters and discards the noise.

What "Structured" Means

Instead of sending raw source code to AI:

// Raw: AI must parse and infer
export const Button = ({ variant = 'primary', disabled, onClick, children }) => {
  const [isHovered, setIsHovered] = useState(false);
  // ... 150 more lines of implementation
}

LogicStamp Context generates:

{
  "kind": "react:component",
  "interface": {
    "props": {
      "variant": { "type": "literal-union", "literals": ["primary", "secondary"] },
      "disabled": { "type": "boolean" },
      "onClick": { "type": "function", "signature": "() => void" }
    }
  },
  "composition": { "hooks": ["useState"], "components": ["./Icon"] }
}

Pre-parsed. Categorized. Stable. The AI reads contracts, not implementations.

On disk, each folder’s context.json is a LogicStampBundle: contracts live under graph.nodes, with graph.edges for dependencies. context_main.json indexes folders and metadata. Full JSON shape: [docs/reference/schema.md](docs/reference/schema.md).

⚡ Features

Under the hood: the TypeScript compiler API (via ts-morph). Analysis-only - it describes your codebase and emits context files. It does not transform or refactor your source.

Core:

• Deterministic contracts - Same input = same output, auditable in version control
• Watch mode - Auto-regenerate on file changes with incremental rebuilds
• Breaking change detection - Strict watch mode catches removed props, events, functions in real-time
• MCP-ready - AI agents consume context via standardized MCP interface

Analysis:

• React/Next.js/Vue component extraction (props, hooks, state, deps)
• Backend API extraction (Express.js, NestJS routes and controllers)
• Dependency graphs (handles circular dependencies)
• Monorepo-aware dependency edges via tsconfig paths / baseUrl
• Style metadata extraction (Tailwind, SCSS, MUI, shadcn)
• Next.js App Router detection (client/server, layouts, pages)

Developer experience:

• Per-folder bundles matching your project structure
• Token estimates: GPT-4o via tiktoken when installed (o200k_base, same as gpt-5 in tiktoken’s bundled table). Not every OpenAI model uses that encoding, and very new model IDs may require a newer @dqbd/tiktoken. Claude via optional Anthropic tokenizer (approximate for Claude 3+ per vendor docs) or char fallback
• Security-first: automatic secret detection and sanitization
• Zero config required - sensible defaults, works out of the box

How it fits your stack

• Works alongside tsc - Focuses on contract structure and change detection, not type-checking. Use tsc --noEmit for compiler errors. compare --strict and --strict-watch flag contract-level breaking changes.
• Beyond .d.ts - Adds semantic contracts, dependency graphs, and diffable hashes (semanticHash, bundleHash) alongside declaration surfaces.
• Context, not control - Feeds structured context to assistants. Decisions stay with you.

📋 For detailed behavior, CLI options, and workflows, see the Usage guide.

Watch Mode

Strict watch mode in action: detecting violations and clearing them when resolved.

For development, run watch mode to keep context fresh as you code:

stamp context --watch                  # regenerate on changes
stamp context --strict-watch           # also detect breaking changes (implies --watch)

Strict watch catches breaking changes that affect consumers:

| Violation | Example | |-----------|---------| | breaking_change_prop_removed | Removed disabled prop from Button | | breaking_change_event_removed | Removed onSubmit callback | | breaking_change_function_removed | Deleted exported formatDate() | | contract_removed | Deleted entire component |

Errors vs Warnings: Violations are classified by severity:

❌ Errors indicate breaking changes that will affect consumers (removed props, events, functions, or entire contracts).

⚠️ Warnings indicate less severe changes (type signature changes, removed internal state). Violations are tracked in real-time and automatically cleared when resolved.

Session Status Tracking: Strict watch mode displays a session status block showing cumulative statistics:

• Errors/Warnings detected: Total violations detected during the session
• Resolved: Number of times all violations were completely resolved
• Active: Current number of active violations

The status block only appears when violations change (not on every file change), keeping terminal output clean.

Example terminal output showing violations and session status.

> ℹ️ Note: Strict Watch currently detects breaking changes at the source. Next step: a symbol-level import/export reverse index to trace which consumer files will break. See [docs/cli/watch.md](docs/cli/watch.md) for complete documentation.

One-time Comparison

Compare regenerated context against existing files:

stamp context compare            # detect changes
stamp context compare --approve  # update (like jest -u)

Useful for reviewing changes before committing or validating context is up-to-date.

Git baseline comparison (v0.7.2): Compare against any git ref:

stamp context compare --baseline git:main      # Compare against main branch
stamp context compare --baseline git:HEAD      # Compare against HEAD
stamp context compare --baseline git:v1.0.0    # Compare against a tag

> ℹ️ Note: Context files are gitignored by default. Git baseline comparison uses git worktrees to generate context for both the baseline ref and the current working tree, then performs a structural contract comparison. See [docs/cli/compare.md](docs/cli/compare.md) for complete documentation.

How it Works

The compilation pipeline:

1. Scan - Discovers all .ts and .tsx source files
2. Parse - Builds AST (Abstract Syntax Tree) via ts-morph using the TypeScript compiler API
3. Extract - Compiles contracts with props, hooks, state, signatures
4. Graph - Resolves dependency relationships
5. Emit - Outputs context.json bundles per folder
6. Index - Generates context_main.json with metadata and statistics

One command. No build step required.

> 💡 Tip: Use stamp context for basic contracts. Use stamp context style when you need style metadata (Tailwind classes, SCSS selectors, layout patterns). Use --style-mode lean (default) for compact output or --style-mode full for detailed arrays.

MCP Server

For AI assistants with MCP support (Claude Desktop, Cursor, etc.):

npm install -g logicstamp-mcp

Then configure your AI assistant to use the LogicStamp MCP Server.

🔗 See LogicStamp MCP Server Repository

📋 See MCP Getting Started Guide for setup instructions.

Security

Automatic Secret Protection

LogicStamp Context protects sensitive data in generated context:

• Security scanning by default - stamp init scans source files (.ts, .tsx, .js, .jsx) and .json files for hard-coded secrets before context compilation
• Automatic sanitization - Detected secrets replaced with "PRIVATE_DATA" in output
• Manual exclusions - Use stamp ignore to exclude files via .stampignore
• Safe by default - Only metadata included. Credentials only appear in --include-code full mode

> ⚠️ Seeing "PRIVATE_DATA" in output? Review stamp_security_report.json, remove hardcoded secrets from source, use environment variables instead.

🔒 See SECURITY.md for complete security documentation.

Usage

💻 CLI Usage Reference

stamp --version                    # Show version
stamp --help                       # Show help
stamp init [path]                  # Initialize project (security scan by default)
stamp ignore                 # Add to .stampignore
stamp context [path]               # Generate context bundles
stamp context --max-roots 25       # Cap root bundles in large repos
stamp context style [path]         # Generate with style metadata (lean mode by default)
stamp context style --style-mode full  # Generate with full style details (verbose)
stamp context --watch              # Watch mode
stamp context --strict-watch       # Watch with breaking change detection (--watch optional)
stamp context compare              # Detect changes vs existing context
stamp context validate [file]      # Validate context files
stamp context clean [path]         # Remove generated files

Common Options

| Option | Description | |--------|-------------| | --depth | Dependency traversal depth (default: 2) | | --include-code | Code inclusion: none\|header\|full (default: header) | | --include-style | Extract style metadata (Tailwind, SCSS, animations) | | --format | Output format: json\|pretty\|ndjson\|toon (default: json) | | --max-nodes | Maximum nodes per bundle (default: 100) | | --max-roots | Maximum root bundles to compile (default: all roots) | | --profile | Preset: llm-chat, llm-safe, ci-strict, watch-fast | | --compare-modes | Show token cost comparison across all modes | | --stats | Emit JSON stats with token estimates | | --out | Output directory | | --quiet | Suppress verbose output | | --strict-missing | Exit with error if any missing dependencies found (CI-friendly) | | --debug | Show detailed hash info (watch mode) | | --log-file | Write change logs to .logicstamp/ (watch mode) |

📋 See docs/cli/commands.md for complete reference.

Framework Support

| Framework | Support Level | What's Extracted | |-----------|--------------|------------------| | React | Full | Components, hooks, props, styles | | Next.js | Full | App Router roles, segment paths, metadata | | Vue 3 | Partial | Composition API (TS/TSX only, not .vue SFC) | | Express.js | Full | Routes, API signatures (middleware not extracted. see [limitations](docs/reference/limitations.md)) | | NestJS | Full | Controllers, decorators, API signatures | | UI Libraries | Full | Material UI, ShadCN, Radix, Tailwind, Styled Components, CSS/SCSS (modules & imports), Chakra UI, Ant Design |

> ℹ️ Note: LogicStamp Context analyzes .ts and .tsx files only (JavaScript is not analyzed). Styling (Tailwind, SCSS, CSS Modules, UI libraries) is extracted as structured style metadata, not raw CSS. See the [Style command](docs/cli/style.md).

Documentation

Full documentation at logicstamp.dev/docs

• Getting Started Guide
• Usage Guide
• Monorepo Support
• Output Schema
• UIF Contracts
• Watch Mode
• Troubleshooting

Known Limitations

LogicStamp Context is in beta. Some edge cases are not fully supported.

📋 **See [docs/reference/limitations.md](https://github.com/LogicStamp/logicstamp-context/blob/main/do

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: LogicStamp
• Source: LogicStamp/logicstamp-context
• License: MIT
• Homepage: https://logicstamp.dev

Install and usage instructions live in the source repository linked above.