Check that the server is up and report its version.

Fetch one Flutter / Dart SDK / pub.dev documentation page as clean markdown.

Identifier forms (resolved in this order):

• "pub:dio" or "pub:dio:5.4.0" → pub.dev package (description + README)

• "dart:async.Future" → Dart SDK class (api.dart.dev)

• "material.AppBar" / "widgets.ListView" → Flutter class with explicit library

• "ListView" → exact match in the local search index, then a widgets/material fallback, then pub.dev as a last resort

Args: identifier: one of the forms above. topic: optional section filter (e.g. "methods", "properties", "examples", "constructors") — keeps only the matching section plus the class title/description; if no section matches, the full content is returned with a "note" listing the available section headings. max_tokens: rough token budget for the returned markdown (1 token ≈ 4 chars); longer output is cut at a line boundary with a trailing note.

Returns {"type", "identifier", "url", "title", "content", "truncated", "tokens", "source_tokens", "max_tokens", "cached"} — plus "truncation" (what was cut and why) whenever "truncated" is true, and an optional "note" — or {"error", "suggestion"} on failure.

Search Flutter and Dart SDK class names (plus enums/mixins/typedefs).

Ranks the local search index by name similarity (exact > prefix > substring

fuzzy). Use this to find the right identifier before calling flutter_docs.

Args: query: text to match against class names, e.g. "text field" or "ListView". limit: maximum number of results (default 8).

Returns {"query", "count", "results": [{name, library, kind, url, score}], "index_stale"} or {"error", "suggestion"} when the index is unavailable.

Fetch pub.dev package metadata plus its README as markdown.

Args: package_name: exact pub.dev package name (case-sensitive), e.g. "dio". version: optional specific version, e.g. "5.4.0" (default: latest). max_tokens: rough token budget for the returned README (1 token ≈ 4 chars); longer output is cut at a line boundary with a trailing note.

Returns {"name", "version", "description", "publisher", "likes", "pub_points", "url", "readme", "truncated", "tokens", "source_tokens", "max_tokens", "cached"} or {"error", "suggestion"} on failure. truncated is true when the README was cut, in which case a truncation block explains the cut and tokens / source_tokens give the returned / full-page estimates. publisher / likes / pub_points may be null when pub.dev does not report them.

Parse every @flutter_mcp mention in a text and resolve each one to its docs.

Mention grammar (identifier forms are the same flutter_docs accepts):

• "@flutter_mcp provider" pub.dev package, latest release

• "@flutter_mcp provider:^6.0.0" caret constraint

• "@flutter_mcp provider:6.1.5" exact published release

• "@flutter_mcp dio:>=5.0.0 <6.0.0" range, space separated

• "@flutter_mcp provider:latest" explicit latest

• "@flutter_mcp pub:dio" / "pub:dio:5.4.0"

• "@flutter_mcp material.AppBar" Flutter class, library given

• "@flutter_mcp dart:async.Future" Dart SDK class

• "@flutter_mcp Container" plain name

A version constraint is answered from pub.dev's own list of published releases: an exact pin is returned when published, a range resolves to the newest release that satisfies it (pre-releases are excluded unless the constraint asks for one), and the constraint that was requested is always reported next to the version that was resolved. A version that does not exist is reported as missing with the nearest published releases — never replaced by a different version.

Args: text: any text containing zero or more @flutter_mcp mentions. max_tokens: rough token budget for each mention's documentation payload (1 token ≈ 4 chars). Non-positive disables truncation.

Returns {"mentions": n, "max_tokens": ..., "results": [...]} with exactly one entry per mention, in document order. Each entry carries "mention" (as written), "type" (flutter_class | dart_class | pub_package | not_found | error), the resolved "identifier" and "version", and the docs payload ("content", "truncated", "tokens", "source_tokens", "max_tokens", plus "truncation" when something was cut). Failures are per-mention {"type": "not_found" | "error", "error", "suggestion"} — one bad mention never removes or duplicates another mention's entry.

Health check: search index state, cache stats, and live API probes.

The cache check gains read_only: true plus read_only_reason when the database cannot be written (P5). It stays an "ok" check on purpose: a cache that only reads is a degraded optimisation, not a sick server, so overall does not change.

Probes api.flutter.dev and pub.dev with a light GET (10s timeout) and reports per-check status plus an overall verdict ("ok" / "degraded" / "error"). Never raises — individual failures only mark that check as error.

Also returns a top-level "politeness" block with the politeness layer's counters: robots cache rows/fetches/hits, requests blocked by robots.txt, throttle waits and per-host delays, conditional GETs / 304 revalidations, 429 and transport retries, request budgets and whether the layer is disabled (FLUTTER_DOCS_MCP_POLITENESS_DISABLED). It is diagnostics only and never affects "overall".