v0.5.0

What's Changed

• Added discovery-time auth for protected OpenAPI and docs URLs.
• detect_openapi, list_endpoints, get_endpoint_details, trace_parameter_usage, and find_related_endpoints now accept an optional auth object.
• call_endpoint now reuses the provided auth while loading protected specs before executing the target endpoint.
• Discovery fetches support Basic auth, Bearer tokens, API keys, and custom headers.
• Discovery auth is scoped to the same origin as the input URL, including Laravel Request Docs fallback paths and same-origin remote $ref files.

Validation

• Added coverage for protected Laravel Request Docs discovery with Basic auth.
• Verified against a live Basic Auth protected Request Docs URL.
• npm run check

@rekl0w/mcp-openapi-discovery v0.4.0 is a minor release focused on more reliable real-world endpoint execution and smoother discovery when users paste API endpoint URLs instead of documentation URLs.

This release adds broader query-string support for endpoint calls and makes OpenAPI discovery more forgiving by falling back from a deep endpoint URL to the origin root page when the exact URL does not expose a spec.

Highlights

• Added safer query support for call_endpoint, including embedded query strings in endpoint paths
• Added support for raw query strings in MCP input, such as "page=2&status=open"
• Added OpenAPI-aware query serialization for arrays and objects, including form, deepObject, spaceDelimited, pipeDelimited, and Swagger 2 collectionFormat
• Fixed query API key authentication so query-based API keys are applied to the actual outgoing request URL
• Added masking for sensitive query values in request summaries
• Added discovery fallback when users provide a concrete endpoint URL, such as https://abc.com/asd/bsd/cds, by trying the exact URL first and then falling back to https://abc.com/
• Added regression coverage for query execution edge cases and endpoint-URL-to-root discovery fallback

What changed

Added: query support for endpoint execution

call_endpoint now handles query values more robustly across several common real-world inputs.

The tool can now accept query parameters as:

• an object, for example { "page": 2, "status": "open" }
• a raw query string, for example "page=2&status=open"
• URLSearchParams
• repeated tuple-style entries

It also supports query strings embedded in the path value itself, such as:

• /items?status=active&tag=red

Previously, this kind of input could be treated as part of the path and produce malformed URLs. The request builder now separates the endpoint path from the query string before creating the final request URL.

Added: OpenAPI-aware query serialization

Query serialization now uses metadata from the discovered OpenAPI parameter definitions when available.

Supported query styles include:

• repeated form values, such as tag=red&tag=blue
• form with explode: false, such as fields=id,name
• spaceDelimited
• pipeDelimited, such as include=comments|stats
• deepObject, such as filter[owner]=me
• Swagger 2 collectionFormat values: csv, ssv, tsv, pipes, and multi

This makes generated calls much closer to what real APIs expect when they document non-trivial query parameters.

Fixed: query API key authentication

API key security schemes using in: query are now synchronized back into the actual request URL before fetch is called.

Previously, query API keys could be applied to the internal auth state but not make it into the outgoing URL in some flows. The request summary now also masks sensitive query values such as api_key, token, and access_token.

Added: endpoint URL discovery fallback

OpenAPI discovery now handles pasted endpoint URLs more gracefully.

When a user provides a URL like:

• https://abc.com/asd/bsd/cds

The server now:

1. tries the exact URL first
2. if no OpenAPI document is found there, tries the origin root page, for example https://abc.com/
3. continues with the existing common-path and HTML-link discovery flow

This helps agents avoid giving up too early when users paste an API endpoint instead of a docs page or direct OpenAPI document URL.

Improved: endpoint path lookup with query strings

Endpoint lookup now tolerates path inputs that include query strings.

For example, a lookup for:

• /reports?period=monthly

can still match the OpenAPI path:

• /reports

This keeps details and execution flows more stable when agents pass user-facing request URLs through to MCP tools.

Validation

Verified in this release:

• TypeScript build passes
• Test suite passes: 25/25
• Added regression coverage for embedded query strings and OpenAPI query serialization styles
• Added regression coverage for raw query strings and query API key masking
• Added regression coverage for endpoint details lookup when path input includes a query string
• Added regression coverage for endpoint URL discovery fallback to the origin root docs page

Install / update

npm i @rekl0w/mcp-openapi-discovery@latest

Notes

This is a minor release because it adds new endpoint execution and discovery capabilities while keeping the MCP tool surface backward-compatible.

@rekl0w/mcp-openapi-discovery v0.3.2 is a patch release focused on cache freshness and safer real-world spec refresh behavior.

This release keeps the persistent cache introduced in v0.3.0, but makes it much less likely to serve stale endpoint lists when a hosted OpenAPI document changes after the first discovery.

Suggested Git tag: v0.3.2

Highlights

• Improved cache freshness by revalidating discovered specs against their canonical document URL
• Fixed stale endpoint results where list_endpoints, get_endpoint_details, or call_endpoint could keep using an older cached spec for up to the full cache TTL
• Added safe fallback behavior so cached specs are still usable if refresh or rediscovery fails temporarily
• Added regression coverage for canonical spec refresh when a docs-generated OpenAPI document gains new endpoints

What changed

Improved: canonical spec revalidation

When a spec is already cached, the server now attempts to refresh it from the previously discovered canonical document URL before reusing the cached result.

This improves compatibility for docs systems that publish an updated OpenAPI document at the same URL after the MCP server has already seen an older version.

Fixed: stale endpoint and execution context reuse

Previously, a cached resolved document could be reused from memory or disk until the cache TTL expired.

That meant tools such as:

• list_endpoints
• get_endpoint_details
• find_related_endpoints
• trace_parameter_usage
• call_endpoint

could continue operating on an older endpoint set even when the source spec had already changed.

This release refreshes the resolved document before serving cached results, so newly added endpoints are picked up much sooner.

Improved: fallback behavior during refresh

If the canonical spec refresh fails, the server now tries rediscovery again from the original input URL.

If rediscovery also fails, it safely falls back to the last known cached spec instead of breaking existing workflows unnecessarily.

This keeps the cache useful during temporary docs outages while still prioritizing freshness whenever possible.

Validation

Verified in this release:

• TypeScript build passes
• Test suite passes: 21/21
• Added regression coverage for stale cache refresh when a canonical spec gains new endpoints

Install / update

npm i @rekl0w/mcp-openapi-discovery@latest

Notes

This is a patch release focused on making cached OpenAPI discovery more trustworthy for live, changing documentation environments without changing the MCP tool surface.

@rekl0w/mcp-openapi-discovery v0.3.1 is a patch release focused on real-world compatibility improvements for generated OpenAPI docs and public API calling.

This release improves docs-page discovery for Swagger UI, Scalar, and Laravel Request Docs deployments, tightens workflow suggestion quality, and fixes request execution when generated specs incorrectly advertise localhost server URLs.

Highlights

• Improved docs-page detection for:
  • Swagger UI
  • Scalar
  • Laravel Request Docs
  • request-docs/api?openapi=true style specs
  • versioned raw spec paths such as swagger/v1/swagger.json and api/v3/openapi.json
• Improved workflow suggestion quality by filtering invalid prerequisite endpoints such as:
  • HEAD
  • OPTIONS
  • TRACE
  • delete-style producers
  • sibling action endpoints that do not actually produce required dependency values
• Fixed request execution base URL rewriting so docs-generated specs pointing to http://localhost can safely fall back to the detected public origin
• Added regression tests for docs discovery, workflow planning, and request URL rewriting

What changed

Improved: docs-page discovery

The detector is now better at extracting raw OpenAPI document URLs from docs pages instead of only succeeding when the raw JSON/YAML URL is provided directly.

This includes support for:

• swagger/v1/swagger.json
• swagger/v2/swagger.json
• swagger/v3/swagger.json
• request-docs
• request-docs/api?openapi=true
• request-docs/api?openapi=1
• api?openapi=true
• api?openapi=1
• versioned openapi.json and swagger.json paths
• docs pages that expose spec URLs through embedded config or raw spec path references

Improved: workflow suggestion guardrails

Workflow planning is now more conservative and more accurate on weak or generated specs.

The planner now avoids treating unrelated endpoints as prerequisite producers unless they actually satisfy the required dependency.

That means it is less likely to suggest noisy chains involving:

• HEAD routes
• delete actions
• sibling approval/reject action routes
• endpoints that share a path family but do not return useful dependency outputs

Fixed: request URL fallback for docs-generated specs

Some generated specs expose server URLs like http://localhost/api, which breaks live calls against publicly hosted APIs.

This release rewrites those obviously local/private base URLs to the detected public origin while preserving the intended API path.

This makes real calls work more reliably against hosted docs systems that were generated from local development settings.

Validation

Verified in this release:

• TypeScript build passes
• Test suite passes: 20/20
• Real-world docs/spec validation succeeded across multiple public APIs, including:
  • Laravel Request Docs deployments
  • Swagger UI deployments
  • Scalar-based docs pages

Install / update

npm i @rekl0w/mcp-openapi-discovery@latest

Notes

This is a patch release focused on making the server more reliable on messy, generated, and production-hosted OpenAPI documentation setups without changing the overall MCP tool surface.

@rekl0w/mcp-openapi-discovery v0.3.0 turns the server into a more practical API workflow assistant.

This release adds multi-step call sequence planning, disk-backed spec caching, and a stronger server-side search scorer for finding the right endpoints without embeddings.

Highlights

• Added suggest_call_sequence for multi-step API workflow planning
• Added persistent disk cache for detected specs keyed by URL and specId
• Improved search_endpoints ranking with:
  • synonym expansion
  • operation intent bonuses
  • path and operation weighting
  • field depth-aware scoring
• Kept external bundle-based $ref support in place
• Expanded test coverage and documentation

What changed

New: suggest_call_sequence

A new MCP tool, suggest_call_sequence, can suggest likely prerequisite API call chains.

It supports two modes:

• exact target planning with targetMethod + targetPath
• goal-based planning with goal

The planner analyzes:

• auth requirements
• path parameter dependencies
• request body identifier fields such as categoryId, attributeId, fileId, or parentId
• response body outputs such as id, accessToken, and resource-specific identifiers
• parent/child path relationships

Example workflow patterns it can now infer:

• login → create category → create category attribute → create product
• login → create customer → create order
• upload file → create entity using returned file id

New: persistent cache

Detected specs are now cached on disk as well as in memory.

This means specId-based tools such as:

• search_endpoints
• suggest_call_sequence

can continue working after process restarts, as long as the cached document is still valid.

The cache is keyed by:

• normalized input URL
• specId

And the cache directory can be overridden with:

• MCP_OPENAPI_DISCOVERY_CACHE_DIR

Improved: search ranking

search_endpoints is now more useful for real-world queries, even without embeddings.

The scorer now considers:

• path tokens
• operationId
• summaries and descriptions
• tags
• parameter names
• request field names
• response field names
• synonym groups such as:
  • add → create
  • edit → update
  • login / token → auth intent

This helps queries like:

• add order
• login token
• edit product

return more relevant endpoints.

Validation

Verified in this release:

• TypeScript build passes
• Test suite passes: 12/12
• npm package published successfully as:
  • @rekl0w/mcp-openapi-discovery@0.3.0

Install / update

npm i @rekl0w/mcp-openapi-discovery@latest

Notes

This release pushes the server beyond endpoint lookup and closer to API workflow reasoning:

• find the spec
• search the right endpoint
• understand dependencies
• suggest the order of calls
• execute the flow

@rekl0w/mcp-openapi-discovery v0.2.0 brings a new server-side endpoint retrieval flow and safer OpenAPI reference handling.

Highlights

• Added search_endpoints tool for server-side endpoint search
• Added stable in-memory specId returned by detect_openapi
• Added bundle-based external $ref support for referenced schemas
• Improved endpoint retrieval using weighted scoring over:
  • method
  • path
  • operationId
  • summary / description
  • tags
  • parameter names
  • request body field names
  • response body field names
• Updated tests and documentation for the new search flow

What changed

New: specId flow

detect_openapi now returns a specId that can be reused by later tools.
This allows the server to keep the parsed spec in memory and return only relevant endpoint matches instead of exposing the full spec surface repeatedly.

New: search_endpoints

A new MCP tool, search_endpoints, can search cached endpoints for a detected spec using server-side weighted scoring.

Example queries:

• create user email
• refresh bearer token
• order status update

Improved: external $ref support

OpenAPI parsing now bundles external references before analysis, improving support for split schema files and remote referenced components.

This is especially useful for specs that keep schemas outside the root document.

Validation

Verified in this release:

• TypeScript build passes
• Test suite passes: 9/9
• npm package published successfully as:
  • @rekl0w/mcp-openapi-discovery@0.2.0

Install / update

npm i @rekl0w/mcp-openapi-discovery@latest

Notes

This release focuses on retrieval quality and better spec compatibility without requiring embeddings or client-side semantic indexing.