trustdex 0.4.3 → 0.5.0

package/README.md

@@ -54,6 +54,7 @@ TrustDex deliberately does not infer "official" status from names, stars, or bra
 - run as a GitHub Action in CI
 - fingerprint MCP entries, skills, and plugin manifests without storing secret values
 - inspect and filter Codex `config.toml` MCP sections
+- inspect and filter Claude Code MCP JSON with explicit transport validation and header execution controls
 - perform explicit provenance lookups against GitHub, npm, and the official MCP Registry
 - verify whether the latest GitHub release tag/commit has a GitHub-verified signature
 - create signed review bundles and automatically require re-review when trust-relevant state drifts
@@ -75,8 +76,8 @@ Requires Node.js 20+.
 Run directly from npm:
 
 ```bash
-npx trustdex@0.4.3 --help
-npx trustdex@0.4.3 inspect ./mcp.json --pack strict --policy ./trustdex.policy.json
+npx trustdex@0.5.0 --help
+npx trustdex@0.5.0 inspect ./mcp.json --pack strict --policy ./trustdex.policy.json
 ```
 
 Or work from a source checkout:
@@ -100,6 +101,23 @@ Exit codes for inspection:
 - `1` - at least one entry needs review
 - `2` - at least one entry is blocked, or the command failed
 
+## Reproducible defensive research
+
+TrustDex includes an inert adversarial benchmark for testing the policy boundary without contacting or executing third-party services. The fixtures use reserved `.invalid` domains, placeholder credentials, and configuration data only; TrustDex inspects them statically and never launches the listed servers.
+
+```bash
+npm run test:research
+
+node ./bin/trustdex.mjs inspect \
+  ./examples/adversarial/mcp-config.json \
+  --pack strict \
+  --policy ./examples/adversarial/policy.json
+```
+
+The direct inspection intentionally exits with code `2`: the checked-in expectation is one `ALLOW`, one `ASK`, and five `BLOCK` decisions. The automated test also verifies that placeholder secret values do not appear in results and that a newly introduced secret-bearing environment variable invalidates the previous review state.
+
+See the [defensive security research policy](docs/SECURITY_RESEARCH.md), [evaluation record](docs/EVALUATION.md), and [adversarial fixture guide](examples/adversarial/README.md).
+
 ## Built-in policy packs
 
 ```bash
@@ -149,6 +167,26 @@ The gate removes non-approved MCP sections while preserving unrelated TOML secti
 
 See [Using TrustDex with Codex](docs/CODEX.md) for a step-by-step gating workflow and for how this project uses Codex in its own review process.
 
+## Claude Code MCP configuration
+
+Claude Code uses the `mcpServers` JSON shape. Use the Claude-specific commands so
+transport changes, authentication header metadata, and header helper commands
+are included in inspection and signed review:
+
+```bash
+node ./bin/trustdex.mjs inspect-claude ./.mcp.json --pack strict
+node ./bin/trustdex.mjs gate-claude ./.mcp.json --pack strict --out .trustdex/claude-mcp.json
+claude --strict-mcp-config --mcp-config .trustdex/claude-mcp.json
+```
+
+Check the gate's result before starting Claude. Only `ALLOW` entries are exposed by
+default; `ASK` entries require review. The adapter rejects settings it cannot
+inspect instead of silently trusting them. These commands are available in npm 0.5.0 and later, and from a source checkout.
+Use `npx trustdex@0.5.0` in place of `node ./bin/trustdex.mjs` to run the published CLI.
+
+See [Using TrustDex with Claude](docs/CLAUDE.md) for supported settings, PowerShell
+error handling, signed review, and the Claude Desktop workflow.
+
 ## Online provenance observations
 
 Normal inspection remains local-only. These commands perform an explicit network lookup only when invoked:
@@ -294,7 +332,7 @@ The private key should never be committed.
 ```yaml
 - uses: actions/checkout@v4
 
-- uses: grigent/trustdex@v0.4.3
+- uses: grigent/trustdex@v0.5.0
   with:
     config: ./mcp.json
     pack: official-first
@@ -322,7 +360,7 @@ The public roadmap is maintained in [docs/ROADMAP.md](docs/ROADMAP.md). Near-ter
 
 TrustDex does **not** prove that third-party code is safe and does not replace sandboxing, dependency scanning, code review, or least-privilege credentials.
 
-See [SECURITY.md](SECURITY.md), [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md), and [docs/TRUST_STORE.md](docs/TRUST_STORE.md).
+See [SECURITY.md](SECURITY.md), [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md), [docs/SECURITY_RESEARCH.md](docs/SECURITY_RESEARCH.md), [docs/EVALUATION.md](docs/EVALUATION.md), and [docs/TRUST_STORE.md](docs/TRUST_STORE.md).
 
 ## Contributing
 

package/bin/trustdex.mjs

@@ -6,6 +6,7 @@ import process from 'node:process';
 
 import { inspectMcpConfig } from '../src/inspect.mjs';
 import { parseCodexMcpToml, gateCodexToml } from '../src/codex-config.mjs';
+import { parseClaudeMcpConfig } from '../src/claude-config.mjs';
 import { inspectSkillText, inspectPluginManifest } from '../src/extensions.mjs';
 import { evaluateAll } from '../src/policy.mjs';
 import { getPolicyPack, mergePolicy } from '../src/policy-packs.mjs';
@@ -48,6 +49,13 @@ Usage:
   trustdex gate-codex <config.toml> --out gated.toml [--pack ...] [--policy policy.json]
       [--trust-store trust-store.json] [--include-ask]
 
+  trustdex inspect-claude <.mcp.json> [--pack ...] [--policy policy.json] [--json]
+  trustdex gate-claude <.mcp.json> --out gated.json [--pack ...] [--policy policy.json]
+  trustdex snapshot-claude <.mcp.json> --out snapshot.json [--pack ...]
+  trustdex approve-claude <.mcp.json> --private key.pem --dir review [--pack ...]
+  trustdex recheck-claude <.mcp.json> --review-dir review --public key.pem [--json]
+  Claude commands accept the same policy/trust-store flags as their generic counterparts.
+
   trustdex provenance github <owner/repo> [--json]
   trustdex provenance github-release <owner/repo> [--json]
   trustdex provenance npm <package> [--json]
@@ -146,8 +154,14 @@ function setInspectExitCode(results) {
 }
 
 async function evaluateMcp(configPath, args) {
-  const config = await readJson(configPath);
-  const inspected = inspectMcpConfig(config);
+  const isClaude = args[0].endsWith('-claude');
+  let config;
+  try { config = await readJson(configPath); } catch (error) {
+    if (isClaude && error instanceof SyntaxError) throw new Error('Invalid Claude MCP JSON.');
+    throw error;
+  }
+  const inspectionConfig = isClaude ? parseClaudeMcpConfig(config) : config;
+  const inspected = inspectMcpConfig(inspectionConfig);
   const store = await loadTrustStore(args);
   const withProvenance = store ? attachProvenanceAll(inspected, store) : inspected;
   const policy = await loadPolicy(args);
@@ -225,7 +239,7 @@ async function main() {
     return;
   }
 
-  if (command === 'inspect') {
+  if (command === 'inspect' || command === 'inspect-claude') {
     const configPath = args[1];
     if (!configPath) throw new Error('inspect requires a path to an MCP JSON file.');
 
@@ -311,7 +325,7 @@ async function main() {
     return;
   }
 
-  if (command === 'gate') {
+  if (command === 'gate' || command === 'gate-claude') {
     const configPath = args[1];
     const out = getFlag(args, '--out');
     if (!configPath || !out) throw new Error('gate requires <mcp.json> and --out <gated.json>.');
@@ -332,7 +346,7 @@ async function main() {
     return;
   }
 
-  if (command === 'approve') {
+  if (command === 'approve' || command === 'approve-claude') {
     const configPath = args[1];
     const privatePath = getFlag(args, '--private');
     const reviewDir = getFlag(args, '--dir');
@@ -364,7 +378,7 @@ async function main() {
     return;
   }
 
-  if (command === 'recheck') {
+  if (command === 'recheck' || command === 'recheck-claude') {
     const configPath = args[1];
     const reviewDir = getFlag(args, '--review-dir');
     const publicPath = getFlag(args, '--public');
@@ -409,7 +423,7 @@ async function main() {
     return;
   }
 
-  if (command === 'snapshot') {
+  if (command === 'snapshot' || command === 'snapshot-claude') {
     const configPath = args[1];
     const out = getFlag(args, '--out');
     if (!configPath || !out) throw new Error('snapshot requires <mcp.json> and --out <snapshot.json>.');

package/docs/CLAUDE.md

@@ -0,0 +1,133 @@
+# Using TrustDex with Claude
+
+TrustDex can inspect Claude MCP JSON before Claude Code or Claude Desktop receives it.
+It evaluates configuration evidence locally, does not start MCP servers, and does not
+upload your configuration. An ALLOW decision means the evidence matched your policy;
+it does not prove that server code is safe.
+
+The Claude-specific commands are available in TrustDex 0.5.0 and later.
+Use `npx trustdex@0.5.0` in place of `node ./bin/trustdex.mjs` in the examples
+below to run the published CLI, or use the commands directly from a source checkout.
+
+## Supported configuration
+
+Use a dedicated JSON file with a top-level `mcpServers` object:
+
+```json
+{
+  "mcpServers": {
+    "reviewed-tools": {
+      "type": "http",
+      "url": "https://your-reviewed-server.example/mcp"
+    }
+  }
+}
+```
+
+The URL above is illustrative; configure your own reviewed server and trust policy.
+
+Supported server fields:
+
+| Transport | Fields |
+| --- | --- |
+| `stdio` (also the default when `type` is omitted) | `type`, `command`, `args`, `env` |
+| `http` or `sse` | `type`, `url`, `headers`, `headersHelper` |
+
+Remote entries require an explicit `type`. Command arguments and environment/header
+values must be strings. Unknown root/server fields, other transports, malformed
+entries, unresolved command/argument/endpoint variables, and URLs containing
+credentials, query parameters, or fragments fail closed. This intentionally excludes
+custom `oauth`, `alwaysLoad`, WebSocket settings, and future controls until they have
+an explicit inspection implementation. Ordinary server-managed OAuth needs no
+`oauth` field and remains Claude's responsibility.
+
+Authentication headers add `static-http-headers` and/or `env-http-headers` signals.
+Built-in packs require review for them. `headersHelper` adds
+`header-helper-command`, which built-in packs block because Claude executes it in a
+shell. TrustDex never runs the helper.
+
+Fingerprints include the transport, header names, referenced environment-variable
+names, and helper presence. Header/variable values, defaults, and helper command text
+are omitted. Rotating a credential value alone does not invalidate a review; changing
+its header name or environment reference does. Avoid putting credentials in command
+arguments or URL paths. Gated files preserve original allowed entries and can contain
+credentials supplied in the input: keep them local and out of version control.
+
+## Claude Code
+
+Claude Code reads project MCP configuration from `.mcp.json`. Inspect it using the
+Claude adapter, then supply only the generated configuration for that session.
+
+From a source checkout in PowerShell:
+
+```powershell
+node ./bin/trustdex.mjs inspect-claude ./.mcp.json --pack strict --policy ./trustdex.policy.json
+
+node ./bin/trustdex.mjs gate-claude ./.mcp.json --pack strict --policy ./trustdex.policy.json --out ./.trustdex/claude-mcp.json
+if ($LASTEXITCODE -ne 0) { throw "Resolve the gate error or pending reviews before starting Claude." }
+
+claude --strict-mcp-config --mcp-config ./.trustdex/claude-mcp.json
+```
+
+The policy file is your explicit trust policy, not a list inferred from vendor names.
+Omit `--policy` to use the strict defaults, which block unknown sources and ask about
+local programs. By default, the gate includes only ALLOW entries. ASK and BLOCK entries
+stay out. A gate exit code of `1` indicates pending ASK decisions; `2` indicates failure.
+Do not launch using an old output file after a failed gate.
+
+The `--strict-mcp-config` flag matters: `--mcp-config` alone adds a configuration
+alongside other MCP sources. Organizations using managed MCP configuration should
+also verify the managed policy's effective servers. This workflow does not gate
+Claude's built-in tools or inspect every skill/plugin automatically.
+
+Inside the resulting Claude Code session, use `/mcp` to verify the actual loaded
+servers. Configuration/unit tests do not replace that runtime check.
+
+Official references:
+[Claude Code MCP](https://code.claude.com/docs/en/mcp) and
+[CLI flags](https://code.claude.com/docs/en/cli-reference).
+
+## Signed review and drift
+
+Keep the Claude adapter throughout a review workflow; generic MCP commands do not
+inspect Claude-specific controls.
+
+```bash
+node ./bin/trustdex.mjs keygen --private .trustdex/private.pem --public .trustdex/public.pem
+node ./bin/trustdex.mjs approve-claude ./.mcp.json --private .trustdex/private.pem --dir .trustdex/claude-review --pack strict --policy ./trustdex.policy.json
+node ./bin/trustdex.mjs recheck-claude ./.mcp.json --review-dir .trustdex/claude-review --public .trustdex/public.pem
+node ./bin/trustdex.mjs snapshot-claude ./.mcp.json --out .trustdex/claude-snapshot.json --pack strict --policy ./trustdex.policy.json
+```
+
+Approval refuses BLOCK decisions. ASK decisions require an explicit human review;
+running `approve-claude` records that review but does not automatically change the
+gate's policy. Rechecks return APPROVED, NEEDS_REVIEW, or INVALID. A pre-existing
+generic review has a different fingerprint and must be reviewed with the Claude adapter.
+Private keys must never be committed.
+
+## Claude Desktop
+
+For a local stdio MCP configuration, export just the `mcpServers` object from
+`claude_desktop_config.json` into a dedicated input file. Do not feed unrelated
+Desktop preferences into the MCP adapter. Use `inspect-claude` and `gate-claude`
+on that file, review the result, then replace only the Desktop config's `mcpServers`
+section with the gated section and restart Claude Desktop. Keep a backup of the
+original configuration.
+
+TrustDex does not modify your active Desktop settings or install a connector.
+Desktop extensions and account-level remote connectors require separate review;
+this JSON gate does not automatically govern them.
+
+## Inert example
+
+`examples/claude.mcp.json` uses reserved `.invalid` domains, a placeholder
+environment-variable reference, and an inert helper string. Do not launch it in
+Claude. It is for static inspection only:
+
+```bash
+node ./bin/trustdex.mjs inspect-claude ./examples/claude.mcp.json --pack strict --policy ./examples/claude.policy.json
+node ./bin/trustdex.mjs gate-claude ./examples/claude.mcp.json --pack strict --policy ./examples/claude.policy.json --out .trustdex/example-claude.json
+```
+
+Inspection intentionally exits `2`. The expected decisions are one ALLOW, one ASK,
+and two BLOCK; the gate writes only `reviewed` and exits `1` because a review remains.

package/docs/CODEX.md

@@ -11,7 +11,7 @@ Codex clients read MCP server definitions from `[mcp_servers.<name>]` tables in
 ### 1. Inspect the current configuration
 
 ```bash
-npx trustdex@0.4.3 inspect-codex ~/.codex/config.toml --pack strict
+npx trustdex@0.4.4 inspect-codex ~/.codex/config.toml --pack strict
 ```
 
 This reads the file locally and makes no network request. The output lists each MCP server, its source type, trust signals, and an ALLOW / ASK / BLOCK decision. Environment variable names may appear; their values never do.
@@ -21,7 +21,7 @@ Use `--json` for machine-readable output and `--trust-store ./trust-store.json`
 ### 2. Write a gated copy
 
 ```bash
-npx trustdex@0.4.3 gate-codex ~/.codex/config.toml \
+npx trustdex@0.4.4 gate-codex ~/.codex/config.toml \
   --pack official-first \
   --trust-store ./trust-store.json \
   --out ./gated-config.toml
@@ -52,8 +52,8 @@ TrustDex parses only the TOML constructs used by Codex MCP sections. An unsuppor
 Agent skills and plugin manifests can be inspected the same way:
 
 ```bash
-npx trustdex@0.4.3 inspect-skill ./path/to/SKILL.md --pack strict
-npx trustdex@0.4.3 inspect-plugin ./path/to/plugin.json --pack strict
+npx trustdex@0.4.4 inspect-skill ./path/to/SKILL.md --pack strict
+npx trustdex@0.4.4 inspect-plugin ./path/to/plugin.json --pack strict
 ```
 
 These report observable signals such as piped shell installers, references to sensitive paths, network URLs, and wildcard tool scopes. They do not prove a skill or plugin is safe.

package/docs/EVALUATION.md

@@ -0,0 +1,35 @@
+# Defensive evaluation
+
+This evaluation records the behavior enforced by the checked-in adversarial fixtures. Run `npm run test:research` to reproduce it. The test performs local static inspection only and does not execute or contact any configured server.
+
+## MCP policy cases
+
+The cases use the built-in `strict` policy with the small overlay in `examples/adversarial/policy.json`.
+
+| Case | Required evidence | Expected decision | Reason |
+| --- | --- | --- | --- |
+| `trusted-pinned-package` | pinned package; explicitly trusted package name | `ALLOW` | the configured version is fixed and the policy contains an explicit package trust rule |
+| `floating-version` | `install-on-run`, `unbounded-version` | `BLOCK` | a moving package version can change without review |
+| `shell-launcher` | `shell-execution`, `filesystem-path` | `BLOCK` | shell execution is blocked by the strict policy |
+| `credential-bearing-url` | `embedded-credentials`, `network-endpoint`, `url-query-parameters` | `BLOCK` | embedded credentials are blocking even when the host is allowlisted |
+| `insecure-remote` | `insecure-transport`, `network-endpoint` | `BLOCK` | plaintext transport is blocking even when the host is allowlisted |
+| `sensitive-local-env` | `filesystem-path`, `secret-env` | `ASK` | a local extension with a secret-like environment name requires review |
+| `unknown-remote` | `network-endpoint` | `BLOCK` | the remote host has no explicit allowlist or provenance evidence |
+
+Expected total: one `ALLOW`, one `ASK`, and five `BLOCK` decisions.
+
+## Drift case
+
+The drift fixture begins with the trusted pinned package and then introduces an `API_TOKEN` environment key. The regression test requires all of the following changes:
+
+- `signals-added` for `secret-env`
+- `decision-changed` from `ALLOW` to `ASK`
+- `fingerprint-changed`
+
+The placeholder value itself must not appear in either inspection result or snapshot.
+
+## What this does not measure
+
+This benchmark is intentionally narrow. It does not measure runtime behavior, sandbox escape, arbitrary malware, every form of prompt injection, publisher identity ownership, or vulnerabilities in transitive dependencies. In particular, tool descriptions returned dynamically by an already-running MCP server are outside the current static configuration boundary.
+
+The small fixture set is a regression baseline, not a statistical claim about detection accuracy. False-positive and false-negative rates require a larger, independently reviewed corpus of redacted real-world configurations.

package/docs/RELEASING.md

@@ -30,12 +30,29 @@ Once trusted publishing works, remove the `NPM_TOKEN` repository secret and revo
 
 Both release workflows run `npm pkg fix` and require a clean `package.json` diff before packing or publishing. This prevents npm from silently normalizing away critical metadata such as the CLI entrypoint.
 
-## Provenance
+## Provenance and release evidence
 
 The repository is public and the package is public, so GitHub-hosted publishing can emit npm provenance. The workflow also passes `--provenance` explicitly.
 
 Provenance links the published artifact to its source/build environment. It does not prove that the package contains no malicious behavior.
 
+The GitHub release workflow also creates and uploads:
+
+- the npm package tarball built from the release commit
+- a CycloneDX JSON SBOM
+- a `SHA256SUMS` file covering the tarball and SBOM
+- a GitHub build-provenance attestation for the tarball
+- a GitHub SBOM attestation binding the SBOM to the tarball
+
+After downloading a release, verify its checksum and GitHub attestation before inspection or installation:
+
+```bash
+shasum -a 256 -c SHA256SUMS
+gh attestation verify trustdex-<version>.tgz --repo grigent/trustdex
+```
+
+The npm provenance statement and GitHub attestations cover different publication paths. Neither is a malware analysis or a substitute for reviewing the release contents and the documented trust boundary.
+
 ## Version checklist
 
 Before each release:

package/docs/SECURITY_RESEARCH.md

@@ -0,0 +1,60 @@
+# Defensive security research
+
+TrustDex is developed for legitimate defensive research into trust decisions made before AI agents receive access to third-party tools. This document defines the authorization, safety, and disclosure boundaries for that work.
+
+## Purpose
+
+The research asks whether observable configuration, provenance, integrity, and capability evidence is sufficient to keep an extension unavailable until a human or policy explicitly trusts it. Current work focuses on:
+
+- unpinned or substituted packages
+- install-on-run and shell launchers
+- embedded URL credentials and insecure remote transport
+- secret-bearing environment variable names without retaining their values
+- source, provenance, decision, fingerprint, and capability drift
+- signed review records and re-review after trust-relevant change
+- parser behavior that must fail closed on unsupported syntax
+
+The intended outputs are reproducible fixtures, regression tests, documented limitations, and practical mitigations for agent developers and operators.
+
+## Authorization boundary
+
+Research is limited to:
+
+- systems and accounts owned by the researcher; or
+- systems for which the researcher has explicit authorization to test; and
+- isolated local or purpose-built test environments using non-sensitive fixtures.
+
+TrustDex research does not authorize testing unrelated public systems. It excludes credential theft, persistence, destructive actions, data exfiltration, mass exploitation, unauthorized access, malware deployment, and bypassing another party's safeguards.
+
+## Safe test data
+
+Checked-in adversarial fixtures are inert configuration documents. They use reserved `.invalid` domains, nonexistent package namespaces, and unmistakable placeholder values. TrustDex does not execute MCP servers during inspection.
+
+Tests assert that secret-like values, URL credentials, query values, and private paths do not appear in inspection results. A fixture that requires a real credential, private endpoint, personal data, or production service is not acceptable for this repository.
+
+## Method
+
+Each research case should contain:
+
+1. a minimal, reviewable input fixture
+2. the expected trust-relevant signals
+3. the expected `ALLOW`, `ASK`, or `BLOCK` decision under a named policy
+4. an automated regression test
+5. a documented limitation or plausible bypass condition
+
+An `ALLOW` result means only that observed evidence matched the selected policy. It is never represented as proof that arbitrary code is safe.
+
+## Handling findings
+
+Potential TrustDex vulnerabilities that could put users at risk should follow [SECURITY.md](../SECURITY.md). Findings in another project should be disclosed through that project's authorized security channel and should not be published before a reasonable coordinated-disclosure process.
+
+Public reports must remove credentials, private endpoints, proprietary prompts, personal data, and exploit details that would create unnecessary risk. Research notes should prefer the minimum evidence needed to reproduce and fix the issue.
+
+## Current reproducible evidence
+
+- [Adversarial MCP fixtures](../examples/adversarial/README.md)
+- [Evaluation record](EVALUATION.md)
+- [Threat model](THREAT_MODEL.md)
+- [Security policy](../SECURITY.md)
+
+The project welcomes verifiable pilot feedback, including false positives and false negatives, through the repository's Pilot feedback issue form. Popularity, branding, and unverifiable testimonials are not treated as security evidence.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trustdex",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "description": "A local-first trust, provenance, and review gate for AI agent tools, MCP servers, skills, and plugins.",
   "type": "module",
   "bin": {
@@ -8,7 +8,8 @@
   },
   "scripts": {
     "test": "node --test",
-    "check": "node --check bin/trustdex.mjs && node --check src/canonical.mjs && node --check src/codex-config.mjs && node --check src/extensions.mjs && node --check src/gate.mjs && node --check src/inspect.mjs && node --check src/policy.mjs && node --check src/policy-packs.mjs && node --check src/provenance.mjs && node --check src/provenance-online.mjs && node --check src/review.mjs && node --check src/snapshot.mjs && node --check src/trust-record.mjs",
+    "test:research": "node --test test/research-fixtures.test.mjs",
+    "check": "node --check bin/trustdex.mjs && node --check src/canonical.mjs && node --check src/claude-config.mjs && node --check src/codex-config.mjs && node --check src/extensions.mjs && node --check src/gate.mjs && node --check src/inspect.mjs && node --check src/policy.mjs && node --check src/policy-packs.mjs && node --check src/provenance.mjs && node --check src/provenance-online.mjs && node --check src/review.mjs && node --check src/snapshot.mjs && node --check src/trust-record.mjs",
     "prepublishOnly": "npm test && npm run check"
   },
   "engines": {

package/src/claude-config.mjs

@@ -0,0 +1,106 @@
+const SERVER_KEYS = {
+  stdio: new Set(['type', 'command', 'args', 'env']),
+  http: new Set(['type', 'url', 'headers', 'headersHelper']),
+  sse: new Set(['type', 'url', 'headers', 'headersHelper'])
+};
+const ENV_REFERENCE = /\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-[^}]*)?\}/g;
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function requireKeys(value, allowed, context) {
+  if (Object.keys(value).some((key) => !allowed.has(key))) {
+    throw new Error(`Unsupported ${context} field. Claude MCP inspection fails closed on unknown settings.`);
+  }
+}
+
+function environmentReferences(value) {
+  return [...new Set([...value.matchAll(ENV_REFERENCE)].map((match) => match[1]))].sort();
+}
+
+// Return inspection input only. Gating must preserve entries from the original
+// configuration, never these internal adapter annotations.
+export function parseClaudeMcpConfig(config) {
+  if (!isRecord(config) || !isRecord(config.mcpServers)) {
+    throw new Error('Expected a Claude MCP JSON object containing an mcpServers object.');
+  }
+  requireKeys(config, new Set(['mcpServers']), 'Claude MCP root');
+
+  const entries = Object.entries(config.mcpServers).map(([name, server]) => {
+    if (!/^[A-Za-z0-9_-]+$/.test(name) || ['__proto__', 'constructor', 'prototype'].includes(name)) {
+      throw new Error('Unsupported Claude MCP server name.');
+    }
+    if (!isRecord(server)) throw new Error('Each Claude MCP server must be an object.');
+    const type = server.type === undefined ? 'stdio' : server.type;
+    if (typeof type !== 'string' || !Object.hasOwn(SERVER_KEYS, type)) {
+      throw new Error('Unsupported Claude MCP transport. Supported: stdio, http, sse.');
+    }
+    requireKeys(server, SERVER_KEYS[type], 'Claude MCP server');
+    const signals = [];
+    const adapter = { runtime: 'claude-mcp-v1', transport: type };
+
+    if (type === 'stdio') {
+      if (typeof server.command !== 'string' || !server.command.trim()) {
+        throw new Error('Claude stdio MCP servers require a non-empty command.');
+      }
+      if (server.command.includes('${')) {
+        throw new Error('Claude command variable expansion is unsupported; use an explicit executable.');
+      }
+      if (server.args !== undefined && (!Array.isArray(server.args) || server.args.some((arg) => typeof arg !== 'string' || arg.includes('${')))) {
+        throw new Error('Claude MCP args must be strings without unresolved variable expansion.');
+      }
+      if (server.env !== undefined && (!isRecord(server.env) || Object.values(server.env).some((value) => typeof value !== 'string'))) {
+        throw new Error('Claude MCP env must contain string values.');
+      }
+      // Reference names are safe metadata; do not fingerprint env values or defaults.
+      adapter.envReferences = Object.fromEntries(Object.entries(server.env || {})
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([key, value]) => [key, environmentReferences(value)]));
+    } else {
+      if (typeof server.url !== 'string' || !server.url.trim() || server.url.includes('${')) {
+        throw new Error('Claude remote MCP servers require a literal HTTP(S) URL.');
+      }
+      let endpoint;
+      try { endpoint = new URL(server.url); } catch {
+        throw new Error('Invalid Claude MCP URL.');
+      }
+      if (!['https:', 'http:'].includes(endpoint.protocol)) {
+        throw new Error('Unsupported Claude MCP URL scheme.');
+      }
+      // The generic inspector fingerprints its input URL. Reject URL credentials
+      // and query/fragment values before they can enter that fingerprint.
+      if (endpoint.username || endpoint.password || endpoint.search || endpoint.hash) {
+        throw new Error('Claude MCP URL credentials, query parameters, and fragments are unsupported; use headers.');
+      }
+      if (server.headers !== undefined) {
+        if (!isRecord(server.headers) || Object.values(server.headers).some((value) => typeof value !== 'string')) {
+          throw new Error('Claude MCP headers must contain string values.');
+        }
+        adapter.headerNames = Object.keys(server.headers).sort();
+        adapter.headerReferences = Object.fromEntries(Object.entries(server.headers)
+          .sort(([a], [b]) => a.localeCompare(b))
+          .map(([key, value]) => [key, environmentReferences(value)]));
+        if (adapter.headerNames.length) {
+          const references = Object.values(adapter.headerReferences);
+          if (references.some((refs) => refs.length)) signals.push('env-http-headers');
+          if (references.some((refs) => !refs.length)) signals.push('static-http-headers');
+        }
+      }
+      if (server.headersHelper !== undefined) {
+        if (typeof server.headersHelper !== 'string' || !server.headersHelper.trim()) {
+          throw new Error('Claude MCP headersHelper must be a non-empty string.');
+        }
+        signals.push('header-helper-command');
+        adapter.hasHeadersHelper = true;
+      }
+    }
+
+    return [name, {
+      ...server,
+      _trustdexSignals: signals,
+      _trustdexFingerprintData: adapter
+    }];
+  });
+  return { mcpServers: Object.fromEntries(entries) };
+}