Imported from maxlainz/FutureFin (.claude/skills/futurefin-mcp-parity/SKILL.md). Install upstream with npx skills add maxlainz/FutureFin --skill futurefin-mcp-parity. Copyright stays with the author.

FutureFin — MCP surface parity

The embedded MCP server (apps/api/src/mcp/) is a derived surface: every tool is a thin Bearer-authenticated wrapper over the same *_core fn its HTTP handler uses. Derived surfaces rot silently — an endpoint gains a field, a handler changes semantics, a new feature ships HTTP-only — unless something forces the question at merge time. This skill is that something.

Volatile facts date-stamped 2026-08-28, Fases 0–6 del tren 4.4.0 (68 tools; recount con los comandos de §5 antes de fiarte de cualquier número de aquí). La Fase 6 (issue #87) es la primera del tren que mueve los contadores: 52 → 68 / 28 lectura / 40 escritura / 17 preview / 8 confirm_token / 18 impact, con 16 altas y cero bajas. Las Fases 0–5 no movieron ninguno (52/21/31/14/7) porque reescribían prosa, formas de respuesta y contratos de campo compartidos con la HTTP API, no el inventario de tools. Previamente 2026-08-22, tren 4.0.0 (52); 2026-08-20, tren 3.8.0 (50); 2026-08-19, tren 3.6.0 (47).

When NOT to use this skill

• WHY tools must call shared cores, live-role auth, hash-only credentials → .claude/skills/futurefin-architecture-contract/SKILL.md (D14, D15).
• What each existing tool does, its params, cache class, preview shape → .claude/api-routes.md §MCP (the catalog's single home).
• FUTUREFIN_MCP_ENABLED, FUTUREFIN_PUBLIC_URL, mcp_write_enabled semantics → .claude/skills/futurefin-config-and-flags/SKILL.md.
• Running/writing the MCP test suites, TestApp mechanics → .claude/tests.md and .claude/skills/futurefin-validation-and-qa/SKILL.md.
• Whether the overall change may ship at all (gates, breaking policy, release) → .claude/skills/futurefin-change-control/SKILL.md. Its "API contract" class routes to this skill; this skill never overrides its gates.
• The whole-handler authoring recipe (routes, openapi, migration, test) → .claude/backend-structure.md §Cómo añadir un handler (its step 7 points here).

1. The parity contract

Any change to the HTTP API surface must end, before merge, in exactly ONE of:

1. Tool added or updated — following the recipe in §4.
2. Deliberate omission recorded — a row added/confirmed in §3 with a rationale that survives the rubric in §2.
3. N/A — the change demonstrably cannot affect the MCP surface (e.g. a refactor with no contract change; an area already classified as excluded in §3 with unchanged rationale).

"Surface change" means: route added/removed/renamed; request/response field added, removed, retyped or revalidated; a handler's semantics changed (even keeping its shape — shared cores propagate semantics to tools silently, which is correct, but tool descriptions may now lie); a new query param or setting axis reachable from a handler.

Two directions, both mandatory:

• HTTP → MCP: new/changed endpoint ⇒ run the §2 rubric. The failure mode this kills is the quiet one: the feature ships, the SPA uses it, and the MCP client simply never learns it exists (nothing fails — tools/list is happily complete-looking at any size).
• MCP → docs/tests: new/changed tool ⇒ frozen catalog test, annotations expectations, .claude/mcp-catalog.md, and the module-map counters in .claude/backend-structure.md, same PR. The frozen-catalog test (tools_list_returns_exactly_the_v1_catalog) makes forgetting the test impossible; nothing mechanical protects the docs — that is why the recipe lists them explicitly.

Who enforces it: futurefin-change-control §1, class "API contract", carries this evaluation as a gate, and .claude/backend-structure.md §Cómo añadir un handler step 7 asks the question at authoring time. If you arrive here from either, do the evaluation, record the outcome (PR description or CHANGELOG entry: "MCP: tool X added" / "MCP: omisión deliberada, ver skill §3"), and go back.

2. Decision rubric — is a tool pertinent?

Default posture: financial data and simulation belong in the catalog; credentials, membership and infrastructure do not. Work the exclusions first — they are cheaper to decide.

2.1 Excluded categories (do NOT build a tool; record the row in §3)

2.2 Pertinence signals (build the tool)

• CRUD symmetry: if create_X and delete_X exist, update_X must too. The incident that proved it: until post-3.5.0 the catalog had create_liability + delete_liability but no update — "el TIN de mi hipoteca ha bajado" left the agent ONE path: destructive delete+recreate, which NULLs linked_liability_id on every linked transaction and drops the cuota's expense_category_id. A missing tool is not neutral; it pushes toward the dangerous alternative. Same logic, still open, for the create-without-cleanup asymmetries in §3.
• Engine inputs should be at least readable, ideally writable: anything that moves the projection (budget, planning, assets/liabilities, fire_settings, transactions in modes B/C, annual_inflation_assumption_percent) is what a conversational client most plausibly wants to inspect and adjust.
• The conversational diferencial: data whose natural entry point is a sentence, not a form ("en enero de 2023 tenía 40.000 € en el fondo" → snapshot backfill). If chat is better than the SPA at capturing it, the tool earns its slot.
• Self-cleanup: a tool that can create (categories, rules) should be able to correct its own mistakes, or the catalog drifts monotonically dirtier over a long conversation.
• Feasibility marker: does the handler already have a *_core? If yes the tool costs ~50 lines (§4). If not, the core extraction is the real work — and per D14 it is mandatory, never optional: a tool with its own SQL is an automatic review block.

2.3 Genuinely contested → record as "dudoso" in §3 with both sides

If neither list decides it, write the argument down in §3 rather than deciding by default. A "dudoso" with reasoning beats both a rushed tool and an invisible gap.

3. Standing decision register

This table is the skill's living core — the only home of "why is there no tool for X". Update it whenever the rubric runs. An entry here is a decision, not a prophecy: revisit when the blocking reason changes (noted per row).

3.1 Deliberate omissions (decided, stable)

3.2 Pertinent gaps — BACKLOG VACÍO (cero filas abiertas)

Estado: 0 huecos abiertos. Las cuatro filas que esta sección tuvo se cerraron el 2026-08-28 (Fase 6, issue #87). Lo que sigue es el archivo de esas cuatro, no una lista de trabajo pendiente: cada fila dice con qué se cerró y qué hubo que decidir. Si buscas qué falta por hacer, la respuesta es «nada en esta tabla» — salta a ¿Y si el backlog está vacío?, al final de la sección.

Se archiva en vez de borrarse porque una fila cerrada dice qué se decidió y por qué, y una tabla vacía sin historia invita a reabrir lo mismo dentro de seis meses. Antes de añadir una fila nueva aquí, muévela arriba de este aviso: el estado de la sección se lee en el encabezado, no en la letra pequeña. Deriva que esto arregla (Fase 7, 2026-08-29): la sección se titulaba «Pending pertinent gaps (open backlog, priority order)» con cuatro filas debajo, así que quien escaneara la tabla —lo normal— contaba cuatro huecos abiertos que llevaban un día cerrados.

Archivo de filas cerradas (Fase 6, 2026-08-28)

Closed since the register was created: las cuatro filas de arriba (Fase 6, 2026-08-28); update_categorization_rule + delete_categorization_rule (4.0.0, auditoría MCP §10 — era la fila #4; patch_rule_core/delete_rule_core extraídas de rules.rs, cache NONE, preview/confirm en el borrado con la huella actual vía apply_categorization_rule_core en dry_run. Cerrarla dejó dos guardias nuevas en la core, rule_patch_empty y rule_patch_conflict: el PATCH aceptaba cuerpo vacío y dejaba que el clear_* ganara en silencio sobre el campo puesto); update_asset and update_liability (post-3.5.0; the CRUD-symmetry incident in §2.2); and in the 3.8.0 issue-#4 train, three rows that were not even in this table because the endpoints did not exist yet — apply_categorization_rule (backfill retroactivo, cache COND), update_transactions (PATCH en lote, COND una sola vez) y get_allocation_resolution (la cascada resuelta, read-only, cache NONE; cierra además el stretch pendiente del issue #2). When you close a row, move it to a one-line mention here — history matters, the table stays short.

Y si el backlog está vacío, ¿qué queda? No «nada»: queda que el próximo hueco se descubra por el rubro §2, no por esta tabla. La Fase 6 salió de una observación que ninguna fila recogía — paridad de rutas ≠ paridad de capacidades: 89 de 90 parejas método-ruta estaban clasificadas y aun así la app calculaba cosas que no son una ruta y que el chat no alcanzaba (el calendario que el motor tira, el deflactado que el servidor ya hace para milestones_real, la huella de dedup que vive dentro de un preview, el cap que YA es un objetivo). Cuando esta tabla se vacíe otra vez, esa es la pregunta que hay que hacerse, no la de si falta un CRUD.

3.3 Reverse direction (tools without an endpoint)

Ya no es una excepción única: son CUATRO, y eso cambia lo que hay que exigirle a la quinta. Cuando esta sección decía «simulate_projection is the only one», la lectura implícita era que tool-sin-endpoint es un caso singular que se justifica por sí mismo. No lo es — es un patrón aceptado, con cuatro formas distintas. Recuento reproducible (cores que solo llama mcp/):

for c in simulate_projection_core patch_fire_settings_core settings_user_core \
         patch_presentation_settings_core; do
  echo "$c -> $(grep -rln "$c" apps/api/src/ | tr '\n' ' ')"
done   # cada uno: su handlers/*.rs de definición + mcp/server.rs, nunca un handler HTTP

Las cuatro comparten la propiedad que sí es exigible: el consumidor MCP no tiene el contexto que la SPA sí tiene (estado de cliente, pantalla previa, sesión). Una quinta tool-sin-endpoint necesita nombrar cuál de esas formas es, o traer un argumento nuevo a esta tabla — no basta con que sea cómoda. Dos de las cuatro son ya la misma forma («la core existe, el PATCH HTTP reemplaza el objeto entero, el chat necesita campo a campo»), así que esa vía está agotada como novedad: la quinta que la invoque no está argumentando nada, solo está aplicando un precedente — legítimo, pero dilo así.

3.4 View echo — object responses vs list_* envelopes (Fase 5, issue #86)

Every scope-aware response must echo which view it actually applied. The failure mode this closes: in a single-user installation, view: "mine" and view omitted returned byte-identical payloads, so there was no way to tell "mine happens to equal household" from "the parameter was silently ignored." In a two-person household that ambiguity is exactly the question that decides whether the number being quoted is the household's or the caller's.

Object responses get it for free. SummaryResponse, BudgetSnapshotResponse, ProjectionSeriesResponse and AllocationResolutionResponse gained a view field on the core (HistorySeriesResponse, CashflowResponse, TransactionsSummaryResponse and CategoryMonthlySeriesResponse already had it) — LedgerView::as_str() in handlers/person_view.rs is the single source now, replacing four separate copies of if view == Mine { "mine" } else { "household" }. Because every tool calls the same core its HTTP handler calls, every object-shaped tool inherits the field with zero code in server.rs.

Listings cannot do that. Every GET /v1/* list endpoint returns a bare JSON array on purpose — REST convention, and the SPA deserializes it as one. Wrapping that array to smuggle in a view field would be a breaking HTTP change for a field the SPA doesn't even need (it already knows its own view — it's the query param it sent). So for a scoped list_*, the echo has to be put on by the tool itself, in an envelope: {"view": "...", "<entity_key>": [...]}.

This is a design consequence, not a workaround. It moves 7 tools out of the byte-for-byte loop (mcp_http.rs::new_read_tools_match_http_endpoints) and into content parity (mcp_http.rs::list_tools_echo_the_applied_view_and_keep_content_parity, which asserts envelope[key] == GET?view=… for both views, AND that the bare GET still returns an array). It's the same path list_categorization_rules already walked when it grew pagination in 4.0.0 — an enveloped listing is not a new kind of problem, it's the second occurrence of one. See NOTA-VIEW-ENVELOPE in apps/api/src/mcp/server.rs for the comment block this section mirrors.

The 7 (tool → envelope key): list_assets → assets, list_liabilities → liabilities, list_planning_flows → planning_flows, list_allocation_rules → allocation_rules, list_transaction_months → months, list_transactions → transactions, list_transaction_imports → imports.

Still in the byte-for-byte loop — 11 tras la Fase 6 (eran 5 cuando se escribió esta sección; recuéntalas, no las copies):

# los pares (tool, endpoint) del bucle, sin contarlos a mano
sed -n '/fn new_read_tools_match_http_endpoints/,/^}/p' apps/api/tests/mcp_http.rs \
  | grep -oE '"(list|get|find|suggest|aggregate|deflate)[a-z_]*"' | sort -u    # → 11

Las cinco originales (list_categories, get_budget, list_recurring_rules, get_history_cashflow, get_category_monthly_series) más las seis lecturas nuevas de la Fase 6 (aggregate_transactions, find_duplicate_transactions, suggest_transfer_matches, list_goals, deflate_amount, get_liability_schedule). Ninguna necesita eco por parte de la tool: list_categories ni scopea ni pagina, y todas las demás son objetos cuya core ya lleva view cuando es scope-aware — las once son to_tool_result(core(...)) literal, así que la paridad byte a byte ES el contrato que prometen, no una aspiración.

La séptima lectura de la Fase 6, list_recent_changes, se queda fuera de los dos bucles: su campo now es el instante de la consulta, así que dos llamadas no pueden coincidir byte a byte. Tiene test propio (mcp_http.rs, paridad list_recent_changes ↔ GET /v1/changes ignorando now). Toda tool futura cuya respuesta lleve un reloj, un id aleatorio o un cursor hereda ese patrón: tercera vía, no una excepción — y hay que nombrar el campo que se ignora.

No view field at all — 4 tras la Fase 6 (own-user por construcción): list_snapshots, list_categorization_rules, list_recurring_rules y suggest_transfer_matches (nueva en la Fase 6). Sus cores no aceptan view de entrada — el doc-comment de list_recurring_rules_core lo dice explícito («siempre own-user… no inventarlo en la tool»). Añadir ahí un campo view no sería un eco, sería afirmar un scope que la tool nunca tuvo. Caso vecino que no es este: deflate_amount tampoco acepta view, pero no porque sea own-user sino porque la inflación es de la instalación — no confundas «sin scope de usuario» con «own-user» al clasificar la quinta.

Rule for future list_* tools: if the new listing's core accepts view, the envelope is mandatory and its parity row belongs in the content-parity test, never the byte-parity one. If the core is own-user (no view param), do not invent a view field in the tool's output.

3.5 prompts — la segunda primitiva del protocolo (Fase 6, issue #87)

Hasta 4.4.0 este registro era tool-shaped: todo el rubro §2 decide si algo merece una tool. La Fase 6 declara la capacidad prompts (ServerCapabilities::builder().enable_tools().enable_prompts(); resources sigue sin declararse), así que hace falta un criterio propio — si no, la primera pregunta sobre un prompt se responderá con el rubro de las tools, que decide otra cosa.

Qué es un prompt aquí: un guion estático. Cero SQL, cero identidad, cero lectura de la instalación. prompts/get no toca la base de datos, así que no hay nada que gatear por rol ni por mcp_write_enabled — y por eso tampoco abre fila de auditoría. Lo que aporta no es acceso: es el orden en que se encadenan tools que ya existen, más las salvedades que un modelo con prisa se salta (el modo de ahorro decide si las transacciones mueven el motor; los agregados de flujo excluyen las conciliadas; null no es cero).

Cuándo un prompt es pertinente (los tres de hoy —revision_mensual, auditoria_categorizacion, amortizar_o_invertir— cumplen los tres puntos):

1. Es un flujo multi-tool, no una tool con otro nombre. Si se resuelve con una llamada, la respuesta correcta es mejorar esa tool o su descripción.
2. Sus salvedades son transversales y hoy viven repetidas (o ausentes) en varias descripciones. Un prompt las versiona con el código en vez de reinventarlas en cada conversación.
3. No necesita argumentos. Los tres se publican sin ninguno a propósito: interpolar texto de cliente dentro de un guion que el modelo lee como instrucciones es una vía de inyección gratuita. Un prompt que "necesita" un parámetro casi siempre quería ser una tool.

Coste y límite, medidos y no supuestos (2026-08-28): cuestan una tabla de constantes y dos métodos sin I/O — pero el conector remoto de claude.ai NO los muestra hoy (sus docs dicen que en MCP remoto prompts y resources «are not yet supported»). Claude Code y los clientes genéricos sí (/mcp__<servidor>__<prompt>). Se publican igual porque el coste es ese y el día que el conector los soporte ya están — pero no cuentan como capacidad entregada al cliente principal, y cualquier texto público debe decirlo (regla de claims, futurefin-research-frontier).

No cuentan en los contadores de §5. Los ocho números son de tools. Si algún día hay tantos prompts como para que su prosa pese, añade su propia línea al presupuesto de contexto — hoy no la tienen porque son tres.

4. Recipe — add or update a tool

Model commits: 82a43cb (reconcile tools, 43→45), the post-3.5.0 update_asset/ update_liability commit (45→47, includes a core extraction) and the 3.8.0 issue-#4 train (47→50: apply_categorization_rule, update_transactions, get_allocation_resolution — two new cores, one new engine entry point and a verb outside the create_/update_/delete_ naming convention, which forced a conscious arm in the annotations test). Steps, in order:

1. Core first. The handler logic must live in a *_core(state|pool, iid, user_id, …) shared fn — auth/extractors stay in the HTTP handler, everything else (validation, SQL, response struct, cache invalidation post-commit) moves into the core. Classify the invalidation: FULL (refresh_projection_after_mutation), COND (invalidate_projection_if_savings_uses_transactions) or NONE — and put it INSIDE the core so no future caller can forget it. Zero SQL in apps/api/src/mcp/server.rs — ese es el invariante que importa, y es el que un grep -c sobre ese fichero comprueba en un segundo. auth.rs sí tiene SQL propio y creciente (el SELECT del toggle desde siempre; el INSERT/UPDATE/poda de mcp_write_audit desde 4.4.0), porque la autorización y su registro NO son lógica de dominio y no tienen core que compartir. Contar «1 hit en todo mcp/» era una aproximación que caducó en cuanto la auditoría aterrizó: el número subía sin que nada se hubiera roto.

2. Params struct in server.rs (before the #[tool_router] impl): #[derive(Debug, Deserialize, schemars::JsonSchema)], /// doc comments in Spanish on every field (they ARE the schema descriptions the LLM reads), #[serde(default)] + Option for optional fields, #[schemars(range(...))] for bounds. Decimals travel as strings; UUIDs/dates as strings parsed with parse_uuid_param/parse_date_param/parse_decimal_param. A PATCH-style "omit vs null" tri-state cannot be expressed in the schema — model it as a clear_*: bool flag (precedents: clear_expense_end_date, clear_cap, clear_purchase_price).

3. Tool fn inside the #[tool_router] impl FutureFinMcp, placed next to its thematic neighbors. Canonical body: identity(&ctx)? → a run() closure mapping params to the handler's body struct (fail early via to_tool_outcome) → async block: require_mcp_write FIRST for any write → the core fn → compact serde_json::json!({id, summary, …}) → to_tool_result. Reads return the core's serde struct unmodified (Decimal-as-string intact). summary, in English — until Fase 2 of issue #83 this key was named resumen, the last Spanish key on the MCP wire (repo norm: "UI copy en español, código e identificadores en inglés"). When the handler names the field in Spanish — today only BatchPatchResponse.resumen/resumen_truncated, the HTTP contract of PATCH /v1/transactions/batch — translate it in the tool, exactly as apply_categorization_rule already publishes out.sample as summary: the catalog must speak ONE language, because a client that learned summary from ten tools reads result.summary on the eleventh and gets undefined with no error at all.

   Description has a hard budget (Fase 5, issue #86): ≤600 characters per tool, ≤24,000 for the whole catalog, enforced by mcp_http.rs::tool_descriptions_stay_within_the_context_budget. The incident that forced it: a client received get_summary's 2,278-character description truncated, mid-warning, about an inconsistency between two other tools. When the guard fails, do not raise the constant — its own failure message says so. Move the overflow to a response-field caveat (the pattern this server already uses: savings_income_basis, avg_basis, fire_target_absent_reason, skipped_reason) or to get_info's instructions, which every client reads once per session instead of once per tool. Reproduce the current numbers with:

   python3 -c "import json;t=json.load(open('apps/api/tests/fixtures/mcp-catalog.json'))['tools'];l=[x['description_len'] for x in t];print(len(t),sum(l),max(l))"

   (today: 68 23949 598 after 4.15.0 — 51 characters from the ceiling; it was 68 23995 596 — 5 from the ceiling — right before 4.15.0, not the 126 this line used to claim: re-measure, never trust the frozen number; 52 21319 596 right after Fase 5; before Fase 5: 37,214 total, one description at 3,821, 26 tools over 600 chars). Read that margin before you start: Fase 6's 16 tools took the raw total to 28,884 (+4,884 over budget) and bringing it back was real work, not a trim. The next tool has to buy its description out of somebody else's.

4. Annotations are mandatory and pattern-bound: title in Spanish + read_only_hint + destructive_hint + idempotent_hint + open_world_hint = false. The annotations test derives expectations from the name (update_*/delete_* ⇒ destructive+idempotent; create_* ⇒ neither) — name the tool to match the convention or extend the test's match arms consciously.

5. Destructive tools get preview/confirm: without confirm: true return {preview: true, confirm_required: true, action, effects} as SUCCESS (a preview is information for the LLM, not an error), using read cores for the effects. Updates that edit fields in place are destructive-hinted but do NOT need preview/confirm (editing keeps the row).

6. Sibling descriptions: a new tool can change what an existing description should say (update_asset_value gained "para el resto de campos usa update_asset"; list_transactions gained the transfer_counterpart_id explanation when reconcile tools shipped). Sweep the related tools' descriptions.

7. Tests — the write-tool quartet in apps/api/tests/mcp_write.rs (shared core: row indistinguishable via HTTP; cache contract via warm/assert_invalidated; a shared domain error surfacing with the HTTP wire code; the mcp_write_enabled toggle cutting it live) + add the name to the frozen catalog in mcp_http.rs::tools_list_returns_exactly_the_v1_ catalog (alphabetical). Read tools: byte-parity vs the GET instead of the quartet.

8. Docs, same PR: .claude/mcp-catalog.md (the catalog and its counters), .claude/backend-structure.md (module-map counters), .claude/tests.md suite rows, this skill's §3 register (close/open rows), CHANGELOG entry. Run §5's counters to catch what you missed.

5. Keeping it honest — verification and drift audit

Reproducible counters (run from repo root; expected values dated 2026-08-28, Fases 0–6 del tren 4.4.0):

grep -c '#\[tool(' apps/api/src/mcp/server.rs                      # 68 — total tools
grep -c 'read_only_hint = true' apps/api/src/mcp/server.rs          # 28 — reads + simulate
grep -c 'read_only_hint = false' apps/api/src/mcp/server.rs         # 40 — writes
grep -c 'require_mcp_write(&self.state.pool' apps/api/src/mcp/server.rs  # 40 — MUST equal writes
grep -c 'p.confirm.unwrap_or(false)' apps/api/src/mcp/server.rs     # 17 — preview/confirm (Fase 6: +3)
grep -c '= two_phase(' apps/api/src/mcp/server.rs                    # 8 — las que exigen token de dos fases
#   (OJO 1: `grep -c 'confirm_token'` a secas da 47 — cuenta también el campo del schema y su prosa.
#    OJO 2: el comando de esta línea fue `grep -c 'confirm_token.as_deref'` hasta la Fase 7, y hoy
#    da **10**, no 8: el propio doc-comment de `DeleteWithTokenParams` en `server.rs` menciona esa
#    cadena dos veces —una de ellas al prescribir este mismo grep—, así que el patrón se cuenta a sí
#    mismo. Es la trampa de todo contador auto-referencial: el comando que un comentario recomienda
#    deja de funcionar en cuanto el comentario lo escribe literal. `= two_phase(` no la tiene (las
#    dos menciones en prosa son `[`two_phase`]`, con backticks). Alternativa igual de buena:
#    `grep -c 'p\.confirm_token\.as_deref()'` → 8. **`server.rs` sigue prescribiendo el grep viejo**
#    y no se puede arreglar desde documentación — reportado como deriva código↔contrato.)
grep -c 'settled(&self.state.pool' apps/api/src/mcp/server.rs       # 40 — == escrituras: toda escritura cierra su fila de auditoría
#   (el patrón lleva `&self.state.pool` a propósito: `grep -c 'settled('` da 41, contando la definición)
grep -c 'impact_since(&self.state' apps/api/src/mcp/server.rs       # 18 — escrituras que publican el bloque `impact`
#   (`grep -c 'impact_since('` da 19: cuenta también la definición)
grep -c 'sqlx::query' apps/api/src/mcp/server.rs                   # 0 — EL invariante real
grep -c 'sqlx::query' apps/api/src/mcp/auth.rs                     # 4 — gate + auditoría (4.4.0)

Los ocho números son 68/28/40/40/17/8/40/18 a 2026-08-28 (Fases 0–6 del tren 4.4.0), recontados enteros ese día. Antes de la Fase 6: 52/21/31/31/14/7/31/15.

Invariant cross-checks: writes == require_mcp_write count (a write tool skipping the gate is a security bug); reads + writes == total; the frozen-catalog vec length == total. The doc-side counters (mcp-catalog.md, backend-structure.md module map, this file) must all agree with the code counter — any mismatch is the "3.0.0 bumped code but not the frozen counters" incident repeating (futurefin-docs-and-writing §7 owns that lesson).

Full parity audit (run when the catalog smells stale, or ~once per release train): list the HTTP surface and diff it against the catalog and this register —

grep -rn '\.route(' apps/api/src/routes/mod.rs apps/api/src/handlers/ | grep -v tests
grep -oP 'name = "\K[a-z_]+' apps/api/src/mcp/server.rs

Every route must land in one of: covered (name the tool), §3.1 omission row, §3.2 backlog row, or — the finding — an unclassified gap, which means the parity contract was skipped: classify it now and check what else that PR missed.

Provenance and maintenance

Written 2026-08-19 (post-3.5.0 train, branch dev), sourced from: full tool inventory and git show 82a43cb (the add-a-tool pattern), a route-by-route HTTP↔MCP coverage matrix over apps/api/src/routes/mod.rs + apps/api/src/mcp/server.rs, and the norm inventory across CLAUDE.md, .claude/api-routes.md, architecture-contract D14/D15 and change-control. The update_asset/update_liability pair (45→47) shipped in the same change as this skill. Refreshed 2026-08-20 for the 3.8.0 issue-#4 train (47→50). Refreshed 2026-08-22 for the 4.0.0 train (50→52 with update_categorization_rule + delete_categorization_rule), and that refresh ran the §1 evaluation over the routes the train added — recorded, never silent:

Evaluación posterior (2026-08-25, sin cambio de contadores — el catálogo sigue en 52):

Evaluación del tren 4.2.0 (modelo de amortización por pasivo; 2026-08-25, catálogo sin cambios en 52):

Evaluación de la rama feat/home-assistant-addon (add-on de HA; 2026-08-27, catálogo sin cambios en 52 — recontado ese día: 52/21/31/31):

Evaluación de la rama feat/ha-idp-login (4.3.1, «Entrar con Home Assistant»; 2026-08-27, catálogo sin cambios en 52):

Evaluación de la rama feat/mcp-fase-1-numeros (Fase 1 de la revisión adversarial del MCP, issue #82 — «números que mienten»; tren 4.4.0, sin publicar aún; catálogo sin cambios en 52, recontado 52/21/31/31 el 2026-08-28). A diferencia de los trenes anteriores, este NO añade superficie: reescribe el contrato de salida de handlers que ya existían, y como cada tool comparte la core de su handler, la mayoría del trabajo llegó gratis — lo que costó fue la prosa:

Nueve tools con description/payload actualizados (get_projection, simulate_projection, get_allocation_resolution, get_history, get_history_cashflow, get_transactions_summary, get_category_monthly_series, update_transaction, create_categorization_rule) + una décima tocada solo en su struct de params (update_fire_settings, sin description reescrita — ver fila de arriba). Cero tools nuevas, cero retiradas: el catálogo sigue en 52. Ninguna fila necesitó promoción HTTP→tool nueva ni omisión — todo lo demás ya estaba cubierto y lo único que cambió fue lo que esa cobertura devuelve. Detalle campo a campo, con el porqué de cada nulabilidad: .claude/api-routes.md §MCP y las secciones HTTP de cada endpoint (History series, History cash-flow, Projection, Allocation rules, Transactions).

Evaluación de la rama feat/mcp-fase-2-esquema (Fase 2 de la revisión adversarial del MCP, issue #83 — «el esquema no valida lo que la prosa promete»; catálogo sin cambios en 52, recontado 52/21/31/31/11/1 el 2026-08-28). Como la Fase 1, no añade superficie: endurece el contrato de entrada (deny_unknown_fields en las 52, enum/pattern/cotas en el JSON Schema en vez de solo en la prosa) y unifica el contrato de salida de las escrituras. Las dos filas que cierran los huecos que la auditoría de la propia fase encontró:

Evaluación de la rama feat/mcp-fase-3-escritura-segura (Fase 3, issue #84 — «escritura segura»: auditoría, scope, confirmación en dos fases; catálogo sin cambios en 52, recontado 52/21/31/31 el 2026-08-28). A diferencia de las Fases 1/2, esta SÍ añade superficie nueva de protocolo (mcp_write_audit, api_tokens.scope, confirm_token) pero no añade ni retira ninguna tool — reescribe el andamiaje común de las escrituras y el contrato de entrada/salida de 22 de las 31:

Truncated - read the full file at https://github.com/maxlainz/FutureFin/blob/7b1feceaeae04ba630b4555ca5cf2255242f57a8/.claude/skills/futurefin-mcp-parity/SKILL.md.