DEV Community

Cover image for Your AI agent reads tsconfig.json. It has absolutely no idea what it means
Albert Alov
Albert Alov

Posted on

Your AI agent reads tsconfig.json. It has absolutely no idea what it means

#typescript #ai #mcp #developertools

Your agent sees "extends": "@tsconfig/strictest" and hallucinates the rest. Here's an MCP server that uses the TypeScript compiler API to resolve the full inheritance chain and return what actually applies.

Here's a scene that happens more than you'd think.

You ask your AI agent to help with a TypeScript error. It reads your tsconfig.json, sees this:

{
  "extends": "@tsconfig/strictest",
  "compilerOptions": {
    "paths": { "@/*": ["./src/*"] }
  }
}
Enter fullscreen mode Exit fullscreen mode

And confidently suggests:

// "This should work fine — I don't see strict mode enabled"
const users = getUsers();
const first = users[0].name; // ❌ Object is possibly 'undefined'
Enter fullscreen mode Exit fullscreen mode

It's wrong. @tsconfig/strictest sets noUncheckedIndexedAccess: true. users[0] is User | undefined, not User. The agent doesn't know this because it never looked inside @tsconfig/strictest. It just guessed.

This is tsconfig-inheritance-flattener-mcp. 🔍

🙈 What the agent actually sees

When your agent reads tsconfig.json, it reads exactly what's in the file. Nothing more.

The extends field points to a package or another file — and the agent stops there. It doesn't chase the chain. It doesn't know what that base config sets. It fills in the blanks from training data, and training data is not your project.

In a typical monorepo this chain can be 3 levels deep:

apps/web/tsconfig.json
  → tsconfig.base.json
    → node_modules/@tsconfig/strictest/tsconfig.json
Enter fullscreen mode Exit fullscreen mode

The final target, module, moduleResolution, strict, paths, baseUrl — all of it is scattered across these files. Without resolving the full chain, the agent is flying blind.

🔧 What the TypeScript compiler API actually knows

Here's the thing: TypeScript already solves this problem. Every time tsc runs, it resolves the full chain and produces a single merged set of compiler options. The API is right there:

const raw = ts.readConfigFile(configPath, ts.sys.readFile);
const parsed = ts.parseJsonConfigFileContent(
  raw.config, ts.sys, path.dirname(configPath), {}, configPath
);
// parsed.options = fully merged CompilerOptions ✅
Enter fullscreen mode Exit fullscreen mode

We're not reimplementing anything. We're just exposing what TypeScript already computes — via MCP, so your agent can ask.

🛠️ Three tools

get_effective_compiler_options

Resolves the full extends chain and returns the merged options that actually apply. Enums come back as readable strings, not magic numbers ("ES2022" not 9, "NodeNext" not 199).

Effective TypeScript Configuration
  Config:            /project/apps/web/tsconfig.json
  Inheritance chain: /project/apps/web/tsconfig.json
                     → /project/tsconfig.base.json
                     → node_modules/@tsconfig/strictest/tsconfig.json

Compiler Options (merged):
  target: "ES2022"
  module: "NodeNext"
  moduleResolution: "NodeNext"
  strict: true
  noUncheckedIndexedAccess: true
  exactOptionalPropertyTypes: true
  baseUrl: "/project"
  paths: { "@/*": ["apps/web/src/*"] }
Enter fullscreen mode Exit fullscreen mode

Now the agent knows why users[0] is User | undefined. No guessing.

resolve_module_alias

Maps @/hooks/useAuth to the physical file on disk. Uses the resolved paths and baseUrl from the full inheritance chain — not just what's in the nearest tsconfig.json.

Alias Resolution: @/hooks/useAuth
  Config:   /project/apps/web/tsconfig.json
  Base URL: /project

Resolved physical paths:
  /project/apps/web/src/hooks/useAuth.ts   ✓ exists
Enter fullscreen mode Exit fullscreen mode

When the agent needs to navigate to the file behind an import, it no longer has to guess the folder structure.

analyze_project_references

Validates the references array in monorepo root configs. Checks that each referenced package has composite: true — without it, TypeScript's incremental build silently breaks.

Project References Analysis
  Config: /project/tsconfig.json
  References found: 2

  [✓] packages/shared → /project/packages/shared/tsconfig.json
  [✗] packages/legacy → /project/packages/legacy/tsconfig.json (NOT FOUND)

Violations:
  ✗ packages/shared is referenced but does not have composite: true
    Fix: add "composite": true to packages/shared/tsconfig.json
Enter fullscreen mode Exit fullscreen mode

⚡ Setup 

{
  "mcpServers": {
    "tsconfig-flattener": {
      "command": "npx",
      "args": ["-y", "tsconfig-inheritance-flattener-mcp"]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

That's it. Works in Claude Desktop, Cursor, or any MCP-compatible client.

🐸 The pattern

Every MCP server in this series follows the same logic: find a place where an AI agent is structurally blind — not because it's dumb, but because it literally cannot see the data — and expose that data via a tool.

tsconfig.json inheritance is a perfect example. The agent isn't hallucinating out of laziness. It's hallucinating because the information it needs is locked inside a chain of files it never opened, or inside a npm package it can't inspect at runtime.

The TypeScript compiler API already resolves all of this. We just asked it nicely. 🔍

📦 Links

Top comments (0)