Log10x MCP

Progressive install wizard for the Log10x Reporter / Receiver on Kubernetes. **This is the SINGLE entry point for installs: call it first.** Do NOT call `log10x_doctor` or `log10x_login_status` as a pre-flight; the wizard handles login state, license acquisition, and demo-mode fallback internally, and surfacing the doctor's optional-capability warnings (Retriever, Datadog backfill, cross-pillar metrics) ahead of the install confuses users with concepts that are unrelated to deploying the Reporter/Receiver. Takes a `snapshot_id` from `log10x_discover_env` and walks the user through five decisions, asking one at a time and remembering each answer across turns (the snapshot's wizard session): (1) **app**, `reporter` (dedicated DaemonSet forwarder, zero-touch) or `receiver` (sidecar inside the user's existing forwarder); (2) **forwarder**, Receiver-only, auto-picked when one is detected, asked when multiple; (3) **backends**, array of metrics destinations, can be multiple (e.g., `["log10x", "datadog"]` to report to both SaaS + own backend simultaneously); (4) **airgapped**, opt-in, conflicts only with `"log10x"` in `backends` (engine sends NOTHING to log10x.com); (5) **license_jwt**, auto-fetched from `/api/v1/license/demo` if the user is not signed in, or from `/api/v1/license` with the persisted Auth0 token if they are. Each call merges new args into the session and either asks the next question (returning a markdown prompt) or emits the final install plan once all answers are in. Demo + airgapped surfaces a soft warning (engine downgrades to online mode on demo licenses). Plan is plan-only: emits helm commands + values.yaml; the user runs them. With `log_destination: "datadog"` a Receiver plan adds the step after the POC: the fleet default for every service with no rule (`fleet_default.action` tier_down to Flex, or offload to S3), with the Flex index and its `@routeState:tier_down` filter or the S3 branch, the always-pass sample, and what an error monitor sees. **Ti…

Given a DiscoverySnapshot (from `log10x_discover_env`), produce an install/verify/teardown plan for the Log10x Retriever. Unlike Reporter + Receiver, the Retriever has no forwarder choice: it is a standalone set of workloads (indexer + query-handler + stream-worker) that read source logs from object storage through a queue and serve an HTTP query endpoint. Two storage providers, picked by `storage_provider`: **aws** (S3 input bucket with an `indexing-results/` prefix, four SQS queues, an IRSA-annotated ServiceAccount), auto-detected from the discovery snapshot or supplied explicitly; **azure** (AKS, Azure Blob containers, four Azure Storage Queues, workload identity), where the chart's own `provision-retriever.sh` creates the resources and the plan quotes it. `blockers` carries the inputs a complete plan is still missing and the plan emits no steps while it is non-empty; the preflight table is the state report beside it, and a FAIL row there is reported, not a gate, so read `preflight_summary.fail` as well as `blockers`. Verify probes follow the provider: pods Ready, indexer processing, query endpoint responding, then S3 + SQS probes on aws and Blob + Storage Queue probes on azure. Teardown uninstalls the Helm release; on aws the S3 / SQS / IAM lifecycle stays with Terraform, on azure the last step runs the provisioning script with `--destroy` to delete the resource group it created.

Pre-flight readiness gate for cost-reduction tools. Verifies Reporter age (default 7d), pattern-coverage stability, and absence of acute anomalies before configure_engine / estimate_savings should run. Returns structured `not_ready` with the specific gate(s) that failed.

Weekly aggregate against a commitment record opened by `log10x_configure_engine`. Reports delivered bytes (and dollars at the contract rate where the contract allows), projects the next 90 days from a weak Beta(2,2) prior updated with weekly evidence, and renders a markdown summary suitable for sharing. REQUIRES a commitment record opened by a prior configure_engine apply; without one there is no baseline to report against.

Compile a symbol library from any mix of sources, waiting inline for the result when it is quick and handing back a pollable `job_id` when it is not. It waits up to `max_wait_ms` (default 45s): a small compile, and EVERY re-run (which reuses prior units via the pinned output folder), finishes inside that window and returns the finished library plus the full scan/link diagnostics in ONE call; a long first compile of a large tree overruns the wait and returns a running `job_id` to poll with log10x_compile_status, or just call this tool again later, since the output is pinned and a finished run is returned by the next call. `max_wait_ms: 0` returns the job_id immediately (fire-and-forget). Sources combine freely: a local folder of source code / binaries (`source_path`), GitHub repositories via the GitHub REST API (`github_repos`, with optional `github_branch` / `github_folders`), docker/OCI images (`docker_images`), Helm charts (`helm_charts`), and Artifactory artifacts (`artifactory_instance` + `artifactory_repo`, with `artifactory_files` / `artifactory_folders`). The run scans the sources (Java, Go, Python, JS/TS, Scala, C/C++, C#, plus binaries) and writes per-file `.10x.json` symbol units plus a single linked `.10x.tar` library, the AOT artifact the 10x runtime later uses to assign hidden classes (TenXTemplates) to events. GitHub pull REQUIRES a token even for public repos: pass `github_token` or set GH_TOKEN; without one the tool returns not_configured. Docker-image pull is daemonless (podman bundled in compiler-10x, `--cap-add SYS_ADMIN` granted automatically) and public images need no credentials. Helm pull is a meta-source (renders the chart, by default also pulls the images it references); OCI/URL chart refs resolve standalone while a bare `repo/chart` needs a matching `helm_repos` entry. Artifactory pull needs a token (`artifactory_token` or ARTIFACTORY_TOKEN). REQUIRES the COMPILER flavor: runs `log10x/compiler-10x @apps/compiler` by default, or a local com…

Link an existing folder of `.10x.json` symbol units (from a prior compile) into a single `.10x.tar` library, with NO source scan. This is the same compiler-flavor Compiler app invoked with link-only arguments: the units folder is the `outputSymbolFolder` and no source is mounted, so the engine reuses the units already on disk (scans 0 new files) and merges them into the library, which is written into that same folder. Like log10x_compile it waits inline up to `max_wait_ms` (default 45s; linking is usually fast, so it normally returns the linked library in ONE call) and otherwise hands back a `job_id` to poll with log10x_compile_status. Use it to re-link after editing or pruning units, to assemble a library from a units tree built piecemeal, or to rebuild a library from the output folder of a prior log10x_compile. REQUIRES the COMPILER flavor (runs `log10x/compiler-10x @apps/compiler` by default, or a local compiler-flavor `tenx` with mode="local"; an engine reporting the flavor as `cloud` is accepted, the native runtime build is refused). No Kubernetes or Log10x account needed.

Poll an asynchronous compile started by log10x_compile (or a link started by log10x_compile_link), by its `job_id`. Returns `job_status` (running / completed / failed / timed_out), the units produced so far + the linked `.10x.tar` (path + size), elapsed time, the engine exit code, and a credential-redacted tail of the engine log. Crucially, it promotes the engine's scan/link DIAGNOSTICS into the envelope so the compiler is not a black box at 100k to 500k file scale: per-language scan-failure counts with capped failure samples (which files failed to parse and why), and the link report (units merged / skipped, files excluded by folder/name filter, and the symbol-type histogram: class / enum / log / exec). Those appear once the compiler-10x image carries the engine diagnostics change; on an older image the tool degrades to unit counts + the log tail. The first terminal poll captures the exit code into the job record and frees the container; later polls stay readable and the compiled library is never removed.

CALL THIS after the user picks 'show me what cutting costs would look like' from log10x_start. At Receiver/Retriever tier returns the 6-mode outcome-first menu (drop / sample / compact / tier_down / offload / observe_only), each gated by the customer's detected capabilities (receiver tier, SIEM type, offload bucket). At Reporter-only or Dev tier, collapses to 2 entries: observe_only + install_receiver (with prose explaining that the full 6-mode menu requires the Receiver in-path). All non-observe modes route to log10x_explain_mode. The envelope carries must_render_verbatim (show to user as-is), must_ask_user (numbered question), and forbidden_next_actions (do not call estimate_savings, configure_engine, or pattern_mitigate until the user picks). Accepts siem_lens (what-if destination): keeps the measured volumes, prices + gates for that destination at list rates, and stamps siem_actual vs siem_lens in the envelope.

Low-level PromQL passthrough to the customer metric backend configured via LOG10X_CUSTOMER_METRICS_URL. Returns the raw Prometheus response shape plus metadata about which backend served the query. This is the escape hatch for cross-pillar investigations the higher-level primitives don't cover: use it to explore the customer backend's label universe, run a one-off PromQL expression, or verify that a specific metric exists before correlating against it. For typical cross-pillar workflows, compose the deterministic primitives: `log10x_metrics_that_moved` → `log10x_rank_by_shape_similarity` → `log10x_metric_overlay`.

Weekly change report for a Datadog install, read from the per-pattern series the engine's Datadog metric output publishes (`emitted_events_summaryVolume`, tagged message_pattern, tenx_hash, k8s_container, tenx_user_service, routeState, and tenx_team once the team label ships). Lists the statements new in a service since `since` (a duration like `7d` or a date; stateless, so pass the previous report's `next_since` to continue), each with lines a day, estimated Standard indexing cost a month at Datadog list price, whether a rule held it, and the rule that did (the container's row and action in caps.csv / actions.csv, read from the gitops repo or the policy ConfigMap). Ends with proposed per-service rows in the plan's form: "<service>: any statement above N lines a day goes to Flex. Today that is these K statements, about $X a month." `view: "monitors"` instead renders two Datadog monitor definitions as JSON for the account owner to apply: a metric monitor that fires when a statement's route turns tier_down or offload, and an anomaly monitor with weekly seasonality that fires when a statement's volume rises above its weekly baseline. Read-only: Datadog's query API with DD_API_KEY / DD_APP_KEY / DD_SITE (GET only), and the engine files. Writes nothing.

Prices an account's log spikes from Datadog's estimated usage metrics, with no 10x install. Reads `datadog.estimated_usage.logs.ingested_events` (datadog_is_excluded:false, by service and datadog_index) and `datadog.estimated_usage.logs.ingested_bytes` (by service) in hourly sums over `lookback` (default `90d`). An hour is a spike hour for a service when its indexed events exceed `spike_multiplier` (default 3) times the median of the same hour over the 7 days before; consecutive hours are one spike, and a service's first 7 days set its baseline. Each spike's excess events are priced at the Standard rate (list $1.70 per million, `standard_rate_per_million` overrides) and its excess bytes at ingestion (list $0.10 per GB, `ingestion_rate_per_gb` overrides). Estimates what a fleet default limit, `headroom` (default 2) times the service's largest hour outside its spikes, would have held, as an upper bound. Returns services by spike cost, each spike (start, hours, index, excess events, cost, held), the total a year at that rate, and the caveats. Read-only: Datadog's query API with DD_API_KEY / DD_APP_KEY / DD_SITE (GET only). Writes nothing.

Given a pattern identity, generate commands to scan the user's SIEM/observability stack (Datadog monitors, Splunk saved searches, Grafana dashboards, Prometheus alert rules) for anything that depends on that pattern. **Call this before any mute, drop, or source-code deletion**: deleting a log line that feeds a live alert silently breaks the alert. Also call when a developer asks "am I allowed to delete this log.info() call" or "what references this pattern".

Read-only discovery of the caller's Kubernetes cluster + AWS account: i.e. the customer's INFRASTRUCTURE environment, NOT their Log10x account. **When the user wants to install Log10x: call this tool FIRST and then `log10x_advise_install`, that's the whole pre-flight. Do NOT call `log10x_doctor` / `log10x_login_status` / `log10x_savings` / etc. before the install; the wizard handles all login + license logic internally, and surfacing those tools' optional-capability warnings (Retriever, Datadog backfill, cross-pillar metrics) makes the install feel more complicated than it is.** Probes kubectl (workloads, DaemonSets, Helm releases, service-account IRSA annotations, metrics-backend agents) and AWS (EKS, S3, SQS, CloudWatch log groups) to detect: which forwarder is running (Fluent Bit, Fluentd, Filebeat, Logstash, OTel Collector, Vector), which log10x apps are already installed (Reporter, Receiver, Retriever), and which metrics backends are already deployed (Datadog Agent, Prometheus, Elastic, CloudWatch Agent, etc.). Returns a terse markdown report + a `snapshot_id` (cached 30 min) the advisor tools consume. **Do NOT call this tool to answer "which Log10x environments do I have access to" / "list my envs" / "switch envs": those are about the user's Log10x ACCOUNT environments, use `log10x_login_status` for that.** Call THIS tool only when the question is about k8s workloads, AWS infra, or "what's deployed in my cluster". Every shell call is logged in the snapshot's `probeLog` for audit. No writes, no state mutation: only `kubectl get` and `aws ... describe/list` verbs. **Tier prerequisites**: none, this is a pre-install tool and runs against any customer environment.

Auto-discover the structural join label between Log10x pattern metrics and the customer metric backend. Runs Jaccard similarity on label value sets across candidate label pairs, returns the best pair above the 0.7 threshold plus runner-ups above 0.5. The result is cached per-session keyed by (environment, customer-backend-endpoint) so the cross-pillar primitives (metrics_that_moved, rank_by_shape_similarity, metric_overlay) can auto-run this once at session start and reuse the cached join without re-probing. Agents should normally NOT need to call this tool directly: the primitives call it internally. The explicit tool exists for power users who want to inspect the join universe or force a re-discovery after backend changes. When no pair crosses the threshold, returns a structured `no_join_available` response with the full probed-label matrix and recommended next actions.

List the labels Log10x metrics can be filtered or grouped by. Call at the start of a session, or before calling any tool that takes a label/filter argument: stops the model from guessing label names like "namespace" when the label is "k8s_namespace". Pass a label name to get its distinct values.

Run a startup health check on the Log10x MCP installation. Probes: environment configuration validity, prometheus.log10x.com reachability and auth, Reporter tier detection (Edge / Cloud / none), Retriever endpoint configuration (informational), Datadog destination credentials (informational), paste endpoint reachability, cross-pillar enrichment floor (v1.4, when LOG10X_CUSTOMER_METRICS_URL is set). Returns a markdown report with pass / warn / fail per check and remediation hints. Call this once at the start of a session to verify the install, or any time a tool returns an unexpected error to isolate whether the problem is configuration or transient.

Render a read-only shell script that exports a log sample out of the user's OWN log analyzer, with the user's OWN credentials, on a machine the user chooses: and then stop. This server does not run the script and, in the fenced profile, could not: it runs inside a container started with `--network none`. That split is the point. Code that sees log data has no network; code that has network is the user's own `aws` / `curl` driven by a script short enough to read once. Use this as step 2 of the fenced POC (step 1 is minting the licence with one visible curl, step 3 is running `log10x_poc_from_local` inside the fenced container over the exported files, step 4 is verifying the fence with `docker inspect` and by turning Wi-Fi off). Also use it whenever the credentials live somewhere this process does not: a jump host, a locked-down laptop, another team. Args: siem (required: cloudwatch / splunk / elasticsearch / opensearch / datadog), window (default 14d), target_event_count (default 1,000,000, the same default `log10x_poc_from_siem_submit` uses, so both paths sample the same size), scope, query, output_dir (default ./poc/logs), write_script (default true, writes export-sample.sh mode 0755 in the working directory). Returns the script text, the read-only API operations and credential variables it touches, a review checklist, and the exact `log10x_poc_from_local` arguments to call next. The sampling matches `log10x_poc_from_siem_submit` bucket for bucket (same stratified sub-windows, same per-bucket cap) so a fenced POC and a credentialed POC over the same window differ because the logs differ. Emitted scripts contain no log10x hostname; the server refuses to return one that does. Read-only: it renders text and writes one script file; it contacts nothing.

Compare the stored env-config document against the `LOG10X_*` environment variables the env-var bridge would have produced, and report per-field disagreements with remediation recommendations. **Call this when** the user says "but I set the env var" or downstream tools report a value the user thinks they overrode: the on-prem store wins over env vars per resolver precedence, and silent-override is the most common boot-time surprise. Args: `env_id` (required, env_id UUID or nickname). For each disagreeing field (env_id, nickname, cluster.*, destination.*, streamer.*, retriever.*, offload_destinations[0].*), returns `{ field, stored, envvar, recommendation }`. The recommendation tells the user to either unset the LOG10X_* env var (preferred: on-prem store is the source of truth) or to update the stored doc via the matching setter (log10x_dest_set for destination, log10x_set_gitops_repo for gitops). Pure-on-prem-store configs (no LOG10X_* env vars set) return ok:true with an empty diff and a note that no ambiguity is possible.

Run schema validation + cross-field sanity checks on a stored env-config document at `~/.log10x/envs/<env_id>.json`. **Call this** after any edit to the env doc (via `log10x_dest_set` / hand-edit / restore) or pre-flight before downstream tools that need a coherent config (commitment_report, configure_engine, offload-recipe emitters). Args: `env_id` (required, env_id UUID or nickname). Returns the canonical zod schema parse result PLUS findings across: destination.region required for vendors that need it (cloudwatch / datadog / azure-monitor / gcp-logging); ingest_url shape sanity (http(s):// prefix, splunk /services/collector suffix); streamer.url / retriever.url shape; cluster cloud type vs offload destination type alignment (eks↔s3, gke↔gcs, aks↔azure_blob); at-least-one active offload destination; SIEM region vs offload destination region (cross-region egress warning). Each finding carries severity (error / warning / info) and a remediation recommendation. Errors block downstream actions; warnings/info surface for the user.

[FRESH-SESSION ROUTING: if this is the user first cost question of the session, call log10x_start first instead, it returns the orientation menu the user needs before any per-tool action.] Two-mode savings estimator with percent-first reporting and a dollar overlay. `forecast` projects bytes_in -> bytes_out and percent reduction for a proposed plan; pass `effective_ingest_per_gb` (or rely on the account profile list-price rate) to overlay $/mo per pattern and in totals. `verify` counts realized savings from the engine `routeState` label over a window with cap-hit / drift / new-patterns / leakage attribution, leading with percent and adding the dollar overlay only when a rate is set. Without a rate, dollar fields are emitted as null (never as a fabricated $1/GB number); the envelope carries `rate_source: list_price | customer_supplied | unset` so callers can show how the overlay was derived. Accepts siem_lens (what-if destination): keeps the measured volumes, prices + gates for that destination at list rates, and stamps siem_actual vs siem_lens in the envelope. REQUIRES Reporter-tier cost attribution (per-pattern bytes in the metrics backend). Before anything is deployed, use log10x_poc_from_local or log10x_poc_from_siem_submit instead.

Resolve a raw log line or pattern name to its pattern hash, which is the same for the same line under the same engine, symbol library and configuration, then return byte volume + share per service (with cost overlay when $/GB is set), before→after delta, first-seen timestamp within the observation window, and the current offload disposition (pass / sample / compact / drop) read from the Reporter `routeState` label; only when `LOG10X_AI_SUMMARY=true`, an AI category for the pattern (error/debug/info/metric/health) with a one-line explanation. **Call this first** whenever a user pastes a SINGLE log line and asks "what is this", "is this new", "is this safe to drop", or "is this being dropped / offloaded". The lookup is structural, not byte-exact: different timestamps/request IDs/user IDs on the same underlying pattern resolve to the same hash. If no match is returned, say so. Use log10x_resolve_batch instead when the user pastes MULTIPLE events, a SIEM dump, or a batch to triage.

CALL THIS AFTER log10x_cost_options when the user picks a mode. Explains the chosen enforcement mode (drop / sample / compact / tier_down / offload / observe_only) in service-level plain language, with dollar math when byte metrics are available. Returns must_render_verbatim (plain-text three-section card, no markdown), must_ask_user (Apply or Preview choice), and forbidden_next_actions (locks apply tools and log10x_preview_filter until the user picks). routes_to.apply routes all non-observe modes to log10x_configure_engine; observe_only has routes_to.apply === null (no enforcement step). routes_to.preview routes to log10x_preview_filter with { service, mode }.

Extract the structural template library from a set of log lines by running a local Log10x pipeline on the user's machine. Returns per-template records (the engine-internal templateHash + the template body with variable slots) and event count. Companion to `log10x_resolve_batch`: both tools answer 'can you run log10x locally / templatize these events'. Does NOT need Kubernetes, a deployed Reporter, or a Log10x account; the pipeline runs in-process on the host via either a locally-installed `tenx` binary or a `docker run log10x/pipeline-10x` container. Use for: (a) bootstrapping a pattern catalog before wiring up a Reporter, (b) offline auditing of stored log files, (c) validating that a config change produces expected template identities. **Validation mode**: pass `expected.min_templates`, `expected.required_patterns`, and/or `expected.forbidden_merges` to turn extraction into assertion-checked validation, each assertion reports PASS/FAIL in the output. REQUIRES a local engine: the tenx binary on PATH, or Docker with LOG10X_TENX_MODE=docker. No preflight checks for it: log10x_doctor does not probe the engine.