[Feature Request]: Documentation retrieval tools (public API reference + auth-walled product docs)

[dv-chrestman]

Feature Description

falcon-mcp has no documentation-retrieval tool. An agent connected to the server can query the tenant in depth (29 modules today) but cannot look up CrowdStrike's own documentation — it has to fall back on whatever the model memorized, which for a platform that ships API changes continuously is the weakest link in the chain.

I'd like a docs module. Concretely, two capabilities, in priority order:

1. API reference lookup (no credentials required).
developer.crowdstrike.com already publishes an LLM-addressable mirror of the entire API reference:

• https://developer.crowdstrike.com/llms.txt
• https://developer.crowdstrike.com/llms-full.txt — 1468 operations, each with method, path and required scope (~380 KB)
• a .md variant of every reference page, e.g. https://developer.crowdstrike.com/api-reference/operations/QueryDevicesByFilter.md, which returns method, path, **Scope:** Hosts: READ, the parameter list, and a FalconPy example in under 1 KB
• https://developer.crowdstrike.com/api-reference/operations-by-collection.md

All of the above are public, unauthenticated, 200, and already clean Markdown. Two tools over that surface — search the operation catalogue, fetch one operation page — need no new credentials and no new scopes.

2. Product documentation search (credentialed).
The product documentation is a different story, and this is the part I can't solve on my own:

• https://falcon.<region>.crowdstrike.com/documentation/page/<id>/<slug> returns the Falcon login page to any non-browser client — it's an Ember SPA behind a console session cookie.
• https://docs.crowdstrike.com is a Fluid Topics instance (<meta name="ft-tenant-base-url" content="https://docs.crowdstrike.com/">). Its REST API is live but gated: GET /api/users/me → 401 {"error":"Unauthorized","message":"Required Authentication"}. Fluid Topics documents search/maps/topics endpoints and JWT + SSO auth, so there is a real machine-readable docs API here — just not one a Falcon API client can reach.
• The Falcon API itself has no documentation collection. I went through all 128 collections / 1468 operations in llms-full.txt: the only near-miss is Knowledge Bases / Knowledge Base Files (/agentic-studio/..., scope Charlotte AI Agent Definition), which is the customer-authored corpus for Charlotte AI agents, not CrowdStrike product docs. FalconPy's 135 endpoint modules confirm the same.
• The regional Swagger spec is not public either — https://assets.falcon.crowdstrike.com/support/api/swagger.json returns 403 MissingKey ("Missing Key-Pair-Id query parameter or cookie value"), i.e. a signed CloudFront URL minted by a console session.

So: an OAuth2 API client pair — the only credential falcon-mcp holds — cannot retrieve CrowdStrike product documentation today. If that's something CrowdStrike would consider exposing (a docs search operation under an existing or new scope, or a documented way to use a Fluid Topics token alongside the Falcon creds), it would make part 2 buildable. If not, I'd rather know that than keep guessing, and part 1 still stands on its own.

Use Case

As a security engineer driving falcon-mcp from an agent, the failures I hit are documentation failures, not API failures:

• Scope errors. An agent picks a tool, the call 403s, and the fix is knowing the exact scope string. Today that lives in a hand-maintained mapping inside this repo — which is precisely what [Bug]: Generated module docs under-report required API scopes when a tool names its operation through a constant #545, Operation names in mixin files are invisible to doc scope detection #552 and exclusions and policies tools document no required scopes at all #553 were about. A live lookup against developer.crowdstrike.com, where the scope is stated on every operation page, turns that from data this project has to keep correct into data it can read.
• Reaching past the MCP. When no tool covers what I need, the next step is a direct FalconPy/REST call. Right now the agent guesses the operation ID, path and parameters from memory. With an API-reference tool it can look up operations-by-collection.md, confirm the operation exists, and get the signature — in the same session, without me leaving to open a browser.
• Product behaviour, not just endpoints. Half my questions aren't "what's the endpoint" but "what does this prevention-policy setting actually do", "what does this sensor status mean", "what are the documented limits on RTR". Those answers are only in the product docs. That is the auth-walled half above, and it's the half I'd get the most out of.

The distinctive thing here is that the credential is already in the room. I'm authenticated to the tenant; the docs I need are gated by the same subscription I'm authenticated against. Making the server able to read them is a much shorter path than any external docs mirror.

Related Module/Area

New module needed

Proposed Solution (Optional)

A docs module, with part 1 shippable independently of part 2:

falcon_search_api_reference(query, collection=None, limit=20)
    -> [{operation_id, method, path, scope, summary, doc_url}]
    Backed by developer.crowdstrike.com/llms-full.txt (or operations-by-collection.md),
    fetched once and cached. No auth.

falcon_get_api_operation(operation_id)
    -> full operation page (params, scope, example)
    Backed by /api-reference/operations/<OperationId>.md. No auth.

falcon_search_product_docs(query, limit=10)      # part 2, gated
falcon_get_product_doc(doc_id)                   # part 2, gated
    Backed by the docs.crowdstrike.com Fluid Topics API, registered only when a
    docs credential is configured, and absent from tools/list otherwise.

Notes on fit with existing conventions:

• Part 1 introduces the server's first outbound call to a host other than the Falcon API. That's a real design decision, not a detail — it wants an opt-out (the module is already opt-in via --modules), and it needs to honour the existing proxy configuration from [Feature Request]: Add proxy configuration support for outbound Falcon API connections #405.
• Alternatively part 1 could ship as MCP resources rather than tools, alongside the existing falcon_mcp/resources/*.py FQL guides. Resources are the closer analogue — they're reference material, not actions. Tools are the better fit only because the operation catalogue is too large to hand to a client wholesale; it needs a query. Happy to go either way.
• Part 2 must degrade silently. A tool that's registered but always 401s is worse than one that isn't there.

Alternatives Considered (Optional)

• Point a generic web-fetch tool at the docs. Works for part 1 and is what I do now, but it means the agent has to already know the URL scheme, and it does nothing for part 2 — an unauthenticated fetch of a /documentation/page/... URL returns the login page, which the model then cheerfully summarizes as though it were documentation. That failure is silent, which is what makes it worth fixing inside this server.
• Widen the embedded resources/*.py guides into a full docs corpus. Doesn't scale, and it recreates the staleness problem this request is trying to remove.
• A separate CrowdStrike docs MCP server. Cleaner separation, but it splits the credential story across two servers for what is, from the agent's point of view, one platform. I'd rather it lived here — though if CrowdStrike would rather ship it standalone, that answers the question just as well.
• Scrape the console with a session cookie. Explicitly not proposing this. It's fragile, it's not a supported interface, and it isn't something this server should be doing.

Additional Context (Optional)

Everything above was verified against the live endpoints on 2026-08-31, from a US-2 tenant.

Related open issues: #522 (CAO hunting saved queries and guides) touches adjacent ground — surfacing CrowdStrike-authored hunting content — but through the tenant API rather than the documentation. #440 (making resources/*.py the single source of truth for FQL hints) overlaps with the "resources vs tools" question in part 1.

Happy to open a PR for part 1 if the approach and the outbound-host question look acceptable. Part 2 I can't build without a supported way in, which is really what I'm asking about.