# Logicstamp Context

> A Context Compiler for TypeScript. Deterministic, diffable architectural contracts and dependency graphs for AI coding workflows.

- **Type:** MCP server
- **Install:** `agentstack add mcp-logicstamp-logicstamp-context`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [LogicStamp](https://agentstack.voostack.com/s/logicstamp)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [LogicStamp](https://github.com/LogicStamp)
- **Source:** https://github.com/LogicStamp/logicstamp-context
- **Website:** https://logicstamp.dev

## Install

```sh
agentstack add mcp-logicstamp-logicstamp-context
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

## 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](https://github.com/LogicStamp/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:

```bash
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:

```bash
npm install -g logicstamp-context
```

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

```bash
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](https://logicstamp.dev/docs/getting-started).**

## 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:

```typescript
// 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:

```json
{
  "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](https://github.com/LogicStamp/logicstamp-context/blob/main/docs/guides/usage.md).**

## 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:

```bash
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:

```bash
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:
```bash
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.):

```bash
npm install -g logicstamp-mcp
```

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

🔗 **See [LogicStamp MCP Server Repository](https://github.com/LogicStamp/logicstamp-mcp)**

📋 **See [MCP Getting Started Guide](https://logicstamp.dev/docs/mcp/getting-started)** 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](https://github.com/LogicStamp/logicstamp-context/blob/main/SECURITY.md)** for complete security documentation.

## Usage

💻 CLI Usage Reference

```bash
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](https://github.com/LogicStamp/logicstamp-context/blob/main/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](https://logicstamp.dev/docs)**

- [Getting Started Guide](https://logicstamp.dev/docs/getting-started)
- [Usage Guide](https://github.com/LogicStamp/logicstamp-context/blob/main/docs/guides/usage.md)
- [Monorepo Support](https://github.com/LogicStamp/logicstamp-context/blob/main/docs/guides/monorepo.md)
- [Output Schema](https://github.com/LogicStamp/logicstamp-context/blob/main/docs/reference/schema.md)
- [UIF Contracts](https://github.com/LogicStamp/logicstamp-context/blob/main/docs/reference/uif-contracts.md)
- [Watch Mode](https://github.com/LogicStamp/logicstamp-context/blob/main/docs/cli/watch.md)
- [Troubleshooting](https://github.com/LogicStamp/logicstamp-context/blob/main/docs/guides/usage.md#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](https://github.com/LogicStamp)
- **Source:** [LogicStamp/logicstamp-context](https://github.com/LogicStamp/logicstamp-context)
- **License:** MIT
- **Homepage:** https://logicstamp.dev

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** yes

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-logicstamp-logicstamp-context
- Seller: https://agentstack.voostack.com/s/logicstamp
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.