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).

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

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

Not published to PyPI, so pip install bigfix-root-mcp will not find it. Install from a release - every release since v0.1.3 attaches a wheel and an sdist, with a SHA256SUMS.txt to check them against:

pip install https://github.com/jgstew/bigfix-root-mcp/releases/download/v0.1.3/bigfix_root_mcp-0.1.3-py3-none-any.whl

(the asset name carries the version, so bump both halves of that URL for a newer release)

Or straight from the repository:

uvx --from git+https://github.com/jgstew/bigfix-root-mcp bigfix-root-mcp

From a checkout (uv required, 0.12+):

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

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: verification is off by default to match besapi; set BES_SSL_VERIFY=true (or a CA bundle path) for anything beyond a lab.
• Generic BigFix logic here is written to be upstreamed into besapi - see docs/besapi-proposals.md.

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.