mcplint-cli 0.1.0__py3-none-any.whl

mcplint/core/rules/completeness_rules.py

@@ -0,0 +1,217 @@
+"""Rules that flag gaps in what a tool's description documents.
+
+`excessive-description-length`'s threshold is a module default; Phase 3's
+configuration loader overrides it via `mcplint.yaml` (`thresholds.max_description_characters`).
+"""
+
+from __future__ import annotations
+
+import re
+
+from mcplint.core.rules.base import Rule, RuleContext
+from mcplint.models.contracts import SourceLocation, ToolContract
+from mcplint.models.findings import Finding, Severity
+
+DEFAULT_MAX_DESCRIPTION_CHARACTERS = 800
+
+_RETURN_HINTS = re.compile(r"\b(returns?|returning|output|result|response)\b", re.IGNORECASE)
+_ERROR_HINTS = re.compile(
+    r"\b(error|fail|failure|exception|raise|raises|throws|invalid|not found)\b", re.IGNORECASE
+)
+_CONSTRAINT_KEYS = ("minimum", "maximum", "minLength", "maxLength", "pattern", "enum")
+_WELL_KNOWN_ACRONYMS = {
+    "ID",
+    "URL",
+    "URI",
+    "API",
+    "JSON",
+    "XML",
+    "HTTP",
+    "HTTPS",
+    "UUID",
+    "SQL",
+    "CSV",
+    "PDF",
+    "UTC",
+    "OK",
+}
+_ACRONYM_PATTERN = re.compile(r"\b[A-Z]{2,6}\b")
+
+
+class MissingReturnSemanticsRule(Rule):
+    id = "missing-return-semantics"
+    title = "Missing return semantics"
+    description = (
+        "Flags tools with no outputSchema whose description also never explains "
+        "what the tool returns."
+    )
+    default_severity = Severity.WARNING
+    tags = ("completeness",)
+
+    def check(self, tool: ToolContract, context: RuleContext) -> list[Finding]:
+        if tool.output_schema is not None:
+            return []
+        if tool.description and _RETURN_HINTS.search(tool.description):
+            return []
+        return [
+            Finding(
+                rule_id=self.id,
+                severity=self.default_severity,
+                message=f"Tool '{tool.name}' does not document what it returns.",
+                evidence="no outputSchema and no return-related wording in the description",
+                location=SourceLocation(tool_name=tool.name, json_path="$.outputSchema"),
+                remediation=(
+                    "Add an outputSchema, or describe the shape and meaning of the "
+                    "tool's return value in its description."
+                ),
+                confidence=0.6,
+            )
+        ]
+
+
+class UndocumentedErrorBehaviourRule(Rule):
+    id = "undocumented-error-behaviour"
+    title = "Undocumented error behaviour"
+    description = "Flags tools whose description never mentions failure or error conditions."
+    default_severity = Severity.INFO
+    tags = ("completeness",)
+
+    def check(self, tool: ToolContract, context: RuleContext) -> list[Finding]:
+        if not tool.description or not tool.description.strip():
+            return []
+        if _ERROR_HINTS.search(tool.description):
+            return []
+        return [
+            Finding(
+                rule_id=self.id,
+                severity=self.default_severity,
+                message=f"Tool '{tool.name}' does not document its error behaviour.",
+                evidence="no error/failure/exception wording found in the description",
+                location=SourceLocation(tool_name=tool.name, json_path="$.description"),
+                remediation=(
+                    "Document how the tool signals failure: what happens on an "
+                    "invalid input, a not-found lookup, or an internal error."
+                ),
+                confidence=0.5,
+            )
+        ]
+
+
+class UndocumentedRequiredConstraintRule(Rule):
+    id = "undocumented-required-constraint"
+    title = "Undocumented required-parameter constraint"
+    description = (
+        "Flags required parameters whose JSON Schema constraints (enum, min/max, "
+        "pattern, length) are not mentioned in the parameter description."
+    )
+    default_severity = Severity.WARNING
+    tags = ("completeness", "schema")
+
+    def check(self, tool: ToolContract, context: RuleContext) -> list[Finding]:
+        findings = []
+        for param in tool.parameters:
+            if not param.required or not param.description:
+                continue
+            description_lower = param.description.lower()
+            for key in _CONSTRAINT_KEYS:
+                if key not in param.json_schema:
+                    continue
+                value = param.json_schema[key]
+                if self._is_documented(value, description_lower):
+                    continue
+                findings.append(
+                    Finding(
+                        rule_id=self.id,
+                        severity=self.default_severity,
+                        message=(
+                            f"Parameter '{param.name}' on tool '{tool.name}' has a "
+                            f"'{key}' constraint not reflected in its description."
+                        ),
+                        evidence=f"schema {key}={value!r}, not mentioned in description",
+                        location=SourceLocation(
+                            tool_name=tool.name,
+                            json_path=f"$.inputSchema.properties.{param.name}.{key}",
+                        ),
+                        remediation=(
+                            f"Mention the '{key}' constraint ({value!r}) in the "
+                            f"description of '{param.name}'."
+                        ),
+                        confidence=0.6,
+                    )
+                )
+        return findings
+
+    @staticmethod
+    def _is_documented(value: object, description_lower: str) -> bool:
+        if isinstance(value, list):
+            return any(str(item).lower() in description_lower for item in value)
+        return str(value).lower() in description_lower
+
+
+class ExcessiveDescriptionLengthRule(Rule):
+    id = "excessive-description-length"
+    title = "Excessive description length"
+    description = (
+        f"Flags descriptions longer than {DEFAULT_MAX_DESCRIPTION_CHARACTERS} characters, "
+        "which risk burning context and burying the useful details."
+    )
+    default_severity = Severity.INFO
+    tags = ("description",)
+    max_characters = DEFAULT_MAX_DESCRIPTION_CHARACTERS
+
+    def check(self, tool: ToolContract, context: RuleContext) -> list[Finding]:
+        if not tool.description or len(tool.description) <= self.max_characters:
+            return []
+        return [
+            Finding(
+                rule_id=self.id,
+                severity=self.default_severity,
+                message=(
+                    f"Tool '{tool.name}' description is {len(tool.description)} characters, "
+                    f"over the {self.max_characters}-character guideline."
+                ),
+                evidence=f"description length: {len(tool.description)}",
+                location=SourceLocation(tool_name=tool.name, json_path="$.description"),
+                remediation=(
+                    "Trim the description to the essential behaviour, inputs, and distinctions."
+                ),
+                confidence=0.8,
+            )
+        ]
+
+
+class UndefinedDomainTermRule(Rule):
+    id = "undefined-domain-term"
+    title = "Undefined domain term"
+    description = (
+        "Flags acronyms or domain-specific terms used in a description without "
+        "being defined nearby, which an agent outside the domain may misread."
+    )
+    default_severity = Severity.INFO
+    tags = ("description",)
+
+    def check(self, tool: ToolContract, context: RuleContext) -> list[Finding]:
+        if not tool.description:
+            return []
+        findings = []
+        seen: set[str] = set()
+        for match in _ACRONYM_PATTERN.finditer(tool.description):
+            term = match.group(0)
+            if term in _WELL_KNOWN_ACRONYMS or term in seen:
+                continue
+            following = tool.description[match.end() : match.end() + 2]
+            if following.startswith(" (") or following.startswith("("):
+                continue
+            seen.add(term)
+            findings.append(
+                Finding(
+                    rule_id=self.id,
+                    severity=self.default_severity,
+                    message=f"Tool '{tool.name}' description uses undefined term '{term}'.",
+                    evidence=f"'{term}' appears without a nearby definition",
+                    location=SourceLocation(tool_name=tool.name, json_path="$.description"),
+                    remediation=f"Define '{term}' on first use, e.g. '{term} (...)'.",
+                    confidence=0.4,
+                )
+            )
+        return findings

mcplint/core/rules/description_rules.py

@@ -0,0 +1,110 @@
+"""Rules that judge a tool's top-level description text."""
+
+from __future__ import annotations
+
+import re
+
+from mcplint.core.rules.base import Rule, RuleContext
+from mcplint.models.contracts import SourceLocation, ToolContract
+from mcplint.models.findings import Finding, Severity
+
+MIN_DESCRIPTION_WORDS = 4
+
+
+def _normalize_words(text: str) -> list[str]:
+    cleaned = re.sub(r"[^a-z0-9\s]", " ", text.lower())
+    return [word for word in cleaned.split() if word]
+
+
+class MissingToolDescriptionRule(Rule):
+    id = "missing-tool-description"
+    title = "Missing tool description"
+    description = "Flags tools with no description or a whitespace-only description."
+    default_severity = Severity.ERROR
+    tags = ("description",)
+
+    def check(self, tool: ToolContract, context: RuleContext) -> list[Finding]:
+        if tool.description is not None and tool.description.strip():
+            return []
+        return [
+            Finding(
+                rule_id=self.id,
+                severity=self.default_severity,
+                message=f"Tool '{tool.name}' has no description.",
+                evidence="description is missing or blank",
+                location=SourceLocation(tool_name=tool.name, json_path="$.description"),
+                remediation=(
+                    "Add a description explaining what the tool does, its inputs, "
+                    "and when an agent should choose it over similar tools."
+                ),
+                confidence=1.0,
+            )
+        ]
+
+
+class DescriptionRepeatsNameRule(Rule):
+    id = "description-repeats-name"
+    title = "Description repeats the tool name"
+    description = (
+        "Flags descriptions that only restate the tool name in words, adding no "
+        "information beyond what the name already conveys."
+    )
+    default_severity = Severity.WARNING
+    tags = ("description",)
+
+    def check(self, tool: ToolContract, context: RuleContext) -> list[Finding]:
+        if not tool.description or not tool.description.strip():
+            return []
+        name_words = _normalize_words(tool.name.replace("_", " ").replace("-", " "))
+        description_words = _normalize_words(tool.description)
+        if description_words != name_words:
+            return []
+        return [
+            Finding(
+                rule_id=self.id,
+                severity=self.default_severity,
+                message=f"Tool '{tool.name}' description only restates its name.",
+                evidence=(
+                    f"description '{tool.description}' normalizes to the same words "
+                    "as the tool name"
+                ),
+                location=SourceLocation(tool_name=tool.name, json_path="$.description"),
+                remediation=(
+                    "Explain what the tool actually does: inputs, output shape, "
+                    "side effects, and when to prefer it over similar tools."
+                ),
+                confidence=0.9,
+            )
+        ]
+
+
+class VagueToolDescriptionRule(Rule):
+    id = "vague-tool-description"
+    title = "Vague tool description"
+    description = (
+        f"Flags descriptions shorter than {MIN_DESCRIPTION_WORDS} words as likely too "
+        "vague to disambiguate tool choice."
+    )
+    default_severity = Severity.WARNING
+    tags = ("description",)
+
+    def check(self, tool: ToolContract, context: RuleContext) -> list[Finding]:
+        if not tool.description or not tool.description.strip():
+            return []
+        words = _normalize_words(tool.description)
+        if len(words) >= MIN_DESCRIPTION_WORDS:
+            return []
+        return [
+            Finding(
+                rule_id=self.id,
+                severity=self.default_severity,
+                message=f"Tool '{tool.name}' description is very short ({len(words)} words).",
+                evidence=f"description: '{tool.description}'",
+                location=SourceLocation(tool_name=tool.name, json_path="$.description"),
+                remediation=(
+                    "Expand the description with the specific action, inputs, and "
+                    "when an agent should use this tool versus alternatives."
+                ),
+                confidence=0.7,
+            )
+        ]

mcplint/core/rules/safety_rules.py

@@ -0,0 +1,139 @@
+"""Rules that check a tool's name and annotations agree about how dangerous it is."""
+
+from __future__ import annotations
+
+import re
+
+from mcplint.core.rules.base import Rule, RuleContext
+from mcplint.models.contracts import SourceLocation, ToolContract
+from mcplint.models.findings import Finding, Severity
+
+READ_VERBS = frozenset({"get", "list", "search", "find", "fetch", "query", "view", "show", "read"})
+WRITE_VERBS = frozenset(
+    {
+        "create",
+        "update",
+        "delete",
+        "remove",
+        "set",
+        "add",
+        "modify",
+        "edit",
+        "insert",
+        "upsert",
+        "patch",
+    }
+)
+_DESTRUCTIVE_WARNING_HINTS = re.compile(
+    r"\b(permanent|permanently|irreversible|cannot be undone|cannot be reversed|destructive)\b",
+    re.IGNORECASE,
+)
+
+
+def first_word(name: str) -> str:
+    return re.split(r"[_\-]", name, maxsplit=1)[0].lower()
+
+
+class ToolNameActionConflictRule(Rule):
+    id = "tool-name-action-conflict"
+    title = "Tool name conflicts with its destructive annotation"
+    description = (
+        "Flags tools whose name reads as a read-only action (get/list/search/...) "
+        "but which are annotated as destructive."
+    )
+    default_severity = Severity.ERROR
+    tags = ("safety",)
+
+    def check(self, tool: ToolContract, context: RuleContext) -> list[Finding]:
+        if first_word(tool.name) not in READ_VERBS:
+            return []
+        if not tool.annotations.destructive_hint:
+            return []
+        return [
+            Finding(
+                rule_id=self.id,
+                severity=self.default_severity,
+                message=(
+                    f"Tool '{tool.name}' reads as a read-only action but is annotated destructive."
+                ),
+                evidence=(
+                    f"name starts with a read verb ('{first_word(tool.name)}') "
+                    "but annotations.destructiveHint is true"
+                ),
+                location=SourceLocation(
+                    tool_name=tool.name, json_path="$.annotations.destructiveHint"
+                ),
+                remediation=(
+                    "Rename the tool to reflect its real effect, or correct the "
+                    "destructive annotation if the tool is genuinely read-only."
+                ),
+                confidence=0.7,
+            )
+        ]
+
+
+class DestructiveToolWithoutWarningRule(Rule):
+    id = "destructive-tool-without-warning"
+    title = "Destructive tool without a warning"
+    description = (
+        "Flags tools annotated destructive whose description does not warn that "
+        "the action is permanent or irreversible."
+    )
+    default_severity = Severity.ERROR
+    tags = ("safety",)
+
+    def check(self, tool: ToolContract, context: RuleContext) -> list[Finding]:
+        if not tool.annotations.destructive_hint:
+            return []
+        if tool.description and _DESTRUCTIVE_WARNING_HINTS.search(tool.description):
+            return []
+        return [
+            Finding(
+                rule_id=self.id,
+                severity=self.default_severity,
+                message=f"Tool '{tool.name}' is destructive but its description has no warning.",
+                evidence="annotations.destructiveHint is true, no warning wording in description",
+                location=SourceLocation(tool_name=tool.name, json_path="$.description"),
+                remediation=(
+                    "State plainly that the action is permanent/irreversible and "
+                    "cannot be undone, so an agent hesitates before calling it."
+                ),
+                confidence=0.8,
+            )
+        ]
+
+
+class StateChangingToolMarkedReadOnlyRule(Rule):
+    id = "state-changing-tool-marked-read-only"
+    title = "State-changing tool marked read-only"
+    description = (
+        "Flags tools whose name reads as a mutation (create/update/delete/...) "
+        "but which are annotated readOnlyHint=true."
+    )
+    default_severity = Severity.ERROR
+    tags = ("safety",)
+
+    def check(self, tool: ToolContract, context: RuleContext) -> list[Finding]:
+        if first_word(tool.name) not in WRITE_VERBS:
+            return []
+        if tool.annotations.read_only_hint is not True:
+            return []
+        return [
+            Finding(
+                rule_id=self.id,
+                severity=self.default_severity,
+                message=f"Tool '{tool.name}' changes state but is annotated read-only.",
+                evidence=(
+                    f"name starts with a write verb ('{first_word(tool.name)}') "
+                    "but annotations.readOnlyHint is true"
+                ),
+                location=SourceLocation(
+                    tool_name=tool.name, json_path="$.annotations.readOnlyHint"
+                ),
+                remediation=(
+                    "Correct readOnlyHint to false for this tool, since agents may "
+                    "rely on it to decide whether a call is safe to retry or sandbox."
+                ),
+                confidence=0.8,
+            )
+        ]

mcplint/core/rules/schema_rules.py

@@ -0,0 +1,101 @@
+"""Rules that cross-check a tool's parameter descriptions against its JSON Schema."""
+
+from __future__ import annotations
+
+import re
+
+from mcplint.core.rules.base import Rule, RuleContext
+from mcplint.models.contracts import SourceLocation, ToolContract
+from mcplint.models.findings import Finding, Severity
+
+_NUMERIC_HINTS = re.compile(r"\b(number of|count of|quantity of|amount of)\b", re.IGNORECASE)
+_LIST_HINTS = re.compile(r"\b(list of|array of|comma-separated list of)\b", re.IGNORECASE)
+_BOOLEAN_HINTS = re.compile(r"\b(true or false|boolean flag|yes or no)\b", re.IGNORECASE)
+
+
+class MissingParameterDescriptionRule(Rule):
+    id = "missing-parameter-description"
+    title = "Missing parameter description"
+    description = "Flags input parameters with no description."
+    default_severity = Severity.WARNING
+    tags = ("schema",)
+
+    def check(self, tool: ToolContract, context: RuleContext) -> list[Finding]:
+        findings = []
+        for param in tool.parameters:
+            if param.description and param.description.strip():
+                continue
+            findings.append(
+                Finding(
+                    rule_id=self.id,
+                    severity=self.default_severity,
+                    message=f"Parameter '{param.name}' on tool '{tool.name}' has no description.",
+                    evidence="parameter description is missing or blank",
+                    location=SourceLocation(
+                        tool_name=tool.name, json_path=f"$.inputSchema.properties.{param.name}"
+                    ),
+                    remediation=(
+                        f"Document '{param.name}': its purpose, expected format, and any "
+                        "constraints not already captured by the schema."
+                    ),
+                    confidence=1.0,
+                )
+            )
+        return findings
+
+
+class SchemaDescriptionTypeConflictRule(Rule):
+    id = "schema-description-type-conflict"
+    title = "Description conflicts with parameter schema type"
+    description = (
+        "Flags parameters whose description implies a different JSON Schema type "
+        "than the one declared (e.g. 'number of X' on a string-typed parameter)."
+    )
+    default_severity = Severity.ERROR
+    tags = ("schema",)
+
+    def check(self, tool: ToolContract, context: RuleContext) -> list[Finding]:
+        findings = []
+        for param in tool.parameters:
+            if not param.description or not param.description.strip():
+                continue
+            declared_type = param.json_schema.get("type")
+            conflict = self._detect_conflict(param.description, declared_type)
+            if conflict is None:
+                continue
+            expected_type, hint = conflict
+            findings.append(
+                Finding(
+                    rule_id=self.id,
+                    severity=self.default_severity,
+                    message=(
+                        f"Parameter '{param.name}' on tool '{tool.name}' reads as "
+                        f"{expected_type!r} but the schema declares type {declared_type!r}."
+                    ),
+                    evidence=(
+                        f"description matched pattern '{hint}', schema type is {declared_type!r}"
+                    ),
+                    location=SourceLocation(
+                        tool_name=tool.name, json_path=f"$.inputSchema.properties.{param.name}.type"
+                    ),
+                    remediation=(
+                        f"Either change the schema type to {expected_type!r} or rewrite the "
+                        "description so it matches the declared type."
+                    ),
+                    confidence=0.6,
+                )
+            )
+        return findings
+
+    @staticmethod
+    def _detect_conflict(description: str, declared_type: object) -> tuple[str, str] | None:
+        numeric_match = _NUMERIC_HINTS.search(description)
+        if numeric_match and declared_type not in ("integer", "number"):
+            return "integer", numeric_match.group(0)
+        list_match = _LIST_HINTS.search(description)
+        if list_match and declared_type != "array":
+            return "array", list_match.group(0)
+        boolean_match = _BOOLEAN_HINTS.search(description)
+        if boolean_match and declared_type != "boolean":
+            return "boolean", boolean_match.group(0)
+        return None