title: MCP Surface Lint emoji: 🔎 colorFrom: indigo colorTo: gray sdk: gradio sdk_version: 6.20.0 app_file: app.py pinned: false license: mit short_description: Find where an MCP tool surface lets a caller fail silently tags:

• mcp

• mcp-server

• developer-tools

• static-analysis

MCP Surface Lint

Static checks over an MCP tool surface. Every rule answers one question:

Could a caller do the wrong thing and get no error back?

A tool that crashes on bad input is fine. A tool that accepts bad input and returns something plausible is the expensive kind of broken, because neither the caller nor the person reading the transcript has any signal that it happened.

Paste a tools/list response, get back the specific places that can happen.

This app is also an MCP server, so an agent can lint an agent interface without going through the UI.

Using it as an MCP server

Launched with demo.launch(mcp_server=True). Point a client at:

https://<space-host>/gradio_api/mcp/sse

Two tools are published:

The UI event handlers are deliberately excluded with api_name=False. Without that, Gradio also publishes analyse, analyse_1, and explain as tools: a duplicate-name pair plus a handler taking a gr.State that cannot survive a tool call. This linter flags all three patterns, so shipping them would be a poor look.

Related MCP server: teeshield

The rules

Names are compared after crude stemming, because list_user_records and list_users_record are the same tool as far as a caller is concerned and raw token comparison misses that entirely.

What it found in its own surface

Pointed at its own published schema, the linter returns exactly one finding, and it is not in this repo:

[high] MCP007 lint_tool_surface: Schema declares properties but no 'required' list

Gradio's get_input_schema builds {"type": "object", "properties": {...}} and never emits a required array. The information is already there: the same parameter dicts it iterates carry parameter_has_default, and Gradio's own gradio skills command uses that field to mark a parameter required. The practical effect is that every Gradio MCP server publishes tools whose arguments all look optional, so a caller that omits a mandatory one produces a schema-valid call.

Reported upstream as gradio-app/gradio#13670.

Running locally

pip install -r requirements.txt
python app.py

Tests:

python -m pytest -q

Rules are only worth what their tests are worth, so there is also a mutation matrix. It neuters each rule in turn and records which tests fail. A rule with no failing test is either dead code or unguarded, and you cannot tell which without looking:

python mutation_check.py

It refuses to report anything unless the baseline suite is green first, and it disables bytecode caching, because every mutated file is the same length and CPython validates a cached .pyc on (mtime, size). Inside one second that pair does not change, so the interpreter happily re-imports the previous mutation's bytecode and the whole matrix reports the wrong rule's result.

License

MIT.