mcp-medic 1.0.0 → 1.0.2

package/README.md

@@ -1,27 +1,43 @@
-# mcp-doctor
+# mcp-medic
+
+[![CI](https://github.com/shivam039/mcp-doctor/actions/workflows/ci.yml/badge.svg)](https://github.com/shivam039/mcp-doctor/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/mcp-medic.svg)](https://www.npmjs.com/package/mcp-medic)
+[![license](https://img.shields.io/npm/l/mcp-medic.svg)](./LICENSE)
 
 Diagnose broken MCP (Model Context Protocol) server configs before they break your agent silently.
 
-`mcp-doctor` validates MCP server configurations, executes full protocol initialization handshakes across stdio/SSE/HTTP transports, checks all exposed tool JSON schemas against standard specifications, and simulates sample calls — providing actionable suggestions, in-editor VS Code diagnostics, fleet management, and CI-ready exit codes.
+`mcp-medic` validates MCP server configurations, executes full protocol initialization handshakes across stdio/SSE/HTTP transports, checks all exposed tool JSON schemas against standard specifications, and simulates sample calls — providing actionable suggestions and CI-ready exit codes.
+
+## Why this exists
+
+A broken MCP server config usually doesn't fail loudly — it fails as your agent silently missing a tool, retrying a handshake forever, or getting a malformed schema it can't reason about. Those bugs are miserable to track down after the fact. `mcp-medic` catches them at the config level, before an agent ever touches the server: it actually connects (real `initialize` handshake, real `tools/list`), so "the config parses" and "the server actually works" are checked together, in CI, with a real exit code.
+
+## ⚠️ How this works — please read before pointing it at a config
+
+`mcp-medic` validates a config by **actually connecting to the servers in it**:
+- `stdio` transport → it **spawns the configured `command`** as a real child process on your machine.
+- `sse`/`http` transport → it **makes real network requests** to the configured `url`, including any `headers` you've set (e.g. auth tokens).
+
+This is the whole point (a real handshake, not a schema guess) — but it means you should only run it against configs you trust, the same way you'd only `npm install` a `package.json` you trust. See [SECURITY.md](./SECURITY.md) for the full threat model.
 
 ---
 
 ## Features
 
-- 🔍 **Auto-Discovery**: Run `mcp-doctor check` with no arguments to auto-discover Claude Desktop, `.mcp.json`, and VS Code/Cursor MCP configuration paths across macOS, Windows, and Linux.
+- 🔍 **Auto-Discovery**: Run `mcp-medic check` with no arguments to auto-discover Claude Desktop, `.mcp.json`, and VS Code/Cursor MCP configuration paths across macOS, Windows, and Linux.
 - 💡 **Auto-Fix Suggestions**: Diagnose issues with clear, actionable fix suggestions using `--show-fixes`.
-- 🌐 **Registry Validation**: Validate published registry entries directly using `mcp-doctor check --registry <server-id>`.
-- 🏢 **Fleet Validation**: Scan and validate monorepos or multi-team configurations with `mcp-doctor check-all "<glob>"`.
-- ⚖️ **Drift Detection**: Catch environment divergence between staging and production configs with `mcp-doctor diff <configA> <configB>`.
-- 📜 **Policy-as-Code**: Enforce organizational constraints (e.g., banned transports, domain allowlists, minimum description lengths) via `.mcp-doctor-policy.json` / `--policy`.
+- 🌐 **Registry Validation**: Validate published registry entries directly using `mcp-medic check --registry <server-id>`.
+- 🧪 **Fleet Validation** (experimental): Scan and validate monorepos or multi-team configurations with `mcp-medic check-all "<glob>"`.
+- 🧪 **Drift Detection** (experimental): Catch environment divergence between staging and production configs with `mcp-medic diff <configA> <configB>`.
+- 📜 **Policy-as-Code**: Enforce organizational constraints (e.g., banned transports, domain allowlists, minimum description lengths) via `.mcp-medic-policy.json` / `--policy`.
 - 📸 **Snapshot Baseline Mode**: Filter out legacy diagnostics with `--snapshot <baseline.json>` to gate only on newly introduced regressions.
 - 📊 **CI Reporting**: Export standard JUnit XML (`--export-junit <file.xml>`) and JSON (`--export-json <file.json>`) for seamless CI dashboard visualization.
-- 👀 **Watch Mode**: Re-run validation on save using `mcp-doctor watch <path>`.
+- 👀 **Watch Mode**: Re-run validation on save using `mcp-medic watch <path>`.
 - ⚡ **Transport Hardening**: Full handshake validation across stdio, HTTP (with OAuth token refresh), and SSE (with automatic retry resilience).
-- 💻 **VS Code Extension**: In-editor squiggles and hover tooltips showing diagnostics and suggested fixes.
+- 🧪 **VS Code Extension** (experimental, not yet on the Marketplace): in-editor squiggles and hover tooltips — runnable from source today, see [vscode-extension/](./vscode-extension/).
 - 🚦 **CI Usability & Exit Codes**: Strict exit code taxonomy (`0` clean, `1` diagnostic failures, `2` usage/syntax errors) and `--fail-on <error|warning>`.
-- 🤖 **GitHub Action**: Drop-in CI integration via `shivam039/mcp-doctor@main` (or `mcp-doctor-action`).
-- 🧩 **Community Checks**: Conformance test helper (`runCheckConformanceSuite`) to build custom `mcp-doctor-check-*` check plugins.
+- 🤖 **GitHub Action**: Drop-in CI integration via `shivam039/mcp-doctor@main` (or `mcp-medic-action`).
+- 🧩 **Community Checks** (framework ready, no packages published yet): a conformance test helper (`runCheckConformanceSuite`) so anyone can build and publish their own `mcp-medic-check-*` plugin.
 
 ---
 
@@ -29,29 +45,29 @@ Diagnose broken MCP (Model Context Protocol) server configs before they break yo
 
 ```bash
 # Run against auto-discovered configs in current project / Claude Desktop
-npx mcp-doctor
+npx mcp-medic
 
 # Run check on a specific configuration file
-npx mcp-doctor check path/to/config.json
+npx mcp-medic check path/to/config.json
 
 # Validate all configs across a monorepo
-npx mcp-doctor check-all "configs/**/*.json"
+npx mcp-medic check-all "configs/**/*.json"
 
 # Compare two configs to detect drift
-npx mcp-doctor diff staging.mcp.json prod.mcp.json
+npx mcp-medic diff staging.mcp.json prod.mcp.json
 
 # Validate a published registry server directly without a local config
-npx mcp-doctor check --registry @modelcontextprotocol/server-memory
-npx mcp-doctor check --registry smithery:username/my-server
+npx mcp-medic check --registry @modelcontextprotocol/server-memory
+npx mcp-medic check --registry smithery:username/my-server
 
 # Apply organizational policy rules and export to JUnit XML
-npx mcp-doctor check path/to/config.json --policy .mcp-doctor-policy.json --export-junit results.xml
+npx mcp-medic check path/to/config.json --policy .mcp-medic-policy.json --export-junit results.xml
 
 # Display suggested fixes for flagged diagnostics
-npx mcp-doctor check path/to/config.json --show-fixes
+npx mcp-medic check path/to/config.json --show-fixes
 
 # Watch mode (re-runs checks on save)
-npx mcp-doctor watch path/to/config.json
+npx mcp-medic watch path/to/config.json
 ```
 
 ---
@@ -65,8 +81,9 @@ npx mcp-doctor watch path/to/config.json
 | `diff <configA> <configB>` | Detect drift between two configuration files |
 | `check --registry <id>` | Validate a published registry server directly |
 | `watch <path>` | Watch configuration file and re-run checks on file save |
+| `fix <path>` | Interactively apply mechanical suggested fixes (see [Auto-Fix](#auto-fix-mcp-medic-fix) below) |
 | `--config <path>` | Explicit configuration path |
-| `--policy <path>` | Apply organizational policy rules (`.mcp-doctor-policy.json`) |
+| `--policy <path>` | Apply organizational policy rules (`.mcp-medic-policy.json`) |
 | `--snapshot <path>` | Compare against baseline snapshot, reporting regressions only |
 | `--update-snapshot <path>` | Save diagnostic report as new baseline snapshot |
 | `--export-junit <file>` | Export report in JUnit XML format |
@@ -76,6 +93,8 @@ npx mcp-doctor watch path/to/config.json
 | `--verbose`, `-v` | Output raw JSON-RPC traffic and debug messages |
 | `--json` | Output full diagnostic report in JSON |
 | `--timeout <ms>` | Per-server handshake timeout in milliseconds (default: `5000`) |
+| `--help`, `-h` | Show usage help |
+| `--version`, `-V` | Print the installed version |
 
 ### Exit Codes
 
@@ -85,7 +104,27 @@ npx mcp-doctor watch path/to/config.json
 
 ---
 
-## Policy-as-Code (`.mcp-doctor-policy.json`)
+## Auto-Fix (`mcp-medic fix`)
+
+For the small subset of diagnostics that carry a mechanical fix (today: upgrading a `security.untrusted-remote` server's `http://` URL to `https://`), `mcp-medic fix` will show you a diff and ask for confirmation before touching your config file:
+
+```bash
+mcp-medic fix path/to/config.json
+
+# Preview every available fix without prompting or writing anything
+mcp-medic fix path/to/config.json --dry-run
+
+# Only offer fixes from one specific check
+mcp-medic fix path/to/config.json --check security.untrusted-remote
+```
+
+- Fixes are **never bulk-applied** — each one is shown as a diff and requires an explicit `y`/`N`.
+- A `.bak` copy of the original file is written before any change, unconditionally.
+- Most diagnostics (schema issues, the two other security checks) don't have a mechanical fix — `fix` reports "No auto-fixable diagnostics found" for those rather than guessing.
+
+---
+
+## Policy-as-Code (`.mcp-medic-policy.json`)
 
 Define organization-wide policies that compose with built-in checks:
 
@@ -99,11 +138,9 @@ Define organization-wide policies that compose with built-in checks:
 
 ---
 
-## VS Code Extension
+## VS Code Extension (experimental)
 
-The `mcp-doctor` VS Code extension provides:
-- Inline squiggles on `.mcp.json`, `mcp.json`, and `claude_desktop_config.json` files as you edit.
-- Hover tooltips showing the full diagnostic explanation and actionable suggested fix.
+**Not published on the VS Code Marketplace yet.** The diagnostics logic (inline squiggles + hover tooltips on `.mcp.json`, `mcp.json`, and `claude_desktop_config.json` files) is real and working, but it's currently only runnable from source as an Extension Development Host, or packaged locally as a `.vsix`. See [vscode-extension/README.md](./vscode-extension/README.md) for setup — it takes about five minutes.
 
 ---
 
@@ -133,25 +170,47 @@ jobs:
 
 | Check ID | Package | Scope | Description |
 |---|---|---|---|
-| `schema.malformed` | `mcp-doctor` | **Official** | Verifies inputSchema is a valid JSON schema object |
-| `schema.missing-required` | `mcp-doctor` | **Official** | Flags required fields missing from properties |
-| `schema.type-mismatch` | `mcp-doctor` | **Official** | Flags invalid JSON schema types and enum mismatches |
-| `schema.missing-description` | `mcp-doctor` | **Official** | Flags tools and properties missing documentation |
-| `schema.sample-call-simulation` | `mcp-doctor` | **Official** | Simulates and validates synthetic call payloads |
-| `policy.*` | `mcp-doctor` | **Official** | Evaluates policy-as-code rules (transports, domains, length) |
-| `community.strict-typing` | `mcp-doctor-check-strict-typing` | *Community* | Enforces strict property type annotations |
-| `community.no-empty-enums` | `mcp-doctor-check-no-empty-enums` | *Community* | Ensures non-empty enum option lists |
+| `schema.malformed` | `mcp-medic` | **Official** | Verifies inputSchema is a valid JSON schema object |
+| `schema.missing-required` | `mcp-medic` | **Official** | Flags required fields missing from properties |
+| `schema.type-mismatch` | `mcp-medic` | **Official** | Flags invalid JSON schema types and enum mismatches |
+| `schema.missing-description` | `mcp-medic` | **Official** | Flags tools and properties missing documentation |
+| `schema.sample-call-simulation` | `mcp-medic` | **Official** | Simulates and validates synthetic call payloads |
+| `security.untrusted-remote` | `mcp-medic` | **Official** (heuristic) | Flags non-HTTPS or raw-IP SSE/HTTP server URLs |
+| `security.overbroad-permissions` | `mcp-medic` | **Official** (heuristic) | Flags tools with unscoped shell/filesystem/network parameters |
+| `security.prompt-injection-risk` | `mcp-medic` | **Official** (heuristic) | Flags instruction-like language in tool descriptions aimed at the model |
+| `policy.*` | `mcp-medic` | **Official** | Evaluates policy-as-code rules (transports, domains, length) |
+| `community.strict-typing` | `mcp-medic-check-strict-typing` | *Planned / example* | Would enforce strict property type annotations |
+| `community.no-empty-enums` | `mcp-medic-check-no-empty-enums` | *Planned / example* | Would ensure non-empty enum option lists |
+
+The two `community.*` rows above are examples of what a check plugin could look like — **those packages aren't published yet**. `runCheckConformanceSuite()` (used by the official checks' own tests) is the tool for validating a plugin conforms to the `Check` interface; see [Authoring Custom Checks](./docs/AUTHORING_CHECKS.md) if you want to build and publish one.
+
+The `security.*` checks are heuristic — they pattern-match on what a server *declares* (URLs, tool descriptions, schemas), not what it actually does at runtime. Every diagnostic they produce says so explicitly; they're a signal to investigate, not proof of a problem.
+
+---
 
-To write and publish your own check plugin, see [Authoring Custom Checks](./docs/AUTHORING_CHECKS.md).
+## Known Limitations
+
+- **Handshake timeout defaults to 5000ms** per server (`--timeout <ms>` to change it). A slow-starting stdio server or a server behind a slow network path can fail with `status: 'timeout'` even though it would eventually respond.
+- **`schema.sample-call-simulation`** builds synthetic payloads from a tool's declared JSON Schema and checks the schema is internally consistent (e.g. catches an empty `enum`, or conflicting `minimum`/`maximum`) — it does **not** actually invoke the tool, and it does not validate business logic, side effects, or whether the tool's real output matches its declared schema.
+- **`security.*` checks are heuristic pattern-matching**, not a security audit — see the note above. They can both miss real issues and flag benign configs (e.g. a legitimate local dev server on plain `http://`).
+- **Fleet commands (`check-all`, `diff`) are newer and less battle-tested** than `check`/`watch` — the core check pipeline they're built on is the same, but edge cases in glob matching or drift diffing are more likely.
+- **The VS Code extension and community check packages are not shipped/published** — see the sections above.
+- **First run via `npx`** pays a one-time cost to resolve and download the package; once installed (or on a warm npx cache), `--help`/`--version` return in well under 100ms.
 
 ---
 
+## Contributing & Support
+
+- 🐛 [Report a bug](https://github.com/shivam039/mcp-doctor/issues/new?template=bug_report.md) / 💡 [Request a feature](https://github.com/shivam039/mcp-doctor/issues/new?template=feature_request.md)
+- 📋 See [CONTRIBUTING.md](./CONTRIBUTING.md) before opening a PR
+- 📝 [CHANGELOG](./CHANGELOG.md)
+
 ## Governance, Stability & Security
 
 - 🏛️ [Governance & Project Sustainability](./GOVERNANCE.md)
-- 📜 [1.0 Stability & Deprecation Policy](./docs/STABILITY_POLICY.md)
+- 📜 [Stability & Deprecation Policy](./docs/STABILITY_POLICY.md) — v1.0's initial stable surface
 - 🔒 [Security Policy & Threat Model](./SECURITY.md)
-- 💡 [RFC Process](./docs/RFC_PROCESS.md)
+- 💡 [RFC Process](./docs/RFC_PROCESS.md) (for changes to the frozen 1.0 surface)
 
 ---
 
@@ -164,6 +223,9 @@ npm run typecheck
 npm run test
 ```
 
+The VS Code extension (`vscode-extension/`) is a separate, independently-installed package — see [vscode-extension/README.md](./vscode-extension/README.md).
+
 ## License
 
 MIT
+

package/action.yml

@@ -1,6 +1,6 @@
-name: 'mcp-doctor-action'
+name: 'mcp-medic-action'
 description: 'Diagnose broken MCP (Model Context Protocol) server configs in CI before they break your agent silently'
-author: 'mcp-doctor'
+author: 'Shivam Dixit'
 branding:
   icon: 'check-circle'
   color: 'green'
@@ -35,7 +35,7 @@ runs:
       with:
         node-version: '20'
 
-    - name: Run mcp-doctor
+    - name: Run mcp-medic
       shell: bash
       run: |
         ARGS="check"
@@ -54,4 +54,4 @@ runs:
         if [ "${{ inputs.verbose }}" = "true" ]; then
           ARGS="$ARGS --verbose"
         fi
-        npx --yes mcp-doctor $ARGS
+        npx --yes mcp-medic $ARGS

package/dist/checks/index.d.ts

@@ -3,4 +3,7 @@ export { missingRequiredFieldsCheck } from './missing-required-fields.js';
 export { typeMismatchCheck } from './type-mismatch.js';
 export { missingDescriptionCheck } from './missing-description.js';
 export { sampleCallSimulationCheck } from './sample-call-simulation.js';
+export { securityUntrustedRemoteCheck } from './security-untrusted-remote.js';
+export { securityOverbroadPermissionsCheck } from './security-overbroad-permissions.js';
+export { securityPromptInjectionRiskCheck } from './security-prompt-injection-risk.js';
 export declare const allChecks: import("../types.js").Check[];

package/dist/checks/index.js

@@ -3,15 +3,24 @@ export { missingRequiredFieldsCheck } from './missing-required-fields.js';
 export { typeMismatchCheck } from './type-mismatch.js';
 export { missingDescriptionCheck } from './missing-description.js';
 export { sampleCallSimulationCheck } from './sample-call-simulation.js';
+export { securityUntrustedRemoteCheck } from './security-untrusted-remote.js';
+export { securityOverbroadPermissionsCheck } from './security-overbroad-permissions.js';
+export { securityPromptInjectionRiskCheck } from './security-prompt-injection-risk.js';
 import { malformedSchemaCheck } from './malformed-schema.js';
 import { missingRequiredFieldsCheck } from './missing-required-fields.js';
 import { typeMismatchCheck } from './type-mismatch.js';
 import { missingDescriptionCheck } from './missing-description.js';
 import { sampleCallSimulationCheck } from './sample-call-simulation.js';
+import { securityUntrustedRemoteCheck } from './security-untrusted-remote.js';
+import { securityOverbroadPermissionsCheck } from './security-overbroad-permissions.js';
+import { securityPromptInjectionRiskCheck } from './security-prompt-injection-risk.js';
 export const allChecks = [
     malformedSchemaCheck,
     missingRequiredFieldsCheck,
     typeMismatchCheck,
     missingDescriptionCheck,
     sampleCallSimulationCheck,
+    securityUntrustedRemoteCheck,
+    securityOverbroadPermissionsCheck,
+    securityPromptInjectionRiskCheck,
 ];

package/dist/checks/security-overbroad-permissions.d.ts

@@ -0,0 +1,2 @@
+import type { Check } from '../types.js';
+export declare const securityOverbroadPermissionsCheck: Check;

package/dist/checks/security-overbroad-permissions.js

@@ -0,0 +1,117 @@
+import { HEURISTIC_DISCLAIMER } from './security-shared.js';
+// Ordered by specificity; matched against each top-level inputSchema property name.
+const PROPERTY_RULES = [
+    {
+        category: 'shell-command',
+        namePattern: /^(cmd|command|shell|bash|sh|exec|script|code)$/i,
+        hint: 'accepts an unconstrained shell/command string',
+    },
+    {
+        category: 'filesystem-path',
+        namePattern: /^(path|filepath|file_path|dir|directory|folder)$/i,
+        hint: 'accepts an unconstrained filesystem path',
+    },
+    {
+        category: 'network-request',
+        namePattern: /^(url|endpoint|host|target|uri)$/i,
+        hint: 'accepts an unconstrained network destination',
+    },
+];
+const DESCRIPTION_RULES = [
+    {
+        category: 'shell-command',
+        pattern: /\b(execute|executes|run|runs)\s+(any|arbitrary)\s+(shell|command|code)\b|\barbitrary\s+shell\s+command/i,
+        hint: 'description states it executes arbitrary shell commands or code',
+    },
+    {
+        category: 'filesystem-path',
+        pattern: /\bfull\s+filesystem\s+access\b|\baccess(?:es)?\s+(?:to\s+)?any\s+file\b|\b(?:read|write|delete)\s+any\s+file\b/i,
+        hint: 'description states it can access any file on the filesystem',
+    },
+    {
+        category: 'network-request',
+        pattern: /\b(unrestricted|arbitrary)\s+(network|http|url)\s+(access|request)\b/i,
+        hint: 'description states it allows unrestricted network access',
+    },
+];
+function isUnconstrainedString(propDef) {
+    if (!propDef || typeof propDef !== 'object' || Array.isArray(propDef))
+        return false;
+    const prop = propDef;
+    if (prop.type !== 'string')
+        return false;
+    if (Array.isArray(prop.enum) && prop.enum.length > 0)
+        return false;
+    if (typeof prop.pattern === 'string' && prop.pattern.length > 0)
+        return false;
+    return true;
+}
+function checkTool(tool, serverName) {
+    const results = [];
+    if (typeof tool.description === 'string') {
+        for (const rule of DESCRIPTION_RULES) {
+            if (rule.pattern.test(tool.description)) {
+                results.push({
+                    checkId: 'security.overbroad-permissions',
+                    severity: 'warning',
+                    message: `Tool "${tool.name}" ${rule.hint} — review before granting it broad access. (${HEURISTIC_DISCLAIMER})`,
+                    serverName,
+                    toolName: tool.name,
+                    details: { category: rule.category, source: 'description' },
+                    suggestedFix: {
+                        description: 'Confirm this scope is intentional after reviewing the server\'s source; prefer a server that exposes narrower, purpose-built tools instead of one broad tool.',
+                    },
+                });
+            }
+        }
+    }
+    const schema = tool.inputSchema;
+    if (schema && typeof schema === 'object' && !Array.isArray(schema)) {
+        const schemaObj = schema;
+        const properties = schemaObj.properties && typeof schemaObj.properties === 'object' && !Array.isArray(schemaObj.properties)
+            ? schemaObj.properties
+            : {};
+        for (const [propName, propDef] of Object.entries(properties)) {
+            if (!isUnconstrainedString(propDef))
+                continue;
+            const rule = PROPERTY_RULES.find((r) => r.namePattern.test(propName));
+            if (!rule)
+                continue;
+            results.push({
+                checkId: 'security.overbroad-permissions',
+                severity: 'warning',
+                message: `Tool "${tool.name}" parameter "${propName}" ${rule.hint} (no enum or pattern constraining it). (${HEURISTIC_DISCLAIMER})`,
+                serverName,
+                toolName: tool.name,
+                details: { category: rule.category, source: 'schema', property: propName },
+                suggestedFix: {
+                    description: `Constrain "${propName}" with an enum of allowed values or a validating pattern, or split it into narrower parameters, if you control this server.`,
+                },
+            });
+        }
+    }
+    return results;
+}
+export const securityOverbroadPermissionsCheck = {
+    id: 'security.overbroad-permissions',
+    description: `Flags tools whose description or schema implies unscoped filesystem/shell/network access (${HEURISTIC_DISCLAIMER}).`,
+    run(connection) {
+        const results = [];
+        try {
+            if (!connection.tools || !Array.isArray(connection.tools))
+                return results;
+            for (const tool of connection.tools) {
+                results.push(...checkTool(tool, connection.server.name));
+            }
+        }
+        catch (err) {
+            results.push({
+                checkId: 'security.overbroad-permissions',
+                severity: 'error',
+                message: `check failed internally: ${err instanceof Error ? err.message : String(err)}`,
+                serverName: connection.server.name,
+            });
+        }
+        return results;
+    },
+};

package/dist/checks/security-prompt-injection-risk.d.ts

@@ -0,0 +1,2 @@
+import type { Check } from '../types.js';
+export declare const securityPromptInjectionRiskCheck: Check;

package/dist/checks/security-prompt-injection-risk.js

@@ -0,0 +1,94 @@
+import { HEURISTIC_DISCLAIMER } from './security-shared.js';
+// Instruction-like language aimed at the model reading the tool description,
+// rather than at a human deciding whether to use the tool — a known MCP
+// supply-chain risk pattern (tool descriptions are injected into the
+// model's context).
+const INJECTION_PATTERNS = [
+    /\balways\s+call\s+this\s+(tool\s+)?first\b/i,
+    /\bignore\s+(all\s+)?(previous|prior|above)\s+instructions\b/i,
+    /\bdisregard\s+(the\s+)?(system\s+prompt|previous\s+instructions)\b/i,
+    /\bdo\s+not\s+(tell|inform)\s+the\s+user\b/i,
+    /\bnever\s+(mention|tell)\s+.*\bthe\s+user\b/i,
+    /\byou\s+must\s+(always|never)\s+\w/i,
+    /\bthis\s+is\s+a\s+system\s+(prompt|instruction)\b/i,
+    /\boverride\s+(your|any)\s+(previous|prior)\s+(instructions|guidelines)\b/i,
+    /\bact\s+as\s+(if\s+you\s+are|though\s+you\s+are)\b/i,
+];
+function findMatch(text) {
+    for (const pattern of INJECTION_PATTERNS) {
+        const match = pattern.exec(text);
+        if (match) {
+            return { pattern: pattern.source, snippet: match[0] };
+        }
+    }
+    return undefined;
+}
+export const securityPromptInjectionRiskCheck = {
+    id: 'security.prompt-injection-risk',
+    description: `Flags tool/parameter descriptions containing instruction-like language aimed at the model rather than a human (${HEURISTIC_DISCLAIMER}).`,
+    run(connection) {
+        const results = [];
+        try {
+            if (!connection.tools || !Array.isArray(connection.tools))
+                return results;
+            for (const tool of connection.tools) {
+                if (typeof tool.description === 'string') {
+                    const match = findMatch(tool.description);
+                    if (match) {
+                        results.push({
+                            checkId: 'security.prompt-injection-risk',
+                            severity: 'warning',
+                            message: `Tool "${tool.name}" description contains instruction-like language aimed at the model ` +
+                                `("${match.snippet}") rather than describing the tool to a human — a known MCP supply-chain ` +
+                                `risk pattern. (${HEURISTIC_DISCLAIMER})`,
+                            serverName: connection.server.name,
+                            toolName: tool.name,
+                            details: { source: 'description', matchedPattern: match.pattern, snippet: match.snippet },
+                            suggestedFix: {
+                                description: "Review this tool's description and the server's source before trusting it; rewrite or remove instruction-like language if you control this server.",
+                            },
+                        });
+                    }
+                }
+                const schema = tool.inputSchema;
+                if (schema && typeof schema === 'object' && !Array.isArray(schema)) {
+                    const properties = schema.properties;
+                    if (properties && typeof properties === 'object' && !Array.isArray(properties)) {
+                        for (const [propName, propDef] of Object.entries(properties)) {
+                            if (!propDef || typeof propDef !== 'object' || Array.isArray(propDef))
+                                continue;
+                            const description = propDef.description;
+                            if (typeof description !== 'string')
+                                continue;
+                            const match = findMatch(description);
+                            if (match) {
+                                results.push({
+                                    checkId: 'security.prompt-injection-risk',
+                                    severity: 'warning',
+                                    message: `Tool "${tool.name}" parameter "${propName}" description contains instruction-like language ` +
+                                        `aimed at the model ("${match.snippet}") rather than describing the parameter to a human. ` +
+                                        `(${HEURISTIC_DISCLAIMER})`,
+                                    serverName: connection.server.name,
+                                    toolName: tool.name,
+                                    details: { source: 'parameter-description', property: propName, matchedPattern: match.pattern, snippet: match.snippet },
+                                    suggestedFix: {
+                                        description: "Review this tool's description and the server's source before trusting it; rewrite or remove instruction-like language if you control this server.",
+                                    },
+                                });
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        catch (err) {
+            results.push({
+                checkId: 'security.prompt-injection-risk',
+                severity: 'error',
+                message: `check failed internally: ${err instanceof Error ? err.message : String(err)}`,
+                serverName: connection.server.name,
+            });
+        }
+        return results;
+    },
+};

package/dist/checks/security-shared.d.ts

@@ -0,0 +1,8 @@
+/**
+ * All security.* checks are heuristic pattern-matching over what a server
+ * *declares* (config URL, tool descriptions, tool schemas) — they cannot
+ * see what a server actually does. Every diagnostic they emit must say so
+ * (FR3-2.4): this is not a substitute for reading a third-party MCP
+ * server's source before trusting it.
+ */
+export declare const HEURISTIC_DISCLAIMER = "heuristic flag, not a guarantee \u2014 review this server's source before trusting it";

package/dist/checks/security-shared.js

@@ -0,0 +1,8 @@
+/**
+ * All security.* checks are heuristic pattern-matching over what a server
+ * *declares* (config URL, tool descriptions, tool schemas) — they cannot
+ * see what a server actually does. Every diagnostic they emit must say so
+ * (FR3-2.4): this is not a substitute for reading a third-party MCP
+ * server's source before trusting it.
+ */
+export const HEURISTIC_DISCLAIMER = "heuristic flag, not a guarantee — review this server's source before trusting it";

package/dist/checks/security-untrusted-remote.d.ts

@@ -0,0 +1,2 @@
+import type { Check } from '../types.js';
+export declare const securityUntrustedRemoteCheck: Check;

package/dist/checks/security-untrusted-remote.js

@@ -0,0 +1,71 @@
+import { HEURISTIC_DISCLAIMER } from './security-shared.js';
+function toHttps(url) {
+    return url.replace(/^http:\/\//i, 'https://');
+}
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', '::1']);
+function isIpLiteralHost(hostname) {
+    if (/^\d{1,3}(\.\d{1,3}){3}$/.test(hostname))
+        return true; // IPv4
+    if (hostname.includes(':') && /^[0-9a-fA-F:]+$/.test(hostname))
+        return true; // IPv6 (URL strips brackets)
+    return false;
+}
+export const securityUntrustedRemoteCheck = {
+    id: 'security.untrusted-remote',
+    description: `For SSE/HTTP servers, flags non-HTTPS URLs or raw IP-address hosts instead of domain names (${HEURISTIC_DISCLAIMER}).`,
+    run(connection) {
+        const results = [];
+        try {
+            const { server } = connection;
+            if (server.transport !== 'sse' && server.transport !== 'http')
+                return results;
+            if (typeof server.url !== 'string' || server.url.length === 0)
+                return results;
+            let parsed;
+            try {
+                parsed = new URL(server.url);
+            }
+            catch {
+                return results; // malformed URLs are the config-loader/protocol layer's concern, not this check's
+            }
+            if (parsed.protocol === 'http:') {
+                results.push({
+                    checkId: 'security.untrusted-remote',
+                    severity: 'warning',
+                    message: `Server "${server.name}" connects over unencrypted "http://"; requests, responses, and any headers ` +
+                        `(including auth tokens) travel in plaintext. Not blocking — legitimate local dev configs exist. ` +
+                        `(${HEURISTIC_DISCLAIMER})`,
+                    serverName: server.name,
+                    details: { url: server.url, reason: 'non-https' },
+                    suggestedFix: {
+                        description: `Switch to "${toHttps(server.url)}" if the server supports TLS.`,
+                        patch: { serverName: server.name, set: { url: toHttps(server.url) } },
+                    },
+                });
+            }
+            if (isIpLiteralHost(parsed.hostname) && !LOOPBACK_HOSTS.has(parsed.hostname)) {
+                results.push({
+                    checkId: 'security.untrusted-remote',
+                    severity: 'warning',
+                    message: `Server "${server.name}" points at a raw IP address ("${parsed.hostname}") instead of a domain name, ` +
+                        `making it hard to verify who actually operates the endpoint or notice if it changes hands. ` +
+                        `Not blocking — legitimate local dev configs exist. (${HEURISTIC_DISCLAIMER})`,
+                    serverName: server.name,
+                    details: { url: server.url, reason: 'ip-literal-host' },
+                    suggestedFix: {
+                        description: 'Point this server at a stable domain name you control or trust, if one is available.',
+                    },
+                });
+            }
+        }
+        catch (err) {
+            results.push({
+                checkId: 'security.untrusted-remote',
+                severity: 'error',
+                message: `check failed internally: ${err instanceof Error ? err.message : String(err)}`,
+                serverName: connection.server.name,
+            });
+        }
+        return results;
+    },
+};

package/dist/cli.d.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 export interface ParsedArgs {
-    command: 'check' | 'watch' | 'check-all' | 'diff' | 'help';
+    command: 'check' | 'watch' | 'check-all' | 'diff' | 'fix' | 'help' | 'version';
     configPath?: string;
     configPathB?: string;
     globPattern?: string;
@@ -15,6 +15,13 @@ export interface ParsedArgs {
     showFixes: boolean;
     verbose: boolean;
     failOn: 'error' | 'warning';
+    checkFilter?: string;
+    dryRun: boolean;
 }
+/** Prompts the user with `question` and resolves true for an explicit "y"/"yes" answer. */
+export type ConfirmFn = (question: string) => Promise<boolean>;
 export declare function parseArgs(argv: string[]): ParsedArgs;
-export declare function main(argv?: string[]): Promise<number>;
+export interface CliDeps {
+    confirm?: ConfirmFn;
+}
+export declare function main(argv?: string[], deps?: CliDeps): Promise<number>;