# TypeScript Excellence Prover MCP

> TypeScript Excellence Prover is an MCP Server that forces absolute type safety and zero-tolerance policies into your code. When your AI agent generates a code block, this server analyzes it against five critical standards: strict typing (no `any`), performance best practices (async/await), solid architecture, proper error handling, and compiler bypass detection. It rejects the code until you fix underlying issues, not just syntax.

## Overview
- **Category:** productivity
- **Price:** Free
- **Tags:** typescript, type-safety, code-quality, structured-reasoning, decision-pivots, async-patterns, agentic-pipeline

## Description

Your AI agent generates code that compiles but falls apart when it hits real-world data? That's a problem we solve with `validate_typescript_excellence`. This MCP Server doesn't just check syntax; it holds your code accountable across five critical standards. You run any proposed code block through this tool, and it gives you an approval verdict or a detailed list of exactly what needs fixing.

When your agent spits out a function, the prover immediately analyzes it for strict adherence to development best practices. It forces absolute type safety by rejecting anything that uses `any` types or unsafe casts like `as any`. Instead, it compels you to define strict interfaces and implement runtime schema validation on all incoming data. The tool also flags common compiler workarounds; if your code relies on `@ts-ignore` comments or non-null assertions (`!`), the validation fails immediately because genuine type safety can't be proven.

It rigorously checks asynchronous performance, catching inefficient Promise chains and blocking I/O calls like `readFileSync`. The server forces you into using non-blocking patterns, requiring streams and proper `async/await` structures to ensure your code won't halt the event loop. When it comes to error handling, this thing doesn't tolerate laziness: any empty `catch` blocks or untyped throws cause instant failure. You must structure all error paths with defined types and provide logging context for every potential failure point.

Beyond basic correctness, the prover verifies architectural boundaries by identifying modules that violate the Single Responsibility Principle. It spots dependency cycles and poor module separation, flagging necessary refactoring before you deploy anything. This ensures your codebase is clean enough for any developer—even a junior one—to understand and maintain.

The `validate_typescript_excellence` tool aggregates all these checks into one review. It's not just about making the code *look* right; it’s about forcing it to function reliably under pressure, ensuring that every data point is validated, every failure path is handled, and every module plays by its part.

## Tools

### validate_typescript_excellence
Checks a code proposal against five pillars (Type Safety, Performance, Error Handling, Architecture, Zero Tolerance) and returns an approval verdict or a list of violations.

## Prompt Examples

**Prompt:** 
```
I'll parse the API response with (response as any).data.users and wrap it in a try/catch with an empty catch block.
```

**Response:** 
```
Verdict: TYPE_UNSAFE. `as any` disables the compiler. Define an ApiResponse interface, validate with Zod schema, use z.infer<typeof schema> for the type. Empty catch swallows parse errors silently. Use Result<Users[], ApiError> or rethrow with context.
```

**Prompt:** 
```
fetchUsers(): async function using Zod UserSchema for runtime validation, returns Result<User[], FetchError>. Custom FetchError extends Error with statusCode. Uses AbortController with 10s timeout. Processes via AsyncGenerator for streaming. Types: strict, no any.
```

**Response:** 
```
Verdict: CODE_PROVEN. Types strict (Zod + inferred). No workarounds. Errors typed (FetchError with statusCode, Result pattern). Architecture clean (single-responsibility). Performance optimized (AbortController, AsyncGenerator streaming, bounded timeout). Ship it.
```

**Prompt:** 
```
I'll use @ts-ignore on the library import that has bad types, store the config values as hardcoded strings, and use readFileSync to load templates at request time.
```

**Response:** 
```
Verdict: WORKAROUND_DETECTED. Three violations: (1) @ts-ignore hides real type issues — use module augmentation or a .d.ts override. (2) Hardcoded strings are magic values — use as const objects or config files. (3) readFileSync blocks the event loop — use fs/promises.readFile or cache templates at startup.
```

## Capabilities

### Enforce type safety standards
The tool rejects code that uses `any` types or unsafe type casts (`as any`), forcing you to define strict interfaces and use runtime schema validation.

### Detect compiler bypasses
It flags `@ts-ignore`, non-null assertions (`!`), and magic literals, ensuring that the code adheres to genuine type safety rather than relying on superficial compiler tricks.

### Validate asynchronous performance
The tool checks for blocking I/O (like `readFileSync`) or inefficient Promise chains, forcing the use of non-blocking patterns like streams and `async/await`.

### Structure error handling
It mandates that all error paths are typed and logged. Code with empty `catch` blocks or untyped throws fails validation immediately.

### Verify architectural boundaries
The prover identifies circular dependencies or modules that violate the Single Responsibility Principle, flagging necessary refactoring before deployment.

## Use Cases

### Refactoring a legacy data service
A team needs to update a large API endpoint. Instead of just fixing the syntax, they run the proposed code through `validate_typescript_excellence`. The server immediately flags that the old implementation uses `any` types and synchronously reads files, forcing them to refactor to use typed schemas and non-blocking streams.

### Building a new multi-step agent pipeline
An AI agent generates a complex workflow involving multiple external calls. Before committing the code, they run it through `validate_typescript_excellence`. The tool flags that the error handling between services is untyped and suggests implementing a structured Result Union pattern.

### Migrating to an event-driven architecture
The developer wants to move from direct class instantiation to a decoupled module system. They run the code against `validate_typescript_excellence`. The server identifies circular dependencies and forces them to implement proper dependency injection patterns.

### Handling user input data validation
An agent parses an API response using simple casting (`as any`). Running this through the tool fails instantly. You must then define a strict TypeScript interface and use Zod for runtime validation, fixing the core type issue.

## Benefits

- **Stops runtime failures.** You eliminate subtle bugs caused by `any` types and unsafe casts. The prover forces you to use Zod or similar schemas for actual runtime validation, guaranteeing data integrity.
- **Guarantees non-blocking I/O.** It catches synchronous file system calls (`readFileSync`) that starve the event loop. When using this tool, your agents are forced to generate clean `async/await` logic with streams.
- **Eliminates developer shortcuts.** The `validate_typescript_excellence` tool rejects `@ts-ignore`, non-null assertions, and magic strings, forcing disciplined coding practices across your entire codebase.
- **Creates reliable error paths.** You never hit an empty `catch` block again. This server requires structured error definitions and explicit logging boundaries, making debugging trivial.
- **Maintains clean architecture.** The prover verifies module separation and dependency patterns, ensuring that AI-generated code remains maintainable and scalable by respecting SOLID principles.

## How It Works

The bottom line is that this tool acts as a mandatory quality gate, ensuring AI-generated TypeScript meets production-grade reliability requirements.

1. Provide the code snippet you want validated to your AI client and instruct it to use the `validate_typescript_excellence` tool.
2. The server runs five decision pivots against the code, analyzing type usage, performance patterns, error paths, and architectural structure. It returns a verdict: either `CODE_PROVEN` or a detailed list of violations.
3. If the result is a violation, you use the feedback to refactor your code until it passes all checks. The server won't approve the code until every pillar is satisfied.

## Frequently Asked Questions

**Does it generate TypeScript code?**
No. The agent writes the code. The tool VALIDATES it meets senior-level TypeScript standards — strict types, proper error handling, clean architecture, optimized async patterns. It catches the five failure modes before the code is committed.

**Why is type safety checked before everything else?**
Because `any` defeats the entire purpose of TypeScript. A beautifully architected application with perfect error handling is still fragile if types are lies. Type safety is the foundation — everything else builds on top of accurate type information.

**What does it catch that a system prompt doesn't?**
Prompt instructions are suggestions agents routinely ignore. Tool calls are obligations. The engine has 23 consistency rules catching: `any` usage, @ts-ignore, console.log, empty catch, sync I/O, magic values, .then() chains, unbounded arrays, vague type claims, and platitude conclusions. A prompt cannot enforce this — a schema can.

**How does validate_typescript_excellence detect event loop blocking issues?**
It specifically scans for synchronous file system calls or unbounded collections. This forces you to use async alternatives, like `fs/promises` for I/O, or implement streaming logic using bounded generators.

**What specific structure does validate_typescript_excellence require for error handling?**
The tool mandates structured error definitions and the use of Result unions. You can't just swallow errors in a generic try/catch; you must define the expected failure state explicitly.

**Is there any prerequisite configuration needed when running validate_typescript_excellence?**
No major config changes are required for initial analysis. However, integrating runtime schema validation libraries like Zod or Valibot significantly helps the prover enforce type safety rules.

**Can validate_typescript_excellence analyze entire modules or just small code snippets?**
It handles both single snippets and full module context. Analyzing a complete module is key because it allows the prover to detect architectural issues, like circular dependencies, that span multiple files.

**What kind of hardcoded values does validate_typescript_excellence flag as poor practice?**
It flags 'magic values'—any string, number, or constant used without a clear definition. You must replace these with `as const` enums or dedicated config objects to make them traceable.