@mmerterden/multi-agent-toolkit-mcp 3.14.0 → 3.15.0

package/CHANGELOG.md

@@ -15,10 +15,199 @@ Releases before this file exists are recorded in the git tags and commit history
 
 ---
 
-## Unreleased
+## [3.15.0] - 2026-09-25
+
+### Changed
+
+- **Requires Node.js 22.13 or later** (`engines`, README, CI matrix 22 and 24).
+  The context index uses `node:sqlite`, which is unflagged from 22.13, and
+  Node 20 is past end of life. The context module is now imported on first use,
+  so on a Node without `node:sqlite` the server still starts and only
+  `context_*` and crawl indexing answer with the reason.
+- **`web_goto` applies `user_agent`.** It was accepted and ignored. It is now
+  set on the browser context, so requests and `navigator.userAgent` agree; a
+  different value starts a fresh context (cookies, storage and tabs of the old
+  one are discarded), and omitting it keeps the current one.
+- **`web_crawl` identifies itself** with a `multi-agent-toolkit-mcp/<version>`
+  User-Agent on every request it makes, as its description already said.
+- **Research results share one shape.** `research_search` over Perplexity now
+  returns the same title/url/snippet blocks as Brave, and `limit` is capped at
+  20, the most Brave returns per request.
+- **`additionalProperties: false` is enforced** at the call boundary for the
+  schemas that declare it (the `security_*` tools, `design_scenario_inventory`,
+  `design_component_variants`): an undeclared argument is an error instead of
+  being ignored. Declared object fields are checked at every depth, so a
+  misspelt field inside an array item or a nested object is refused too.
+- **`design_scenario_inventory` counts a `*Outcome` / `*Scenario` / `*MockCase`
+  type only with debug evidence.** The suffix alone also matches production
+  service results, whose cases no debug switch can reach. A type is a target
+  when it is declared under `#if DEBUG` or in an Android debug/mock source set,
+  referenced only from debug/mock code, or read from a runtime key (launch
+  argument, UserDefaults, SharedPreferences, intent extra). Test targets are
+  neutral. Every decision is returned: `acceptedSelectors[]` with the rule that
+  admitted it (also on each target as `evidence.basis`), `rejectedSelectors[]`
+  with the production references that disqualified it.
+
+### Added
+
+- **`design_component_variants`** (tool 118): resolves design nodes to their
+  component set and variants from Figma data the caller already fetched - a
+  REST `/v1/files/:key/nodes` response or MCP `get_metadata` XML per file, plus
+  the library's `component_sets` listing to locate a set in another file. Walks
+  instance -> main component -> set -> variants and returns, per variant, its
+  properties, frame, a geometry-only `figma_spec`, the render to fetch and the
+  Code Connect name from a supplied mapping. Audited states are matched to
+  variants by how much of the state's wording a variant name covers, so a
+  one-word state such as `Error` matches `State=Error, Size=L`; ambiguous or
+  distant matches are listed, never assigned. A node id is looked up in the
+  file that referenced it first, and `node_ids` accepts `fileKey/nodeId` to pick
+  one of several sources that use the same id. Code Connect URLs with a
+  percent-encoded `node-id` are read.
+  `needs[]` and `rendersNeeded[]` name what is still to fetch. Comparing the
+  live component region against its matched variant removes fixture row-count
+  differences from the geometry findings.
+- **`design_visual_compare` `component`**: the component a capture region
+  belongs to; stamped onto every finding that names none, so `design_report`
+  renders the main component link and one thumbnail per variant. A variant
+  without a render shows a "not rendered" placeholder instead of a broken image.
+- **`design_scenario_inventory` `targets_file` / `targets[]`**: supply the
+  target set from an external catalog (a bare array, or `{ version: 1,
+  platform?, description?, targets }`, each target in the shape the tool
+  returns). Source scanning is skipped; `plan`, `groups`, `relaunchCount`, the
+  coverage gate, `extra_targets` and `ignore_targets` work unchanged. Unknown
+  fields, a driver missing the field its type needs, and duplicate ids are
+  refused. The 400-target cap applies to source scanning only: a catalog, config
+  extras and extra launch args are kept whole, and `truncated` is set only when
+  a scan found more targets than the cap, not exactly as many.
+- **`design_report` roll-up mode** (`modules[]`): one row per module with
+  coverage, gate, deviations and a link to its report (rendered into
+  `<out_dir>/<module>/` unless `href` is given). Each module runs through the
+  coverage gate; any module that fails it, or declares no coverage, fails the
+  roll-up, and the result names the failed modules.
+- **`MCP_TOOLKIT_URL_POLICY=strict`** (opt-in): the web tools refuse non-http(s)
+  URLs and hosts that are or resolve to loopback, unspecified (`0.0.0.0/8`),
+  link-local, private (RFC1918, CGNAT `100.64.0.0/10`, IPv6 ULA `fc00::/7`,
+  deprecated IPv6 site-local `fec0::/10`), IETF protocol (`192.0.0.0/24`), benchmarking (`198.18.0.0/15`), multicast,
+  reserved (`240.0.0.0/4`) or cloud metadata addresses. An IPv6 address that
+  carries an IPv4 one (mapped, compatible, translated, NAT64 `64:ff9b::/96`,
+  6to4, Teredo) is judged by that IPv4 address, since a translator or relay
+  delivers it there; the local-use NAT64 prefix `64:ff9b:1::/48` is refused
+  outright. The check applies to every request the browser
+  makes: a browser-context route aborts refused navigations, subresources,
+  fetches, popups and WebSockets, and the browser runs behind a local egress
+  proxy that checks each redirect hop and connects to the address it checked.
+  The address a navigation lands on is checked too, `web_crawl` neither reads
+  nor indexes a page that redirected to a refused address, and the reading
+  tools refuse a page whose address is refused. Service workers are blocked in
+  this mode, and WebRTC is kept off direct UDP, which neither the route nor
+  the proxy sees (Chromium's WebRTC IP handling policy is
+  `disable_non_proxied_udp`, Firefox has `media.peerconnection.enabled` off,
+  WebKit pages get no `RTCPeerConnection`). The proxy attaches its error
+  handlers before judging a request, validates the CONNECT port, answers a
+  failing check instead of rejecting, opens nothing for a client that has
+  already gone, and closes each side of a tunnel when the other closes, so a
+  client that resets mid-check cannot take the server down or leak a socket.
+  A CONNECT tunnel dials the host the check judged (brackets stripped, through
+  the pinned address), not the raw authority. An upstream that does not accept
+  the connection within `MCP_TOOLKIT_PROXY_CONNECT_TIMEOUT_MS` (default 15000)
+  is answered with 504, for plain requests, tunnels and upgrades alike, and a
+  response whose upstream goes away mid-body is closed toward the browser
+  instead of being left open as if more were coming.
+  Unset, nothing changes.
+- **`MCP_TOOLKIT_URL_ALLOW`**: comma-separated host names, IPs and CIDRs the
+  strict policy lets through (for an intranet wiki, a staging range, a local
+  fixture server). It never widens the scheme check; a malformed entry is
+  reported and ignored.
+- **`MCP_TOOLKIT_INDEX_DENY`**: paths `context_index` will not index and
+  `context_get` / `context_search` will not return. Under the strict policy
+  `~/.ssh`, `~/.aws`, `~/.gnupg`, `~/Library/Keychains`, `~/.netrc`,
+  `~/.git-credentials`, `~/.config/gh`, `~/.docker`, `~/.kube`, `~/.npmrc`,
+  `~/.config/gcloud`, `~/.azure`, `~/.pypirc`, `~/.cargo/credentials` and
+  `~/.cargo/credentials.toml` are denied by default. The variable adds to that
+  list, so naming one extra path cannot drop the credential stores; a value
+  that starts with `!` replaces the defaults, and one that leaves nothing
+  denied (a lone `!`) is reported on stderr, naming the strict defaults it
+  drops. On macOS the comparison ignores letter case, as the
+  default volume does, so `~/.SSH/id_rsa` is denied too.
+
+### Fixed
+
+- **`design_visual_compare` with `live_region` measured rows against the full
+  screen height.** Full-width rows were sampled at `y / screenHeight` of the
+  cropped region, so they read another row's edges and produced inset findings
+  on a conformant component; the region's own height is used now. Without a
+  region, a top crop is subtracted from the live height the same way.
+- **Config `extra_targets` carry a `cost`** derived from their driver, like
+  scanned targets, instead of none (which `byCost` counted under `undefined`).
+- **Test fixtures and comments use neutral product names** only.
+- **The research key follows the provider.** `RESEARCH_PROVIDER` was not
+  validated, and any value other than exactly `perplexity` picked the Brave key
+  while any value other than exactly `brave` sent the request to Perplexity,
+  so `Brave` or a typo sent the Brave key to api.perplexity.ai. The value is
+  now trimmed, lowercased and checked; an unknown provider is an error and no
+  request is made.
+- **Offloaded results are owner-only**: the offload directory is `0700` and
+  each file `0600`. `web_storage_state` is no longer offloaded at all, since
+  its payload is session cookies and localStorage.
+- **An empty or dash-led bundle id or package name is refused.** An empty
+  `bundle_id` turned `ios_reset_permissions` into `simctl privacy <d> reset
+  all`, which resets every app on the simulator. A slash is refused too:
+  `ios_set_locale` passes the bundle id to `defaults write`, which reads a value
+  with a slash as a plist path. An Android `activity` may still be written as
+  `package/activity`, and is validated on its own.
+- **`media_frames` can re-run into the same `out_dir`**: ffmpeg gets `-y`, and
+  frames left by an earlier run are removed first instead of being counted.
+- **`web_crawl` honours `max_depth: 0` and `delay_ms: 0`**, which `Number(x) ||
+  default` turned into the defaults.
+- **`android_list_packages` with `filter` reports an adb failure** instead of
+  filtering the error text into an empty success.
+- **Recorders**: a recorder binary that cannot be spawned is reported by the
+  start call instead of crashing the server with an unhandled `error` event.
+- **The server exits when the host closes stdin.** Recorders stop at once,
+  calls in flight get up to five seconds to answer, and then the SIGTERM path
+  runs: LSP servers, spawned commands and the browser are closed and the
+  process exits. An open browser or LSP server kept it alive before.
+- **Long-running commands are bounded**: `spawnCollect` runs the command in its
+  own process group, signals the whole group on a timeout or an abort, follows
+  SIGTERM with SIGKILL after a grace period, and returns shortly after the
+  shell exits even if a grandchild still holds the output pipe. That holds for
+  a clean exit too: a command that leaves a background job running reports its
+  own exit code, and `timedOut` is set only when the timer fired while the
+  command was still running. Whatever the command left running in its group
+  is sent SIGTERM once the result is returned, then SIGKILL after the grace
+  period, so a background job does not outlive the call. Output is decoded as UTF-8 per stream, so a
+  multibyte character split across two reads is no longer garbled. The App
+  Store audit runs every command through one helper with a timeout and an
+  output cap.
+- **design-check source scans pass `--` to ripgrep** before the search path,
+  so a path that starts with a dash is searched instead of being read as an
+  option.
+- **The context index** keeps one database handle per server instead of one
+  per call, and indexes a file in a single transaction, so a failure partway
+  no longer leaves a partial copy that later calls report as unchanged. Its
+  directory is narrowed to `0700` on every open, including one that already
+  existed with wider permissions.
+
+### Removed
+
+- The unused `TOOL_DESCRIPTOR` export in `tools/ios-app-store-audit`; its
+  tests now check the description the server actually serves.
 
 ---
 
+## [3.14.0] - 2026-09-21
+
+### Added
+
+- **`security` family: `security_cvss_score` and `security_dep_inventory`.**
+  security_cvss_score turns a CVSS 3.1 base vector into a score and band by the
+  FIRST arithmetic, so a finding's number cannot drift from its vector.
+  security_dep_inventory normalizes a lockfile (npm, yarn, pnpm, CocoaPods, pip,
+  Go, Cargo, RubyGems) into {ecosystem, name, version}. Both are pure JS and
+  contact nothing - matching an inventory against known CVEs stays a separate,
+  network-bearing step, so the stdio-only egress surface is unchanged. Gated at
+  serve time by `MCP_TOOLKIT_CAPS=security`. 117 tools total.
+
 ## 3.13.1 - 2026-09-21
 
 Fixes to the web and context families, each held by a gate proven to fail
@@ -751,8 +940,6 @@ The tests pin both shapes; the first real Android run is that half's measurement
   It could not be tested where it was: `index.js` connects its transport at
   import time, so nothing in it is reachable from a test.
 
-## Unreleased
-
 ## 3.1.0
 
 One new tool and the offload path behind it. Minor rather than patch because the
@@ -1025,7 +1212,7 @@ TestFlight pre-submission validation: ask Apple before Apple asks you.
   because the app never reaches the mock state those riders need. Assignment
   scores an exact screen match above a substring one, then a relaunch with a
   launch argument above one without, then canonical order. Substring pairing
-  ("Apis Form" ↔ "APIS") still works; it just no longer outranks an exact match.
+  ("Order Form" ↔ "ORDER") still works; it just no longer outranks an exact match.
 - New `plan-determinism.test.mjs` permutes `buildPlan`'s input across 40 seeds
   and asserts the plan is byte-identical. A pass-count is not proof of order
   independence: this property test caught residual rider-ordering drift on its
@@ -1153,7 +1340,7 @@ down to the `path` array.
 **Fixture-count noise is demoted, not reported as defects** (`docs/design-check-gaps.md`
 section 1, the item that dominated a real 109-target audit). A live capture is
 compared against a screen frame, and a screen frame carries whatever the mock
-fixture produced: 5 passenger rows in the design against 3 in the app makes every
+fixture produced: 5 item rows in the design against 3 in the app makes every
 container height and every downstream position differ for a reason that is not a
 defect.
 
@@ -1320,19 +1507,6 @@ paths and requires an error on each. Gate 9 requires every tool advertising an
 outputSchema to actually return `structuredContent`, and to keep its text
 content beside it. 14 gates, all green.
 
-## [3.14.0] - 2026-09-21
-
-### Added
-
-- **`security` family: `security_cvss_score` and `security_dep_inventory`.**
-  security_cvss_score turns a CVSS 3.1 base vector into a score and band by the
-  FIRST arithmetic, so a finding's number cannot drift from its vector.
-  security_dep_inventory normalizes a lockfile (npm, yarn, pnpm, CocoaPods, pip,
-  Go, Cargo, RubyGems) into {ecosystem, name, version}. Both are pure JS and
-  contact nothing - matching an inventory against known CVEs stays a separate,
-  network-bearing step, so the stdio-only egress surface is unchanged. Gated at
-  serve time by `MCP_TOOLKIT_CAPS=security`. 117 tools total.
-
 ## [3.0.0] - 2026-08-22
 
 ### Changed

package/README.md

@@ -7,13 +7,13 @@
 
 🇹🇷 Türkçe: [README.tr.md](./README.tr.md)
 
-**117 tools** for iOS Simulator, Android Emulator, and headless web control. MCP server that lets your AI coding assistant see, interact with, and audit your mobile apps - plus drive browsers, run an 18-rule App Store compliance audit, and orchestrate multi-step batch flows.
+**118 tools** for iOS Simulator, Android Emulator, and headless web control. MCP server that lets your AI coding assistant see, interact with, and audit your mobile apps - plus drive browsers, run an 18-rule App Store compliance audit, and orchestrate multi-step batch flows.
 
 Distributed on the **public npm registry** - `npx @mmerterden/multi-agent-toolkit-mcp` resolves with no auth, no token, no `~/.npmrc` setup.
 
 **Verified on Claude Code, Copilot CLI and Codex CLI** - the three hosts the release gates actually exercise. Being a standard stdio MCP server it also runs in Cursor, Antigravity, VS Code Copilot Chat, Claude Desktop and any other MCP client; config snippets for those are below, but nothing here checks them.
 
-That distinction is worth keeping straight. This line once called five hosts "the multi-agent-pipeline's full-orchestration targets", which stopped being true in pipeline v10.7.0 when the Cursor / Antigravity / Codex / Copilot Chat adapters were deleted. Codex CLI returned as a first-class target in pipeline v13.0.0 on capability - it now has skills, parallel sub-agents, hooks and MCP - and it is on the verified list only because a gate exercises it, not because it is supported elsewhere. Claiming hosts nobody exercises is not free either: 2.20.0 and 2.21.0 shipped an illegal `outputSchema` on the first tool, so Claude Code rejected the whole `tools/list` and served zero of the 78 - in the primary host, for two releases, with every gate in this repo green.
+The verified list is the set of hosts a release gate starts and queries: a host that no gate runs is not claimed as supported, because a schema that one client tolerates can make another reject the whole `tools/list`.
 
 **14 categories:**
 - **Device Control** (59 tools) - screenshot, tap, swipe, type, navigate, dark mode, locale, orientation, location, permissions, push notifications, real start/stop screen recording
@@ -22,7 +22,7 @@ That distinction is worth keeping straight. This line once called five hosts "th
 - **Accessibility Audit** (3 tools) - `ios_accessibility_audit` / `android_accessibility_audit` read the live tree for missing labels, controls a screen reader cannot name, small tap targets, missing identifiers and a reading order that does not follow the visual layout. `ios_accessibility_audit_deep` runs Apple's own XCUIAccessibilityAudit through your XCUITest for the things a tree cannot show: contrast, Dynamic Type, clipped text. All three report `measurable:false` with a reason rather than a clean result when they could not look
 - **Store Compliance** (5 tools) - App Store / Play Store readiness; **18-rule deep `ios_app_store_audit`** cross-references Apple ITMS error codes + App Store Review Guidelines (privacy manifest, required-reason API, Info.plist, code signing, entitlements, embedded SDK, IPv6, debug-tool leak, ...)
 - **Web Automation** (18 tools) - Playwright-powered: goto, click, type, press a key, select an option, eval JS, wait for a selector, extract text, screenshot, plus an accessibility snapshot whose `ref` handles the other tools accept in place of a CSS selector, console and network logs captured since the last navigation, tab and storage state, readable article extraction, same-origin link mapping and a bounded crawl. Chromium / WebKit / Firefox engines. **Requires `playwright` peer dependency.**
-- **Design Audit** (6 tools) - mock-mode vs Figma conformance: scenario inventory, mock detection, mock launch, live UI geometry, pixel/geometry/typography compare, and the HTML/PDF report with its coverage gate
+- **Design Audit** (7 tools) - mock-mode vs Figma conformance: scenario inventory, mock detection, mock launch, live UI geometry, component-variant resolution, pixel/geometry/typography compare, and the HTML/PDF report with its coverage gate and module roll-up
 - **Code Intelligence** (8 tools) - compiler-grade answers about Swift and Kotlin source, over the language server each platform already ships: definition, references, hover, document and workspace symbols, diagnostics without a full build, plus `code_index_status` for whether this machine can answer at all. Cross-file answers need a background index, so they report whether it had settled instead of returning an empty list that reads as "unused"
 - **Wallet Passes** (4 tools) - build, sign, validate and inspect Apple Wallet passes. All five styles, offline and deterministic, and a literal passphrase is deliberately not an accepted input: the caller names an environment variable or a keychain entry. The validator grades by consequence, because the interesting failures are the silent ones - one unknown `PKPassengerCapability` value raises nothing and quietly drops an enhanced pass back to the old layout
 - **Context Index** (3 tools) - a large result is not only written to a file, it is chunked and indexed in SQLite FTS5, so `context_search` ranks passages with bm25() and answers in roughly 50-100 tokens which part is about what. `context_get` opens one passage by id; the file path is still there for everything. Grep tells you which lines contain a string; ranking tells you which part is about the subject. No dependency: `node:sqlite` ships with Node
@@ -163,7 +163,7 @@ Add to `.vscode/mcp.json`:
 
 ### Requirements
 
-- **Node.js 18+**
+- **Node.js 22.13+** (the context tools use `node:sqlite`, unflagged from 22.13; on an older Node the rest of the server still starts and `context_*` answers with that reason)
 - **iOS tools**: macOS + Xcode (provides `xcrun simctl`)
 - **Android tools**: Android SDK Platform-Tools (provides `adb`)
 - **Web tools** (optional): `playwright` - install once:
@@ -174,6 +174,16 @@ Add to `.vscode/mcp.json`:
 
 > If Xcode is not installed, iOS tools return a friendly message instead of crashing. Same for Android and Web tools - use what you have.
 
+### Restricting what the server can reach
+
+Off by default; unset, nothing below changes behaviour.
+
+- **`MCP_TOOLKIT_URL_POLICY=strict`** - the web tools refuse any URL that is not `http(s)`, and any host that is or resolves to a loopback (`127.0.0.0/8`, `::1`, `localhost`), unspecified (`0.0.0.0/8`, `::`), link-local (`169.254.0.0/16`, `fe80::/10`), private (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, CGNAT `100.64.0.0/10`, IPv6 ULA `fc00::/7`, deprecated IPv6 site-local `fec0::/10`), IETF protocol (`192.0.0.0/24`), benchmarking (`198.18.0.0/15`), multicast or reserved (`224.0.0.0/4`, `240.0.0.0/4`, `ff00::/8`, local-use NAT64 `64:ff9b:1::/48`) or cloud metadata address (`metadata.google.internal`, `fd00:ec2::254`, `100.100.100.200`). An IPv6 address that carries an IPv4 one (IPv4-mapped, IPv4-compatible, IPv4-translated, NAT64 `64:ff9b::/96`, 6to4 `2002::/16`, Teredo `2001::/32`) is judged by the IPv4 address it carries. A host that does not resolve is refused. The check covers every request the browser makes, not only the URL given to `web_goto`: a browser-context route aborts refused navigations, subresources, fetches, popups and WebSockets, and the browser is launched behind a local proxy (127.0.0.1 only) that checks each hop of a redirect chain and connects to the address it checked; an upstream that does not accept the connection within `MCP_TOOLKIT_PROXY_CONNECT_TIMEOUT_MS` (default 15000) is answered with 504. The URL a navigation lands on is checked as well, `web_crawl` skips and does not index a page that redirected to a refused address, and the reading tools (`web_get_text`, `web_extract`, `web_snapshot`, `web_screenshot`, `web_eval` and the rest) refuse to read a page whose address is refused. Service workers are blocked and the HTTP cache is off in this mode, because both would bypass the route. WebRTC is kept off direct UDP, which neither the route nor the proxy sees: Chromium is launched with `--force-webrtc-ip-handling-policy=disable_non_proxied_udp`, Firefox with `media.peerconnection.enabled=false`, and WebKit pages get no `RTCPeerConnection`. The proxy's coverage of loopback targets is verified on Chromium. Any value other than `strict` or `off` is warned about on stderr and treated as `strict`.
+- **`MCP_TOOLKIT_URL_ALLOW`** - comma-separated exceptions to the strict policy: host names (matched exactly, case-insensitively), IP addresses and CIDRs, e.g. `wiki.corp.example,10.20.0.0/16,127.0.0.1`. A listed host, a literal IP inside a listed range, or a host whose refused answers all fall inside a listed range is let through. It never allows a non-`http(s)` scheme, a malformed entry is reported on stderr and ignored, and it has no effect without `strict`.
+- **`MCP_TOOLKIT_INDEX_DENY`** - comma-separated paths (`~/` expands) that `context_index` refuses to index and that `context_get` / `context_search` refuse to return, symlinks resolved (on macOS the comparison ignores letter case, as the default APFS volume does, so `~/.SSH/id_rsa` is `~/.ssh/id_rsa`). Under `strict` the default list is `~/.ssh`, `~/.aws`, `~/.gnupg`, `~/Library/Keychains`, `~/.netrc`, `~/.git-credentials`, `~/.config/gh`, `~/.docker`, `~/.kube`, `~/.npmrc`, `~/.config/gcloud`, `~/.azure`, `~/.pypirc`, `~/.cargo/credentials`, `~/.cargo/credentials.toml`. Set, the variable adds its paths to those defaults and applies with or without the strict policy. A value that starts with `!` replaces the defaults instead (`!~/work,~/notes` denies only those two; a lone `!` denies nothing, and the server says so on stderr at startup).
+
+Offloaded results under `~/.claude/logs/multi-agent-toolkit/` are written owner-only (directory `0700`, files `0600`), and the context index directory is narrowed to `0700` every time it is opened, including one that already existed with wider permissions. `web_storage_state` is never offloaded: its cookies and localStorage come back inline.
+
 ### Agent DSL Example
 
 Run a scripted login flow in one MCP call:
@@ -274,18 +284,19 @@ Returns per-step status so the agent can self-correct on failure.
 | `android_list_crashes` | Dump the adb crash log buffer, tail-bounded |
 | `android_set_orientation` | Rotate to portrait/landscape (pins user_rotation, disables auto-rotate) |
 
-### Design Tools (6)
+### Design Tools (7)
 
 Mock-mode vs Figma design audit. Generic and platform-agnostic - the heavy orchestration (Figma fetch, variant matching, screen navigation, report assembly) is expected to live in the caller; these expose the mechanical primitives.
 
 | Tool | Description |
 |------|-------------|
 | `design_mock_detect` | Detect whether a project supports a mock/stub mode (`true` / `false` / `debug-only`) via naming conventions, `#if DEBUG` DI, MockData fixtures, and well-known runtime switch keys (extendable). Returns activation + variant hints + evidence. |
-| `design_scenario_inventory` | Enumerate every state driver the mock build exposes - relaunch flags, `*Scenario` / `*Outcome` enum cases, reference-prefix variants (`hasPrefix("F6DI")` branches inside per-screen mock repositories, typically the largest group), flow-wide scenario codes, MockData fixtures, custom-scheme deep links - each with file+line evidence. Prices every target (`relaunch` vs `in-app`) and batches them into a run `plan`, so one relaunch serves every in-app state on that screen. Gives an audit a countable target set instead of "walk the UI until it feels done". |
+| `design_scenario_inventory` | Enumerate every state driver the mock build exposes - relaunch flags, `*Scenario` / `*Outcome` enum cases (counted only with debug evidence: declared under `#if DEBUG` or in an Android debug/mock source set, referenced only from debug/mock code, or read from a runtime key; a production type sharing the suffix is reported in `rejectedSelectors` instead), reference-prefix variants (`hasPrefix("R1EX")` branches inside per-screen mock repositories, typically the largest group), flow-wide scenario codes, MockData fixtures, custom-scheme deep links - each with file+line evidence. Prices every target (`relaunch` vs `in-app`) and batches them into a run `plan`, so one relaunch serves every in-app state on that screen. `targets_file` / `targets[]` supply the target set from an external catalog instead of scanning; plan, groups, relaunch count and the coverage gate work unchanged. Gives an audit a countable target set instead of "walk the UI until it feels done". |
 | `design_mock_launch` | Launch an installed app in mock mode (iOS UserDefaults launch arg / Android intent extra). |
 | `design_ui_geometry` | Flat element bounding boxes of the current screen + screen size, for px-level spacing measurement. |
+| `design_component_variants` | Resolve a design node to its component set and list the variants (`State=Error`, `Rows=3`), from Figma data the caller already fetched (REST `nodes` response or MCP `get_metadata` XML, plus the library's `component_sets` listing; the server never contacts Figma). Returns per-variant geometry spec, frame, render request and Code Connect name, matches audited states to variants by name, and lists the nodes and renders still to fetch. Comparing the live component region against its own variant removes the fixture row-count dimension from the geometry findings. |
 | `design_visual_compare` | Compare a Figma render vs a live screenshot without failing on size mismatch: normalizes scale, crops chrome, reports perceptual diff %, spacing/size/position (px), color (ΔE), and typography. Writes figma/live/diff/overlay/side-by-side PNGs. |
-| `design_report` | Render a design-audit report object to self-contained HTML (base64 images, CSS-positioned annotations) + optional PDF. Enforces a coverage gate: every target must be audited or skipped with an explicit reason, so a partial audit cannot render as a clean report. Wording comes from a label pack (English default, Turkish built in). |
+| `design_report` | Render a design-audit report object to self-contained HTML (base64 images, CSS-positioned annotations) + optional PDF. Enforces a coverage gate: every target must be audited or skipped with an explicit reason, so a partial audit cannot render as a clean report. Wording comes from a label pack (English default, Turkish built in). Roll-up mode (`modules[]`) renders one row per module - coverage, gate, deviations, link to the module report - and fails when any module fails its own gate. |
 
 ### Code Intelligence Tools (8)
 
@@ -362,6 +373,66 @@ that grade exists because those are the ones nobody finds:
 Run against a real signed production boarding pass, the validator reported zero
 errors and found both of the last two.
 
+### Web Tools (18)
+
+Headless browser control through Playwright, an optional peer dependency. One browser and one context are reused across calls.
+
+| Tool | Description |
+|------|-------------|
+| `web_goto` | Open a URL. Takes `browser` (chromium / webkit / firefox), `wait_until`, `timeout_ms`, `viewport`, `locale` and `user_agent` |
+| `web_screenshot` | Screenshot of the current page, inline PNG or written to `path` |
+| `web_click` | Click by CSS selector, text, or a `ref` from `web_snapshot` |
+| `web_type` | Type into an input matched by selector or `ref` |
+| `web_eval` | Run JavaScript in the page and return the result as JSON |
+| `web_wait_for` | Wait for a selector to reach a state |
+| `web_get_text` | textContent of the first match of a selector or `ref` |
+| `web_close` | Close the browser context and release resources |
+| `web_snapshot` | Accessibility snapshot with a stable `[ref=eN]` per node, for the action tools |
+| `web_console` | Console messages since the last `web_goto` |
+| `web_network` | Requests since the last `web_goto`: method, status, type, URL |
+| `web_tabs` | List the open pages and switch the active one |
+| `web_storage_state` | Read cookies and localStorage, or restore a saved state |
+| `web_extract` | The page's article content as Markdown (or text) |
+| `web_map` | Same-origin links on the current page, deduplicated |
+| `web_crawl` | Bounded same-origin crawl, robots.txt respected, each page indexed for `context_search` |
+| `web_press_key` | Press a key, optionally on a focused element |
+| `web_select_option` | Choose a `<select>` option by value or label |
+
+### Context Index Tools (3)
+
+| Tool | Description |
+|------|-------------|
+| `context_index` | Index a text file into the SQLite FTS5 index; an unchanged file is a no-op |
+| `context_search` | Ranked passages (bm25) with a short snippet and a chunk id per hit |
+| `context_get` | One passage in full by id, with its file and line range |
+
+### Research Tools (2)
+
+| Tool | Description |
+|------|-------------|
+| `research_search` | Web search through Brave or Perplexity, normalized to title / url / snippet. Key from `BRAVE_API_KEY` or `PERPLEXITY_API_KEY`, never an argument |
+| `research_ask` | A cited answer from Perplexity Sonar. Key from `PERPLEXITY_API_KEY` |
+
+### Media Tools (1)
+
+| Tool | Description |
+|------|-------------|
+| `media_frames` | Key frames from a video as PNGs, near-duplicates dropped. Requires ffmpeg |
+
+### Agent Tools (2)
+
+| Tool | Description |
+|------|-------------|
+| `agent_run_steps` | Run a batch of ios / android / web / design steps in one call, with per-step status and a verdict |
+| `agent_query_output` | Search the saved full output of an earlier call that was too large to return inline |
+
+### Security Tools (2)
+
+| Tool | Description |
+|------|-------------|
+| `security_cvss_score` | CVSS 3.1 base score and band from a base vector, offline |
+| `security_dep_inventory` | A lockfile normalized to `{ecosystem, name, version}`, offline |
+
 ### Use Cases
 
 - **Visual bug hunting** - Screenshot every screen, AI analyzes for layout issues

package/README.tr.md

@@ -7,13 +7,13 @@
 
 🇬🇧 English: [README.md](./README.md)
 
-iOS Simulator, Android Emulator ve headless web kontrolü için **115 araç**. AI kodlama asistanının mobil uygulamalarını görmesini, onlarla etkileşime girmesini ve denetlemesini sağlayan bir MCP sunucusu - ayrıca tarayıcıları sürer, 18-kurallık bir App Store uyumluluk denetimi çalıştırır ve çok-adımlı batch akışlarını orkestre eder.
+iOS Simulator, Android Emulator ve headless web kontrolü için **118 araç**. AI kodlama asistanının mobil uygulamalarını görmesini, onlarla etkileşime girmesini ve denetlemesini sağlayan bir MCP sunucusu - ayrıca tarayıcıları sürer, 18-kurallık bir App Store uyumluluk denetimi çalıştırır ve çok-adımlı batch akışlarını orkestre eder.
 
 **Public npm registry** üzerinden dağıtılır - `npx @mmerterden/multi-agent-toolkit-mcp`, auth'suz, token'sız, `~/.npmrc` ayarı gerekmeden çözülür.
 
 **Claude Code, Copilot CLI ve Codex CLI üzerinde doğrulanmıştır** - release kapılarının fiilen çalıştırdığı üç host. Standart bir stdio MCP sunucusu olduğu için Cursor, Antigravity, VS Code Copilot Chat, Claude Desktop ve diğer herhangi bir MCP client'ında da çalışır; bunlar için config parçacıkları aşağıda, ama burada hiçbir şey onları kontrol etmiyor.
 
-Bu ayrımı net tutmakta fayda var. Bu satır bir zamanlar beş host'u "multi-agent-pipeline'ın tam-orkestrasyon hedefleri" olarak adlandırıyordu, bu da pipeline v10.7.0'da Cursor / Antigravity / Codex / Copilot Chat adaptörleri silindiğinde doğru olmaktan çıktı. Codex CLI, pipeline v13.0.0'da yetenek üzerinden birinci-sınıf bir hedef olarak geri döndü - artık skill'leri, paralel sub-agent'ları, hook'ları ve MCP'si var - ve doğrulanmış listede sadece bir kapı onu çalıştırdığı için yer alıyor, başka bir yerde desteklendiği için değil. Kimsenin çalıştırmadığı host'ları iddia etmek de bedavaya gelmiyor: 2.20.0 ve 2.21.0, ilk araçta yasa dışı bir `outputSchema` gönderdi, bu yüzden Claude Code tüm `tools/list`'i reddetti ve 78'in sıfırını sundu - birincil host'ta, iki release boyunca, bu repo'daki her kapı yeşilken.
+Doğrulanmış liste, bir release kapısının başlatıp sorguladığı host'lardan oluşur: hiçbir kapının çalıştırmadığı bir host desteklenen olarak iddia edilmez, çünkü bir client'ın tolere ettiği bir şema başka bir client'ın tüm `tools/list`'i reddetmesine yol açabilir.
 
 **14 kategori:**
 - **Device Control** (59 araç) - screenshot, tap, swipe, type, navigate, dark mode, locale, orientation, location, permissions, push notifications, gerçek start/stop ekran kaydı
@@ -22,7 +22,7 @@ Bu ayrımı net tutmakta fayda var. Bu satır bir zamanlar beş host'u "multi-ag
 - **Accessibility Audit** (3 araç) - `ios_accessibility_audit` / `android_accessibility_audit` canlı ağacı okur: eksik label, ekran okuyucunun adlandıramadığı kontrol, küçük tap target, eksik identifier ve görsel düzeni izlemeyen okuma sırası. `ios_accessibility_audit_deep` ise ağacın gösteremeyeceği şeyler için Apple'ın kendi XCUIAccessibilityAudit'ini XCUITest'iniz üzerinden çalıştırır: kontrast, Dynamic Type, kırpılmış metin. Üçü de bakamadıklarında temiz bir sonuç değil, gerekçesiyle `measurable:false` döner
 - **Store Compliance** (5 araç) - App Store / Play Store hazırlığı; **18-kurallık derin `ios_app_store_audit`**, Apple ITMS hata kodları + App Store Review Guidelines'a çapraz referans verir (privacy manifest, required-reason API, Info.plist, code signing, entitlements, gömülü SDK, IPv6, debug-tool sızıntısı, ...)
 - **Web Automation** (18 araç) - Playwright-destekli: goto, click, type, tuş basma, seçenek seçme, JS eval, selector bekleme, metin çıkarma, screenshot; ayrıca diğer araçların CSS selector yerine kabul ettiği `ref` tutamaklarını üreten erişilebilirlik snapshot'ı, son navigasyondan beri toplanan console ve network kayıtları, sekme ve storage durumu, okunabilir makale çıkarımı, aynı-origin link haritası ve sınırlı bir crawl. Chromium / WebKit / Firefox motorları. **`playwright` peer dependency'si gerektirir.**
-- **Design Audit** (6 araç) - mock-mode vs Figma uygunluğu: scenario envanteri, mock tespiti, mock launch, canlı UI geometrisi, piksel/geometri/tipografi karşılaştırması, ve coverage kapısıyla birlikte HTML/PDF rapor
+- **Design Audit** (7 araç) - mock-mode vs Figma uygunluğu: scenario envanteri, mock tespiti, mock launch, canlı UI geometrisi, component varyant çözümleme, piksel/geometri/tipografi karşılaştırması, ve coverage kapısı ile modül özetiyle birlikte HTML/PDF rapor
 - **Code Intelligence** (8 araç) - Swift ve Kotlin kaynağı hakkında derleyici seviyesinde cevaplar, her platformun zaten getirdiği dil sunucusu üzerinden: tanım, referanslar, hover, dosya ve proje geneli semboller, tam build olmadan tanılamalar, ve bu makinenin soruyu cevaplayıp cevaplayamayacağını söyleyen `code_index_status`. Çapraz dosya cevapları arka plan index'ine bağlı olduğu için, "kullanılmıyor" diye okunan boş bir liste yerine index'in oturup oturmadığını raporlar
 - **Wallet Passes** (4 araç) - Apple Wallet pass'i üret, imzala, doğrula ve incele. Beş stilin hepsi, çevrimdışı ve deterministik; düz metin parola bilerek kabul edilen bir girdi değil: çağıran taraf bir ortam değişkeninin adını ya da bir keychain kaydını verir. Doğrulayıcı bulguları sonucuna göre derecelendirir, çünkü asıl önemli hatalar sessiz olanlar - tanınmayan tek bir `PKPassengerCapability` değeri hiçbir uyarı üretmez ve gelişmiş pass'i sessizce eski düzene düşürür
 - **Context Index** (3 araç) - büyük bir sonuç yalnızca dosyaya yazılmaz, parçalanıp SQLite FTS5'e indekslenir; `context_search` bm25() ile sıralar ve hangi parçanın neyle ilgili olduğunu yaklaşık 50-100 token'da söyler. `context_get` tek bir parçayı id ile açar, dosya yolu ise her şey için orada durur. Grep hangi satırların bir dizgiyi içerdiğini söyler; sıralama hangi parçanın o konuyla ilgili olduğunu. Bağımlılık yok: `node:sqlite` Node ile geliyor
@@ -163,7 +163,7 @@ paketine scope'la) ve tekrar dene.
 
 ### Gereksinimler
 
-- **Node.js 18+**
+- **Node.js 22.13+** (context araçları `node:sqlite` kullanır, 22.13'ten itibaren bayraksız; daha eski bir Node'da sunucunun geri kalanı yine açılır ve `context_*` bu gerekçeyle cevap verir)
 - **iOS araçları**: macOS + Xcode (`xcrun simctl`'i sağlar)
 - **Android araçları**: Android SDK Platform-Tools (`adb`'yi sağlar)
 - **Web araçları** (opsiyonel): `playwright` - bir kere kur:
@@ -174,6 +174,16 @@ paketine scope'la) ve tekrar dene.
 
 > Xcode kurulu değilse, iOS araçları crash etmek yerine anlaşılır bir mesaj döner. Android ve Web araçları için de aynı - elindekini kullan.
 
+### Sunucunun erişimini kısıtlamak
+
+Varsayılan olarak kapalı; ayarlanmadığında aşağıdakilerin hiçbiri davranışı değiştirmez.
+
+- **`MCP_TOOLKIT_URL_POLICY=strict`** - web araçları `http(s)` olmayan her URL'yi ve loopback (`127.0.0.0/8`, `::1`, `localhost`), belirtilmemiş (`0.0.0.0/8`, `::`), link-local (`169.254.0.0/16`, `fe80::/10`), özel ağ (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, CGNAT `100.64.0.0/10`, IPv6 ULA `fc00::/7`, kullanımdan kaldırılmış IPv6 site-local `fec0::/10`), IETF protokol (`192.0.0.0/24`), benchmark (`198.18.0.0/15`), multicast ya da ayrılmış (`224.0.0.0/4`, `240.0.0.0/4`, `ff00::/8`, yerel kullanım NAT64 `64:ff9b:1::/48`) ya da bulut metadata adresi (`metadata.google.internal`, `fd00:ec2::254`, `100.100.100.200`) olan veya bunlara çözümlenen her host'u reddeder. İçinde IPv4 adresi taşıyan bir IPv6 adresi (IPv4-mapped, IPv4-compatible, IPv4-translated, NAT64 `64:ff9b::/96`, 6to4 `2002::/16`, Teredo `2001::/32`) taşıdığı IPv4 adresine göre değerlendirilir. Çözümlenemeyen host reddedilir. Kontrol yalnızca `web_goto`'ya verilen URL'yi değil, tarayıcının yaptığı her isteği kapsar: tarayıcı bağlamındaki bir route reddedilen navigasyonları, alt kaynakları, fetch'leri, popup'ları ve WebSocket'leri keser; tarayıcı ayrıca yerel bir proxy'nin (yalnızca 127.0.0.1) arkasında başlatılır, bu proxy bir yönlendirme zincirinin her adımını kontrol eder ve kontrol ettiği adrese bağlanır; bağlantıyı `MCP_TOOLKIT_PROXY_CONNECT_TIMEOUT_MS` (varsayılan 15000) içinde kabul etmeyen bir upstream 504 ile yanıtlanır. Navigasyonun vardığı URL de kontrol edilir, `web_crawl` reddedilen bir adrese yönlenen sayfayı atlar ve indekslemez, okuma araçları (`web_get_text`, `web_extract`, `web_snapshot`, `web_screenshot`, `web_eval` ve diğerleri) adresi reddedilen bir sayfayı okumaz. Bu modda service worker'lar engellenir ve HTTP önbelleği kapalıdır, çünkü ikisi de route'u atlar. WebRTC, ne route'un ne de proxy'nin gördüğü doğrudan UDP'den uzak tutulur: Chromium `--force-webrtc-ip-handling-policy=disable_non_proxied_udp` ile, Firefox `media.peerconnection.enabled=false` ile başlatılır, WebKit sayfalarında `RTCPeerConnection` bulunmaz. Proxy'nin loopback hedeflerini kapsadığı Chromium üzerinde doğrulanmıştır. `strict` ya da `off` dışındaki her değer stderr'de uyarılır ve `strict` sayılır.
+- **`MCP_TOOLKIT_URL_ALLOW`** - strict politikaya virgülle ayrılmış istisnalar: host adları (birebir, büyük/küçük harf duyarsız eşleşir), IP adresleri ve CIDR'ler, ör. `wiki.corp.example,10.20.0.0/16,127.0.0.1`. Listelenen bir host, listelenen bir aralıktaki IP ya da reddedilen tüm cevapları listelenen bir aralığa düşen bir host geçirilir. `http(s)` dışı bir şemaya asla izin vermez, hatalı bir girdi stderr'de bildirilip yok sayılır ve `strict` olmadan etkisi yoktur.
+- **`MCP_TOOLKIT_INDEX_DENY`** - `context_index`'in indekslemeyi reddettiği, `context_get` / `context_search`'ün döndürmeyi reddettiği, virgülle ayrılmış yollar (`~/` açılır, symlink'ler çözülür; macOS'ta karşılaştırma, varsayılan APFS birimi gibi büyük/küçük harfe bakmaz, yani `~/.SSH/id_rsa` ile `~/.ssh/id_rsa` aynıdır). `strict` altında varsayılan liste `~/.ssh`, `~/.aws`, `~/.gnupg`, `~/Library/Keychains`, `~/.netrc`, `~/.git-credentials`, `~/.config/gh`, `~/.docker`, `~/.kube`, `~/.npmrc`, `~/.config/gcloud`, `~/.azure`, `~/.pypirc`, `~/.cargo/credentials`, `~/.cargo/credentials.toml` olur. Değişken ayarlandığında yolları bu varsayılanlara eklenir ve strict politikadan bağımsız uygulanır. `!` ile başlayan bir değer ise varsayılanların yerine geçer (`!~/work,~/notes` yalnızca bu ikisini reddeder; tek başına `!` hiçbir şeyi reddetmez ve sunucu bunu açılışta stderr'e yazar).
+
+`~/.claude/logs/multi-agent-toolkit/` altına offload edilen sonuçlar yalnızca sahibine açık yazılır (dizin `0700`, dosyalar `0600`); context indeks dizini de her açılışta, daha geniş izinlerle önceden var olmuş olsa bile, `0700`'e daraltılır. `web_storage_state` hiç offload edilmez: cookie'leri ve localStorage'ı satır içinde döner.
+
 ### Agent DSL Örneği
 
 Tek bir MCP çağrısında scriptlenmiş bir login akışı çalıştır:
@@ -274,18 +284,103 @@ Agent'ın hata durumunda kendini düzeltebilmesi için adım-başına durum dön
 | `android_list_crashes` | adb crash log buffer'ını dök, tail-sınırlı |
 | `android_set_orientation` | Portrait/landscape'e döndür (user_rotation'ı sabitler, auto-rotate'i kapatır) |
 
-### Design Araçları (6)
+### Design Araçları (7)
 
 Mock-mode vs Figma tasarım denetimi. Jenerik ve platform-bağımsız - ağır orkestrasyonun (Figma çekme, varyant eşleme, ekran navigasyonu, rapor derleme) çağıranda yaşaması beklenir; bunlar mekanik ilkel işlemleri açığa çıkarır.
 
 | Araç | Açıklama |
 |------|-------------|
 | `design_mock_detect` | Bir projenin mock/stub modunu desteklediğini (`true` / `false` / `debug-only`) isimlendirme konvansiyonları, `#if DEBUG` DI, MockData fixture'ları ve bilinen runtime switch key'leri (genişletilebilir) üzerinden tespit et. Aktivasyon + varyant ipuçları + kanıt döner. |
-| `design_scenario_inventory` | Mock build'in açığa çıkardığı her state sürücüsünü enumerate et - relaunch flag'leri, `*Scenario` / `*Outcome` enum case'leri, reference-prefix varyantları (ekran-başına mock repository'ler içindeki `hasPrefix("F6DI")` dalları, genelde en büyük grup), akış-geneli senaryo kodları, MockData fixture'ları, custom-scheme deep link'ler - her biri dosya+satır kanıtıyla. Her hedefi (`relaunch` vs `in-app`) fiyatlandırır ve bir çalıştırma `plan`ına gruplar, böylece bir relaunch o ekrandaki her in-app state'e hizmet eder. Bir denetime "UI'da bitmiş hissedene kadar gez" yerine sayılabilir bir hedef seti verir. |
+| `design_scenario_inventory` | Mock build'in açığa çıkardığı her state sürücüsünü enumerate et - relaunch flag'leri, `*Scenario` / `*Outcome` enum case'leri (yalnızca debug kanıtıyla sayılır: `#if DEBUG` altında ya da Android debug/mock source set'inde tanımlı, yalnızca debug/mock koddan referanslanan veya runtime key'den okunan; aynı son eki taşıyan production tipi `rejectedSelectors` içinde raporlanır), reference-prefix varyantları (ekran-başına mock repository'ler içindeki `hasPrefix("R1EX")` dalları, genelde en büyük grup), akış-geneli senaryo kodları, MockData fixture'ları, custom-scheme deep link'ler - her biri dosya+satır kanıtıyla. Her hedefi (`relaunch` vs `in-app`) fiyatlandırır ve bir çalıştırma `plan`ına gruplar, böylece bir relaunch o ekrandaki her in-app state'e hizmet eder. `targets_file` / `targets[]` hedef setini tarama yerine harici bir katalogdan verir; plan, gruplar, relaunch sayısı ve coverage kapısı aynı şekilde çalışır. Bir denetime "UI'da bitmiş hissedene kadar gez" yerine sayılabilir bir hedef seti verir. |
 | `design_mock_launch` | Kurulu bir uygulamayı mock modda başlat (iOS UserDefaults launch arg / Android intent extra). |
 | `design_ui_geometry` | Piksel-seviyesi boşluk ölçümü için mevcut ekranın düz element bounding box'ları + ekran boyutu. |
+| `design_component_variants` | Bir tasarım node'unu component set'ine çözümle ve varyantlarını (`State=Error`, `Rows=3`) listele; veri çağıranın zaten çektiği Figma verisidir (REST `nodes` yanıtı ya da MCP `get_metadata` XML'i, artı kütüphanenin `component_sets` listesi; sunucu Figma'ya hiç bağlanmaz). Varyant başına geometri spec'i, frame, render isteği ve Code Connect adı döner, denetlenen state'leri isimle varyantlara eşler, hâlâ çekilmesi gereken node ve render'ları listeler. Canlı component bölgesini kendi varyantıyla karşılaştırmak fixture satır sayısı farkını geometri bulgularından çıkarır. |
 | `design_visual_compare` | Bir Figma render'ını canlı bir screenshot ile boyut uyuşmazlığında başarısız olmadan karşılaştır: ölçeği normalize eder, chrome'u kırpar, algısal diff %'sini, boşluk/boyut/pozisyonu (px), rengi (ΔE) ve tipografiyi raporlar. figma/live/diff/overlay/side-by-side PNG'leri yazar. |
-| `design_report` | Bir tasarım-denetim rapor nesnesini kendi kendine yeten HTML'e (base64 görseller, CSS-konumlandırılmış annotasyonlar) + opsiyonel PDF'e render et. Bir coverage kapısı zorlar: her hedef denetlenmeli ya da açık bir gerekçeyle atlanmalı, böylece kısmi bir denetim temiz bir rapor olarak render edilemez. Metin bir label pack'ten gelir (varsayılan İngilizce, Türkçe dahili olarak yerleşik). |
+| `design_report` | Bir tasarım-denetim rapor nesnesini kendi kendine yeten HTML'e (base64 görseller, CSS-konumlandırılmış annotasyonlar) + opsiyonel PDF'e render et. Bir coverage kapısı zorlar: her hedef denetlenmeli ya da açık bir gerekçeyle atlanmalı, böylece kısmi bir denetim temiz bir rapor olarak render edilemez. Metin bir label pack'ten gelir (varsayılan İngilizce, Türkçe dahili olarak yerleşik). Özet modu (`modules[]`) modül başına bir satır render eder - kapsam, kapı, sapmalar, modül raporuna link - ve herhangi bir modül kendi kapısını geçemezse başarısız olur. |
+
+### Code Intelligence Araçları (8)
+
+Swift ve Kotlin kaynağı hakkında, her platformun zaten getirdiği dil sunucusu üzerinden derleyici seviyesinde cevaplar. Kotlin tarafı JetBrains `kotlin-lsp` (Alpha) kullanır ve bu repo'daki hiçbir kapı onu çalıştırmaz.
+
+| Araç | Açıklama |
+|------|----------|
+| `code_definition` | Bir sembolün tanımlandığı yer; 1-tabanlı satır+sütun ya da `symbol` adı alır |
+| `code_references` | Workspace genelinde her referans; index'in oturup oturmadığını raporlar |
+| `code_hover` | Bir konumdaki tip, imza ve doc comment |
+| `code_document_symbols` | Tek bir dosyanın sembol ağacı |
+| `code_workspace_symbols` | Workspace genelinde isimle sembol arama |
+| `code_diagnostics` | Tam build olmadan tek dosyanın derleyici tanılamaları |
+| `code_index_status` | Dil başına: sunucu kurulu mu, hangi build sistemi bulundu, diskte index var mı |
+| `code_server_reset` | Havuzdaki dil sunucularını durdurur |
+
+### Wallet Pass Araçları (4)
+
+| Araç | Açıklama |
+|------|----------|
+| `pass_validate` | pass.json, `.pass` dizini ya da `.pkpass`'i Apple kurallarına göre denetler, bulguları sonucuna göre derecelendirir |
+| `pass_build` | `.pkpass` üretir, imzalar ve arşivler; önce doğrular |
+| `pass_inspect` | Bir `.pkpass`'in içeriğini raporlar: stil, semantik etiketler, görseller, manifest bütünlüğü, imza zinciri |
+| `pass_certificates` | İmza materyalini raporlar; anahtar materyalini okumaz |
+
+### Web Araçları (18)
+
+Opsiyonel peer dependency olan Playwright üzerinden headless tarayıcı kontrolü. Çağrılar arasında tek tarayıcı ve tek context kullanılır.
+
+| Araç | Açıklama |
+|------|----------|
+| `web_goto` | Bir URL açar. `browser` (chromium / webkit / firefox), `wait_until`, `timeout_ms`, `viewport`, `locale` ve `user_agent` alır |
+| `web_screenshot` | Mevcut sayfanın screenshot'ı, satır içi PNG ya da `path`'e yazılmış |
+| `web_click` | CSS selector, metin ya da `web_snapshot`'tan bir `ref` ile tıklar |
+| `web_type` | Selector ya da `ref` ile eşleşen input'a yazar |
+| `web_eval` | Sayfada JavaScript çalıştırır, sonucu JSON döner |
+| `web_wait_for` | Bir selector'ın belirli bir duruma gelmesini bekler |
+| `web_get_text` | Selector ya da `ref`'in ilk eşleşmesinin textContent'i |
+| `web_close` | Tarayıcı context'ini kapatır |
+| `web_snapshot` | Her düğümde sabit bir `[ref=eN]` olan erişilebilirlik snapshot'ı |
+| `web_console` | Son `web_goto`'dan beri console mesajları |
+| `web_network` | Son `web_goto`'dan beri istekler: method, status, tip, URL |
+| `web_tabs` | Açık sayfaları listeler, aktif olanı değiştirir |
+| `web_storage_state` | Cookie ve localStorage'ı okur ya da kayıtlı bir durumu geri yükler |
+| `web_extract` | Sayfanın makale içeriği Markdown (ya da metin) olarak |
+| `web_map` | Mevcut sayfadaki aynı-origin linkler, tekilleştirilmiş |
+| `web_crawl` | Sınırlı aynı-origin crawl, robots.txt'ye uyar, her sayfa `context_search` için indekslenir |
+| `web_press_key` | Bir tuşa basar, isteğe bağlı olarak bir elemana odaklanarak |
+| `web_select_option` | Bir `<select>` seçeneğini değer ya da etiketle seçer |
+
+### Context Index Araçları (3)
+
+| Araç | Açıklama |
+|------|----------|
+| `context_index` | Bir metin dosyasını SQLite FTS5 index'ine ekler; değişmemiş dosya no-op |
+| `context_search` | bm25 ile sıralanmış parçalar, her sonuçta kısa snippet ve chunk id |
+| `context_get` | Bir parçanın tamamı, dosyası ve satır aralığıyla |
+
+### Research Araçları (2)
+
+| Araç | Açıklama |
+|------|----------|
+| `research_search` | Brave ya da Perplexity üzerinden web araması, title / url / snippet'e normalize. Anahtar `BRAVE_API_KEY` ya da `PERPLEXITY_API_KEY`'den, asla argüman olarak değil |
+| `research_ask` | Perplexity Sonar'dan atıflı cevap. Anahtar `PERPLEXITY_API_KEY`'den |
+
+### Media Araçları (1)
+
+| Araç | Açıklama |
+|------|----------|
+| `media_frames` | Bir videodan anahtar kareler PNG olarak, benzerleri elenmiş. ffmpeg gerektirir |
+
+### Agent Araçları (2)
+
+| Araç | Açıklama |
+|------|----------|
+| `agent_run_steps` | ios / android / web / design adımlarından oluşan bir batch'i tek çağrıda çalıştırır, adım başına durum ve verdict döner |
+| `agent_query_output` | Satır içi dönemeyecek kadar büyük önceki bir çağrının kaydedilmiş tam çıktısını arar |
+
+### Security Araçları (2)
+
+| Araç | Açıklama |
+|------|----------|
+| `security_cvss_score` | Bir temel vektörden CVSS 3.1 skoru ve bandı, çevrimdışı |
+| `security_dep_inventory` | Bir lockfile'ı `{ecosystem, name, version}` listesine normalize eder, çevrimdışı |
 
 ### Kullanım Senaryoları