io.github.vola-trebla/tsconfig-inheritance-flattener-mcp

🔍 tsconfig-inheritance-flattener-mcp

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

MCP server that resolves the full TypeScript config inheritance chain and returns the effective compiler options that actually apply — including everything inherited from extended base configs, monorepo packages, and node_modules presets.

🤔 The problem

Your agent reads tsconfig.json and sees:

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

It has no idea that @tsconfig/strictest sets strict: true, noUncheckedIndexedAccess: true, exactOptionalPropertyTypes: true. It doesn't know that baseUrl is defined two levels up in your monorepo base config. So it:

• Suggests code that would fail noUncheckedIndexedAccess
• Gets confused about what @/ resolves to
• Doesn't know your target is ES2022, not ES5
• Gives wrong answers about module resolution

The TypeScript compiler API already resolves all of this. This MCP just exposes it.

🛠️ Tools

get_effective_compiler_options

Resolves the full extends chain and returns the merged compiler options that actually apply to a given tsconfig.json. Shows the inheritance chain, all merged options (with enums as readable strings, not magic numbers), and include/exclude patterns.

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/*"] }

resolve_module_alias

Maps a TypeScript path alias (e.g. @/hooks/useAuth) to its physical file location on disk, using the resolved paths and baseUrl from the tsconfig. Returns all existing candidates with extension probing.

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

Resolved physical paths:
  /project/apps/web/src/hooks/useAuth.ts      ✓ exists

analyze_project_references

Inspects the references array in a root tsconfig.json and validates that each referenced package has composite: true. Catches broken cross-package dependencies in TypeScript monorepos before they cause silent build failures.

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

  [✓] packages/shared → /project/packages/shared/tsconfig.json
  [✗ NOT FOUND] packages/deprecated → /project/packages/deprecated/tsconfig.json

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

🧪 What it looks like in practice

Agent is helping debug a TypeScript error and asks:

"What compiler options are actually active in this project?"

Without this MCP, the agent guesses based on what it sees in tsconfig.json. With it:

get_effective_compiler_options("/project/apps/web/tsconfig.json")
→ strict: true, noUncheckedIndexedAccess: true, target: "ES2022", module: "NodeNext"

Now the agent knows exactly why arr[0] has type string | undefined and not just string. No more wrong suggestions.

⚡ Setup

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

🚀 Usage

"What compiler options actually apply to /project/apps/web/tsconfig.json? It extends a monorepo base and @tsconfig/strictest."

"Where does @/components/Button resolve to on disk?"

"Are the project references in my root tsconfig valid? Do all referenced packages have composite: true?"

Works great alongside:

• ast-impact-mapper-mcp — for code→test correlation
• release-readiness-triage-mcp — for CI triage

📦 Links

• npm: npmjs.com/package/tsconfig-inheritance-flattener-mcp
• GitHub: github.com/vola-trebla/tsconfig-inheritance-flattener-mcp

License

MIT