mcp-medic 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shivam039
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,169 @@
+# mcp-doctor
+
+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.
+
+---
+
+## 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-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`.
+- 📸 **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>`.
+- ⚡ **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.
+- 🚦 **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.
+
+---
+
+## Quick Start
+
+```bash
+# Run against auto-discovered configs in current project / Claude Desktop
+npx mcp-doctor
+
+# Run check on a specific configuration file
+npx mcp-doctor check path/to/config.json
+
+# Validate all configs across a monorepo
+npx mcp-doctor check-all "configs/**/*.json"
+
+# Compare two configs to detect drift
+npx mcp-doctor 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
+
+# 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
+
+# Display suggested fixes for flagged diagnostics
+npx mcp-doctor check path/to/config.json --show-fixes
+
+# Watch mode (re-runs checks on save)
+npx mcp-doctor watch path/to/config.json
+```
+
+---
+
+## CLI Options
+
+| Command / Flag | Description |
+|---|---|
+| `[check] [path]` | Check target configuration (or auto-discover if path is omitted) |
+| `check-all "<glob>"` | Validate all matching configuration files in fleet |
+| `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 |
+| `--config <path>` | Explicit configuration path |
+| `--policy <path>` | Apply organizational policy rules (`.mcp-doctor-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 |
+| `--export-json <file>` | Export report in JSON format |
+| `--show-fixes` | Show suggested fixes inline under diagnostics |
+| `--fail-on <severity>` | Fail with exit code 1 on `error` (default) or `warning` |
+| `--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`) |
+
+### Exit Codes
+
+- **`0`**: All checks passed cleanly.
+- **`1`**: Diagnostic failure (one or more errors, or warnings if `--fail-on warning` is set).
+- **`2`**: Configuration or usage error (missing file, JSON parse error, invalid options).
+
+---
+
+## Policy-as-Code (`.mcp-doctor-policy.json`)
+
+Define organization-wide policies that compose with built-in checks:
+
+```json
+{
+  "bannedTransports": ["stdio"],
+  "allowedDomains": ["corp.internal", "mcp.example.com"],
+  "minDescriptionLength": 20
+}
+```
+
+---
+
+## VS Code Extension
+
+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.
+
+---
+
+## GitHub Action
+
+Add MCP config validation to your PR workflow:
+
+```yaml
+name: Validate MCP Configs
+on: [push, pull_request]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: shivam039/mcp-doctor@main
+        with:
+          config-path: './.mcp.json'
+          fail-on: 'error'
+          show-fixes: 'true'
+```
+
+---
+
+## Check Ecosystem Directory
+
+| 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 |
+
+To write and publish your own check plugin, see [Authoring Custom Checks](./docs/AUTHORING_CHECKS.md).
+
+---
+
+## Governance, Stability & Security
+
+- 🏛️ [Governance & Project Sustainability](./GOVERNANCE.md)
+- 📜 [1.0 Stability & Deprecation Policy](./docs/STABILITY_POLICY.md)
+- 🔒 [Security Policy & Threat Model](./SECURITY.md)
+- 💡 [RFC Process](./docs/RFC_PROCESS.md)
+
+---
+
+## Development
+
+```bash
+npm install
+npm run build
+npm run typecheck
+npm run test
+```
+
+## License
+
+MIT

package/action.yml

@@ -0,0 +1,57 @@
+name: 'mcp-doctor-action'
+description: 'Diagnose broken MCP (Model Context Protocol) server configs in CI before they break your agent silently'
+author: 'mcp-doctor'
+branding:
+  icon: 'check-circle'
+  color: 'green'
+
+inputs:
+  config-path:
+    description: 'Path to MCP configuration file (defaults to auto-discovery)'
+    required: false
+    default: ''
+  fail-on:
+    description: 'Failure threshold: "error" (default) or "warning"'
+    required: false
+    default: 'error'
+  show-fixes:
+    description: 'Display actionable fix suggestions under diagnostics'
+    required: false
+    default: 'true'
+  timeout:
+    description: 'Handshake timeout per server in milliseconds'
+    required: false
+    default: '5000'
+  verbose:
+    description: 'Output raw JSON-RPC traffic for debugging'
+    required: false
+    default: 'false'
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Set up Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '20'
+
+    - name: Run mcp-doctor
+      shell: bash
+      run: |
+        ARGS="check"
+        if [ -n "${{ inputs.config-path }}" ]; then
+          ARGS="$ARGS ${{ inputs.config-path }}"
+        fi
+        if [ "${{ inputs.show-fixes }}" = "true" ]; then
+          ARGS="$ARGS --show-fixes"
+        fi
+        if [ -n "${{ inputs.fail-on }}" ]; then
+          ARGS="$ARGS --fail-on ${{ inputs.fail-on }}"
+        fi
+        if [ -n "${{ inputs.timeout }}" ]; then
+          ARGS="$ARGS --timeout ${{ inputs.timeout }}"
+        fi
+        if [ "${{ inputs.verbose }}" = "true" ]; then
+          ARGS="$ARGS --verbose"
+        fi
+        npx --yes mcp-doctor $ARGS

package/dist/checks/index.d.ts

@@ -0,0 +1,6 @@
+export { malformedSchemaCheck } from './malformed-schema.js';
+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 declare const allChecks: import("../types.js").Check[];

package/dist/checks/index.js

@@ -0,0 +1,17 @@
+export { malformedSchemaCheck } from './malformed-schema.js';
+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';
+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';
+export const allChecks = [
+    malformedSchemaCheck,
+    missingRequiredFieldsCheck,
+    typeMismatchCheck,
+    missingDescriptionCheck,
+    sampleCallSimulationCheck,
+];

package/dist/checks/malformed-schema.d.ts

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

package/dist/checks/malformed-schema.js

@@ -0,0 +1,63 @@
+export const malformedSchemaCheck = {
+    id: 'schema.malformed',
+    description: 'Flags tools whose inputSchema is not a valid JSON Schema object.',
+    run(connection) {
+        const results = [];
+        try {
+            if (!connection.tools || !Array.isArray(connection.tools)) {
+                return results;
+            }
+            for (const tool of connection.tools) {
+                const schema = tool.inputSchema;
+                // Check if inputSchema is an object and not null / array / primitive
+                if (schema === null || typeof schema !== 'object' || Array.isArray(schema)) {
+                    const actualType = schema === null ? 'null' : Array.isArray(schema) ? 'array' : typeof schema;
+                    results.push({
+                        checkId: 'schema.malformed',
+                        severity: 'error',
+                        message: `Tool "${tool.name}" inputSchema must be a valid JSON Schema object, but got ${actualType}.`,
+                        serverName: connection.server.name,
+                        toolName: tool.name,
+                        details: { actualType, inputSchema: schema },
+                        suggestedFix: {
+                            description: 'Replace inputSchema with a valid JSON Schema object, e.g. { "type": "object", "properties": {} }.',
+                        },
+                    });
+                    continue;
+                }
+                // Schema is an object: verify it has 'type' or a combinator / ref
+                const schemaObj = schema;
+                const hasType = typeof schemaObj.type === 'string' || Array.isArray(schemaObj.type);
+                const hasCombinatorOrRef = Boolean(schemaObj.$ref) ||
+                    Boolean(schemaObj.oneOf) ||
+                    Boolean(schemaObj.anyOf) ||
+                    Boolean(schemaObj.allOf);
+                if (!hasType && !hasCombinatorOrRef) {
+                    const hasProperties = Boolean(schemaObj.properties);
+                    results.push({
+                        checkId: 'schema.malformed',
+                        severity: 'warning',
+                        message: hasProperties
+                            ? `Tool "${tool.name}" inputSchema is missing a "type" or combinator ("$ref", "oneOf", "anyOf", "allOf") field, but defines "properties".`
+                            : `Tool "${tool.name}" inputSchema is missing a "type" or combinator ("$ref", "oneOf", "anyOf", "allOf") field.`,
+                        serverName: connection.server.name,
+                        toolName: tool.name,
+                        details: { inputSchema: schema },
+                        suggestedFix: {
+                            description: 'Add `"type": "object"` to the inputSchema.',
+                        },
+                    });
+                }
+            }
+        }
+        catch (err) {
+            results.push({
+                checkId: 'schema.malformed',
+                severity: 'error',
+                message: `check failed internally: ${err instanceof Error ? err.message : String(err)}`,
+                serverName: connection.server.name,
+            });
+        }
+        return results;
+    },
+};

package/dist/checks/missing-description.d.ts

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

package/dist/checks/missing-description.js

@@ -0,0 +1,71 @@
+export const missingDescriptionCheck = {
+    id: 'schema.missing-description',
+    description: 'Flags tools and tool properties that are missing descriptions.',
+    run(connection) {
+        const results = [];
+        try {
+            if (!connection.tools || !Array.isArray(connection.tools)) {
+                return results;
+            }
+            for (const tool of connection.tools) {
+                // Check top-level tool description
+                if (tool.description === undefined ||
+                    typeof tool.description !== 'string' ||
+                    tool.description.trim() === '') {
+                    results.push({
+                        checkId: 'schema.missing-description',
+                        severity: 'warning',
+                        message: `Tool "${tool.name}" is missing a description.`,
+                        serverName: connection.server.name,
+                        toolName: tool.name,
+                        suggestedFix: {
+                            description: `Add a "description" field to tool "${tool.name}" explaining what the tool does.`,
+                        },
+                    });
+                }
+                // Check property descriptions in inputSchema
+                const schema = tool.inputSchema;
+                if (!schema || typeof schema !== 'object' || Array.isArray(schema)) {
+                    continue;
+                }
+                const schemaObj = schema;
+                if (!schemaObj.properties ||
+                    typeof schemaObj.properties !== 'object' ||
+                    Array.isArray(schemaObj.properties)) {
+                    continue;
+                }
+                const properties = schemaObj.properties;
+                for (const [propName, propDef] of Object.entries(properties)) {
+                    if (!propDef || typeof propDef !== 'object' || Array.isArray(propDef)) {
+                        continue;
+                    }
+                    const propObj = propDef;
+                    if (propObj.description === undefined ||
+                        typeof propObj.description !== 'string' ||
+                        propObj.description.trim() === '') {
+                        results.push({
+                            checkId: 'schema.missing-description',
+                            severity: 'info',
+                            message: `Property "${propName}" in tool "${tool.name}" is missing a description.`,
+                            serverName: connection.server.name,
+                            toolName: tool.name,
+                            details: { property: propName },
+                            suggestedFix: {
+                                description: `Add a "description" field to property "${propName}" in tool "${tool.name}".`,
+                            },
+                        });
+                    }
+                }
+            }
+        }
+        catch (err) {
+            results.push({
+                checkId: 'schema.missing-description',
+                severity: 'error',
+                message: `check failed internally: ${err instanceof Error ? err.message : String(err)}`,
+                serverName: connection.server.name,
+            });
+        }
+        return results;
+    },
+};

package/dist/checks/missing-required-fields.d.ts

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

package/dist/checks/missing-required-fields.js

@@ -0,0 +1,55 @@
+export const missingRequiredFieldsCheck = {
+    id: 'schema.missing-required',
+    description: 'Flags required fields listed in inputSchema.required that are not defined in inputSchema.properties.',
+    run(connection) {
+        const results = [];
+        try {
+            if (!connection.tools || !Array.isArray(connection.tools)) {
+                return results;
+            }
+            for (const tool of connection.tools) {
+                const schema = tool.inputSchema;
+                if (!schema || typeof schema !== 'object' || Array.isArray(schema)) {
+                    continue;
+                }
+                const schemaObj = schema;
+                if (!Array.isArray(schemaObj.required)) {
+                    continue;
+                }
+                const properties = schemaObj.properties &&
+                    typeof schemaObj.properties === 'object' &&
+                    !Array.isArray(schemaObj.properties)
+                    ? schemaObj.properties
+                    : {};
+                for (const reqField of schemaObj.required) {
+                    if (typeof reqField === 'string' && !(reqField in properties)) {
+                        results.push({
+                            checkId: 'schema.missing-required',
+                            severity: 'error',
+                            message: `Tool "${tool.name}" lists required field "${reqField}", but it is not defined in "properties".`,
+                            serverName: connection.server.name,
+                            toolName: tool.name,
+                            details: {
+                                missingField: reqField,
+                                required: schemaObj.required,
+                                definedProperties: Object.keys(properties),
+                            },
+                            suggestedFix: {
+                                description: `Define property "${reqField}" under inputSchema.properties, or remove "${reqField}" from inputSchema.required.`,
+                            },
+                        });
+                    }
+                }
+            }
+        }
+        catch (err) {
+            results.push({
+                checkId: 'schema.missing-required',
+                severity: 'error',
+                message: `check failed internally: ${err instanceof Error ? err.message : String(err)}`,
+                serverName: connection.server.name,
+            });
+        }
+        return results;
+    },
+};

package/dist/checks/sample-call-simulation.d.ts

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