Installation

Before you begin

You need Node.js ≥ 22.12.0 and a JavaScript or TypeScript repository. Run the commands below from that project’s root, not from a shared tools directory.

node --version

The default . workflow requires a root tsconfig.json for TypeScript; advanced first-target selection is different. For a JavaScript-only project, init leaves TypeScript disabled when no root config is detected.

1. Add the package

Install signalint-mcp as a development dependency. The commands below currently resolve npm’s latest version; these docs audit 1.2.1. Add @1.2.1 to the package name if you need that exact edition:

npm

npm install --save-dev signalint-mcp

pnpm

pnpm add -D signalint-mcp

yarn

yarn add -D signalint-mcp

Provide the engines you need

Since 1.1.0, Oxlint and TypeScript are optional peer dependencies, not runtime dependencies bundled by a default Signalint install. Biome is also optional; ESLint must be installed in the project. Reuse your project’s compatible toolchain, or add the engines you intend to enable:

npm install --save-dev oxlint typescript

The published peer declarations are oxlint@1.86.0, typescript@7.0.2, and optional @biomejs/biome@2.5.15; those are the versions used in the source audit. Check compatibility before changing an existing project’s compiler/linter versions. A fresh Signalint-only install does not supply them; unresolved enabled engines report disabled, and no successful engine yields nothing_checked, not clean.

2. Initialize the project

npx signalint-mcp init

The setup command:

• Detects TypeScript, Oxlint, Biome, flat ESLint, and Prettier configuration.
• Creates signalint.config.json if it does not already exist.
• Appends .signalint/ to .gitignore when no exact .signalint or .signalint/ line exists. The v1 CLI does this automatically, including non-interactive runs; it does not normally prompt for this write.
• Detects nearby MCP clients and asks before updating a selected client configuration.

TypeScript is enabled when a root tsconfig.json exists. Biome and ESLint follow their detected root configs. In v1, Oxlint is enabled when a root .oxlintrc or .oxlintrc.* file is detected or no Biome config exists; it can therefore coexist with ESLint. Review the generated file before your first check.

No client detected?

If a client cannot be selected safely, init prints copyable configuration snippets. Follow the guide for your client rather than creating a global entry with a fixed working directory.

3. Inspect the setup

The package provides two executables: signalint is the explicit terminal CLI; signalint-mcp starts stdio when launched by an MCP client. Since 1.1.1 the MCP entry point also dispatches recognized CLI verbs, so signalint-mcp doctor now works. A bare interactive TTY launch prints guidance and exits 2, rather than waiting for JSON-RPC.

npm

npx --no-install signalint doctor

pnpm

pnpm exec signalint doctor

yarn

yarn run signalint doctor

Doctor checks the root, configuration-file existence, JS/TS markers, package metadata for all four engines, active payload mode, and some stale cwd entries. It now warns about unavailable linters or TypeScript, but warnings do not necessarily make it fail. Config parse errors can still be swallowed; PASSED does not prove config validity, engine execution, or an MCP connection. Review the output, then verify ping using the default both mode.

Upgrading from 1.0.0

Install selected engines explicitly if you relied on bundled Oxlint/TypeScript. Update response consumers for schema 1.4, missing inactive warnings, optional engine-map entries, and flat remaining records. The explicit signalint CLI remains a clear choice; recognized signalint-mcp CLI verbs no longer hang as they did in 1.0.

4. Connect and check

Open your client setup guide, restart or reconnect the MCP client, then follow the quickstart.

You can also check the repository without an MCP client:

npx --no-install signalint check .

The CLI prints clustered JSON. An exit code of 1 is expected when issues are found with the default settings.

The JSON client-file merger uses strict JSON, not JSONC. Back up existing settings: comments or trailing commas can make init fail; the selected Signalint entry is replaced, so recheck any custom env or arguments. See client setup.

Keep signalint.config.json in version control if it is part of your team’s setup. Do not commit .signalint/: it contains local cache and session state.