io.github.vola-trebla/tsconfig-inheritance-flattener-mcp
Resolves TypeScript config inheritance chains and returns effective compiler options per file.
Open source Open in the app JSON README (API)
About
Resolves TypeScript config inheritance chains and returns effective compiler options per file.
Details
- Kind
- MCP servers
- Topic
- Developer tools
- Publisher
- vola-trebla
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.2.0
- Last push
- 2026-05-20T21:00:44Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:01:39
- Updated
- 2026-08-29 04:01:39
- Origin id
io.github.vola-trebla/tsconfig-inheritance-flattener-mcp
README
# 🔍 tsconfig-inheritance-flattener-mcp
[](https://www.npmjs.com/package/tsconfig-inheritance-flattener-mcp)
[](https://github.com/vola-trebla/tsconfig-inheritance-flattener-mcp/actions)
[](LICENSE)
**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:
```json
{ "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
```json
{
"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](https://www.npmjs.com/package/ast-impact-mapper-mcp) — for code→test correlation
- [release-readiness-triage-mcp](https://www.npmjs.com/package/release-readiness-triage-mcp) — for CI triage
---
## 📦 Links
- **npm:** [npmjs.com/package/tsconfig-inheritance-flattener-mcp](https://www.npmjs.com/package/tsconfig-inheritance-flattener-mcp)
- **GitHub:** [github.com/vola-trebla/tsconfig-inheritance-flattener-mcp](https://github.com/vola-trebla/tsconfig-inheritance-flattener-mcp)
## License
MIT