bigfix-root-mcp

A minimal, read-only MCP server around the besapi library, exposing the HCL BigFix root server REST API to MCP clients. Built on FastMCP 4 (stateless). Session relevance is evaluated with bigfix-remote-session-relevance (see Session relevance); every other REST call goes through besapi.

Focus: session relevance queries (data the server already has) and client fast query (live questions answered by BigFix agents), plus a few read-only helpers.

Strongly recommend using the official BigFix Platform MCP server instead: https://help.hcl-software.com/bigfix/11.0/platform/Platform/MCP/c_introduction.html

The capabilities of this MCP server are intentionally limited, where as the official one is not.

Tools

Relevance analysis (advisory)

The relevance-taking tools statically analyze their relevance with bigfix-relevance-analyzer before sending it (dialect pinned per tool). The analysis is advisory only: even a query the analyzer rejects still goes to the server, because the analyzer's inspector table is a snapshot - an unknown inspector there may still exist on the live server. When there are findings, the response carries an analysis key (findings, suggestions, dialect mismatch); a clean query adds nothing. Server-side relevance errors gain a Static analysis: appendix with the findings and did-you-mean suggestions, so a typo'd inspector is a one-round-trip fix.

qna fast evaluation

Registered by default; absent when every target source is disabled - see qna evaluation.

Write tools (opt-in)

Absent unless BIGFIX_ALLOW_WRITES is set - see Writes.

Result bounding

Every tool that can return an unbounded payload is windowed and says so. List-shaped tools take limit/offset and report returned, total_available and truncated; blob-shaped tools report truncated and total_chars, and drop an oversized payload rather than cut it into something that looks complete.

This is not optional politeness: BigFix relevance has no row-limiting operator (first, firsts, items, elements are all undefined), so bounding the response is the only way to bound a result. find_content on the reference deployment matches 12,395 fixlets.

Resources and prompts

Relevance is the hard part, so the server ships reference material clients can pull on demand rather than repeating it in every tool description:

Prompts: diagnose_computer, patch_status, find_stale_agents, troubleshoot_relevance.

Relevance errors also carry a cause hint: the server recognizes the common failure shapes (a non-existent limiting operator, client relevance in a session query, singular-vs-plural) and appends what to do instead, so a bad expression is a retry rather than a dead end.

Client fast query semantics

Client queries are answered by live agents: results accumulate at /api/clientqueryresults/{id} over seconds to minutes as clients report in, and there is no completion flag. The client_query tool polls with three termination heuristics (reported in stop_reason):

1. expected_count_reached - as many distinct computers reported as targeted;
2. results_stable - no new computers for stable_polls consecutive polls;
3. timeout - partial results at timeout are a normal outcome (offline agents never report), not an error.

For long waits, use client_query_submit then client_query_results repeatedly instead of a single blocking call.

Configuration

Environment variables win over config files:

Config files are searched in besapi's order: /etc/besapi.conf, ~/besapi.conf, ~/.besapi.conf, ./besapi.conf - same [besapi] section format as besapi/bescli, so an existing config just works. Prefer keeping credentials in ~/besapi.conf over MCP client config files.

Example MCP client config (see .mcp.json):

{
  "mcpServers": {
    "bigfix-root": {
      "command": "uvx",
      "args": ["bigfix-root-mcp"]
    }
  }
}

Install / run

Published on PyPI. Requires Python 3.11+.

With uv (preferred)

No install step - uvx fetches and runs it in a throwaway environment, which is also what the MCP client configuration above uses:

uvx bigfix-root-mcp

To keep it on PATH instead, as a managed tool:

uv tool install bigfix-root-mcp
bigfix-root-mcp

With pip

pip install bigfix-root-mcp
bigfix-root-mcp               # or: python -m bigfix_root_mcp

From a checkout

uv 0.12+ required:

uv sync
uv run bigfix-root-mcp        # or: uv run python -m bigfix_root_mcp

Verifying a download

Every release since v0.1.3 also attaches the wheel and sdist with a SHA256SUMS.txt, checkable with sha256sum -c SHA256SUMS.txt.

Smoke test against a live root server with MCP Inspector:

npx @modelcontextprotocol/inspector bigfix-root-mcp

then call whoami, session_relevance_query with number of bes computers, and client_query targeting a known computer ID.

Operator scope

Every result is limited to what the configured REST operator can see. Only a master operator has full visibility; a regular operator can never be certain its view is complete, and cannot distinguish "does not exist" from "outside my scope". So number of bes computers returning 35 means 35 computers visible to this operator - a lower bound, not the BigFix total.

whoami reports is_main_operator for exactly this reason: check it before treating any result as the full state of BigFix. The tool descriptions carry this caveat so LLM clients don't overstate scoped results.

Safety and design notes

• Read-only by default: with BIGFIX_ALLOW_WRITES unset, only read tools are registered - the write tools do not exist as far as any client can tell. One nuance: submitting a client query does create a query object server-side, but agents only evaluate relevance against it - no managed-endpoint state changes.
• Client fast query is a powerful read. client_query with target_all evaluates arbitrary client relevance on every agent the operator can see, and the BigFix agent runs as SYSTEM/root. That can read file contents, registry values and process lists fleet-wide, and the results come back in the tool response. Scope the configured operator to the smallest useful set of computers; whoami.is_main_operator tells you which you have.
• Explicit site paths: this server never uses besapi's mutable "current site path" connection state (set_current_site_path / get_current_site_path - a bescli convenience); tools that need a site take a required site_path parameter.
• Stdout hygiene: stdout belongs to the MCP stdio transport; all logging goes to stderr, and config loading avoids besapi helpers that print.
• TLS: with BES_SSL_VERIFY unset (or tofu), session relevance trusts on first use: a CA-valid certificate is used as is, a self-signed one (the BigFix default) is pinned on first contact in ~/.bigfix/.remote_session_known_certs.toml - shared with the bigfix-remote-session-relevance CLI - and a different certificate later is refused before any credentials are sent. Remove the entry (or run bigfix-remote-session-relevance --forget-cert HOST:PORT) once a legitimately changed certificate is verified out of band. The besapi tools have no pinning and stay unverified in that mode, matching besapi. An explicit false turns verification off for both; true (honouring REQUESTS_CA_BUNDLE / CURL_CA_BUNDLE) or a CA bundle path verifies both and pins nothing - use one of those for anything beyond a lab. HTTPS_PROXY / NO_PROXY are honoured by the besapi tools only; session relevance connects directly.
• Generic BigFix logic here is written to be upstreamed into besapi - see docs/besapi-proposals.md.

Session relevance

session_relevance_query, find_computers and find_content evaluate through the REST backend of bigfix-remote-session-relevance, using the same connection settings as everything else (env vars or besapi.conf); its own ~/.bigfix config, certificate pinning and deployment discovery are not used. The reason is the root server's behaviour when it can reach a BigFix Explorer: it forwards /api/query to Explorer, which rejects besapi's double-encoded form post with "This expression contained a character which is not allowed" - in practice any query containing a space. The library sends a JSON body first and falls back to besapi's form encoding only when the server answers "no reachable BigFix Explorer", so both setups evaluate the query exactly as written.

qna evaluation

bigfix-remote-client-relevance is a base dependency, so evaluate_client_relevance_qna / list_qna_targets are registered by default; they are absent only when both target sources are off (no BIGFIX_QNA_INVENTORY and BIGFIX_QNA_CONTAINERS=0). The [qna] extra still exists so older install commands keep working, but adds nothing. It evaluates client relevance with the BigFix qna binary on lab targets in about a second per warm run - the fast half of the feedback loop next to the advisory analysis.

What it is not: qna runs on the target machine, not through the BigFix deployment. No operator scope, no site subscriptions, no client settings - inspectors that depend on deployment state will differ from client_query. Iterate here, confirm on real agents with client_query. (The package's Fast Query transport is an upstream stub; this server does not expose it.)

Targets are deliberately constrained:

• Container images (ubuntu:22.04, ...) may be passed by the caller; needs docker or podman on the server host. First use of an image is slow (agent artifact download + derived image build); later runs are ~1s. Set BIGFIX_QNA_CONTAINERS=0 to forbid these.
• Inventory hosts come only from an admin-configured hosts.toml named by BIGFIX_QNA_INVENTORY (the package's inventory format: ssh/local/container entries). The MCP client can pick entries by name but can never supply ssh hosts, users, or become flags of its own.

Security notes: qna executes on the targets; the controller downloads BigFix agent artifacts from support.bigfix.com (SHA256-verified against the release site's sums) on first use of a version, so the server host makes outbound requests; every run leaves a BIGFIX QNA audit line on stderr.

Writes

Set BIGFIX_ALLOW_WRITES=true to register the three write tools. The flag controls registration, so with it off there is nothing to call.

Two guardrails apply to all of them:

• dry_run defaults to true. The response describes the call that would be made and nothing is sent. A write only happens on an explicit dry_run=false.
• Every attempt is audit-logged to stderr as one BIGFIX WRITE line with the operator, target, dry-run flag and outcome.

The set is limited on purpose to operations whose blast radius is reversible or nil. import_bes_content creates content; it does not run it - a fixlet imported this way does nothing until somebody deploys an action against it in the console.

Not implemented, and not to be added without their own design round: deploying actions (POST /api/actions), any DELETE, creating sites or operators, and file upload. Deploying an action is arbitrary code execution as root across the fleet, which is a different category of risk from anything here.

Documentation

Development

Requires Python 3.11+ and uv 0.12+. uv sync creates .venv from the committed uv.lock and installs the dev dependency group; no manual venv or pip install -e step.

uv sync
uv run pytest

Linting, formatting, type checking and the packaging checks all run through pre-commit (ruff, mypy, bandit, slyp, zizmor, and the uv lock/build checks). Install both hook types - some checks are deliberately deferred to pre-push because they are too slow to want on every commit:

uv run pre-commit install --hook-type pre-commit --hook-type pre-push

Useful invocations:

uv run pre-commit run --all-files                    # the commit-stage hooks
uv run pre-commit run --all-files --hook-stage manual  # everything, as CI runs it

Tests run entirely offline against a scripted fake BESConnection, including in-memory end-to-end MCP calls via fastmcp.Client.