Document the config surface, filter grammar, and migration seams in the README

[Azdaroth]

Audited the README against the actual Configuration / Resource / Filtering surface rather than reading it through. The prose is in good shape — it already covers 0.6.1's appended-discovery change — but one documented default is now wrong, and a lot of load-bearing surface is missing.

The outdated bit

The config table documents tool_provider as defaulting to nil. Since 0.5.0 it composes itself when unset:

def tool_provider
  @tool_provider || composed_tool_provider   # RegistryToolProvider + extra_tool_providers
end

This is worse than a gap — it tells a host it must assign a provider, which is the plumbing 0.5.0 explicitly removed the need for. The README's own "Or serve the generic Registry-backed tools" example then demonstrated that boilerplate. Both are fixed: registering resources is now shown as sufficient, with the explicit assignment kept as the take-full-control escape hatch.

Settings that were undocumented

Ten had no mention anywhere in the README; six OAuth ones existed only in prose, never in the reference table. Two of those (oauth_signing_secret, oauth_authorization_code_ttl) appeared nowhere at all.

Family	Settings
Data path / filtering	bare_filter_value_semantics, non_numeric_pk_order, filter_operator_overrides, sql_sanitizer
Safety caps	max_filter_values (500), max_batch_size (50)
Authority	extra_tool_providers, session_data_builder
OAuth bridge	all six oauth_*, now in a table of their own

The two caps are worth calling out — they are security limits added in 0.5.0 (an uncapped IN-set / JSON-RPC batch lets one valid token fan out unbounded work), and a host had no way to learn they existed, let alone tune them.

The filter grammar

The largest gap. The README never documented how a client actually filters — no mention of not_eq, gteq, matches, does_not_match, { op:, value: }, IN sets, or the "null" token anywhere in 766 lines.

The grammar is served in the tool descriptions, so clients discover it at runtime. But a host evaluating the gem, or configuring filter_operator_overrides, had nothing to read. Added a "Reading data" section: limit/offset/fields/filter, bare values vs operator conditions, AND-ed condition arrays, the operator table by column type, and why the null/LIKE combinations raise instead of silently matching nothing.

Also

• filter_requirements and extra added to the documented Resource DSL (both were missing).
• register_upstreams_from_env documented — the 0.5.0 helper for the two gotchas "every authority host re-discovers" (reload duplication, blank ENV vars).
• A Migrating an existing MCP endpoint table mapping a pre-gem contract onto the compatibility seams that exist for it, including the one deliberate non-revertible delta ({ op: "in", value: "a,b" } now splits).

Verification

Docs-only; no code changed. bundle exec rubocop clean, and both new cross-reference anchors resolve against real headings.

🤖 Generated with Claude Code