[BUG] Misleading error message in /doctor when project-level .mcp.json doesn't exist

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

see below

What Should Happen?

see below

Error Messages/Logs

Steps to Reproduce

see below

Claude Model

None

Is this a regression?

Yes, this worked in a previous version

Last Working Version

_No response_

Claude Code Version

2.0.76

Platform

Anthropic API

Operating System

Other Linux

Terminal/Shell

Other

Additional Information

Description

The main window shows a confusing error message

ˋˋˋ
Found 1 invalid settings file · /doctor for details
ˋˋˋ
when the project-level .mcp.json file doesn't exist, even though:

1. The file is optional (project-level config is not required)
2. MCP servers still work correctly via user-level config
3. The error message is factually incorrect ("file does not exist" ≠ "does not adhere to schema")

---
Environment

Claude Code version: 2.0.76
Install method: npm-global (global)
Platform: Linux (Termux on Android)
Path: /data/data/com.termux/files/usr/bin/node
Invoked via: /data/data/com.termux/files/usr/bin/claude

---
User Configuration (Working)

User-level config: ~/.claude.json

MCP servers are configured and functioning correctly at user level. No project-level .mcp.json exists because it's not needed.

---
Reproduction

Run /doctor command.

---
Current Output

MCP Config Diagnostics

For help configuring MCP servers, see: https://code.claude.com/docs/en/mcp

[Failed to parse] Project config (shared via .mcp.json)
Location: /data/data/com.termux/files/home/.mcp.json
└ [Error] mcpServers: Does not adhere to MCP server configuration schema

Problem: The file at /data/data/com.termux/files/home/.mcp.json simply doesn't exist. There is no schema validation failure - the file doesn't exist at all.

---
Expected Behavior

The /doctor output should either:

1. Not show any error/warning when the file simply doesn't exist (file is optional)
2. Or show an informational message like:

Project config: /path/to/.mcp.json (not found - this is optional)

1. Never show "Does not adhere to schema" for a non-existent file

---
Impact

• No functional impact: MCP servers load and work correctly via user-level config
• UX confusion: Users may think their MCP configuration is broken when it's not
• Misleading error: The "Does not adhere to schema" error is factually wrong - the file doesn't exist, so schema validation never ran

---
Workaround

Creating an empty .mcp.json suppresses the error:

echo '{}' > .mcp.json

But this shouldn't be required for users who don't need project-level MCP configuration.

---
Suggested Fix

In the diagnostic code, distinguish between:

1. File doesn't exist → Show info-level message or no message (config is optional)
2. File exists but invalid JSON → Show error with actual parse error
3. File exists but invalid schema → Show error with schema violation details

---
Additional Notes

Per the documentation, project-level .mcp.json is optional. User-level config (~/.claude.json) should be sufficient for most users. The current behavior incorrectly implies something is broken when it's not.