Release v0.6.3

Bug Fix

• body parameter now accepts both JSON objects {} and arrays [] — previously declared as object only, which blocked endpoints expecting a root-level array body

Release v0.6.2

Bug Fix

• Fixed "No module named 'jsonpath_ng'" error in released binaries — jsonpath-ng was missing from the GitHub Actions build step

Release v0.6.1

Debug Console Improvements

• Server info bar now shows Base URL, Schema URL, load status, and last request details
• Sidebar (Requests / Variables) is collapsed by default — click ☰ to toggle
• Fixed debug_ui_url disappearing from get_server_info after set_server_config calls

Tool Description Improvements

• execute_request: AI is now nudged to always use jsonpath when response structure is predictable, saving tokens and avoiding re-execution
• get_endpoint_details: warns to use compact=false if body is empty (due to $ref)
• set_server_config: clarifies base_url is auto-detected and only needed as override

Docs

• Added docs/how_to_release.md with release procedure

ControlAPI-MCP v0.6.0 - Token-Efficient Output & JSONPath Filtering

✨ New Features

1. Compact Output by Default

All tools now return compact JSON (no whitespace) to minimize token usage. Every tool is leaner by default.

2. Pagination for list_endpoints and search_schema

Both tools now support limit (default: 10) and offset parameters. Results include a (use offset=N for next page) hint.

3. JSONPath Filtering on Responses

execute_request and replay_response now accept a jsonpath parameter to extract specific fields from the response body directly.

jsonpath: "$.data.access_token"   →  returns just the token string
jsonpath: "$.results[*].id"       →  returns array of IDs

Note: $ is the body root — use $.field not $.body.field.

4. New Tool: replay_response

Re-inspect any cached API response without re-executing the request. Critical for POST/PUT/DELETE to avoid duplicate side effects.

• index=-1 → latest response (default)
• index=-2 → second latest, etc.
• Supports jsonpath, include_headers, include_request, max_body_length

5. get_endpoint_details Compact Mode

Endpoint details now default to a compact field: type summary instead of raw OpenAPI JSON. Use compact=false to get the full raw schema (including $refs).

6. Debug Monitor Auto-Port Fallback

If the configured debug port (or default 45133) is occupied, the server now automatically falls back to an OS-assigned free port. The actual URL is always reported in get_server_info as debug_ui_url.

7. Auto-Detect Double-Path Bug

Many Django/DRF specs (drf-spectacular) set servers[0].url to include a path prefix (e.g. http://localhost:8000/api/v1) while endpoint paths also start with /api/v1. The adapter now auto-detects this and strips the duplicate prefix, so requests resolve correctly without any manual base_url override.

🐛 Bug Fixes

• Falsy body check — if body incorrectly skipped sending 0, false, or []. Fixed to if body is not None.
• base_url display null — get_server_info showed null for base_url on startup even though requests worked correctly.
• Multi-word search_schema — Queries like "login orders" now match endpoints containing ANY of the words (OR logic) instead of requiring the full phrase.
• reload_schema missing return — On failure, the tool fell through to "Unknown tool" instead of returning the error.
• Hardcoded localhost fallback — When no server is configured, base_url is now empty instead of silently defaulting to http://localhost:8000.

🛠️ Improved Tool Descriptions

Tool parameter descriptions updated to prevent common AI mistakes:

• jsonpath: explicitly states $ = body root (not $.body.*)
• get_endpoint_details compact: warns to use compact=false if body appears empty (due to $ref)
• set_server_config base_url: clarifies it's auto-detected and only needed for overrides
• get_server_info: instructs AI to open debug_ui_url in browser when user asks for debug monitor

ControlAPI-MCP v0.3.2 - Content-Type Visibility & Critical Bugfix

🐛 Critical Bug Fixed

Server Configuration Failure from Initial State

Issue: When starting fresh (no server configured yet), attempting to connect to a server would fail with:

Error: Request URL is missing an 'http://' or 'https://' protocol.

Root Cause: When set_server_config fails to load a new schema, it attempts to restore the previous server configuration by calling loader.reload_with_url(temp_loader_url). However, on first run when no server is configured, temp_loader_url is "not-configured" (a placeholder string, not a valid URL). This caused httpx to fail when trying to fetch the schema.

Fix: Check if the previous URL is valid (temp_loader_url != "not-configured") before attempting to reload it. If starting fresh and the new server fails to load, simply don't attempt a rollback.

File changed: src/tools.py (line 309)

✨ New Features

1. Content-Type Visibility in Endpoint Listings

Endpoint listings now show which content-types each endpoint accepts, making it clear when endpoints require special encoding:

{
  "path": "/api/v1/auth/login",
  "method": "POST",
  "summary": "Login",
  "content_types": ["application/x-www-form-urlencoded"]
}

Benefits:

• AI agents can see content-type requirements at a glance
• Easier debugging of API integration issues
• Clear documentation of endpoint expectations

Files changed:

• src/openapi_loader.py - Added content_types field to Endpoint dataclass
• src/tools.py - Updated list_endpoints and search_schema to include content-types

2. New Tool: get_endpoint_details

Get comprehensive schema information for any endpoint:

{
  "path": "/api/v1/auth/login",
  "method": "POST",
  "summary": "Login",
  "description": "Login user and return tokens with user data.",
  "content_types": ["application/x-www-form-urlencoded"],
  "request_body_required": true,
  "request_schemas": {
    "application/x-www-form-urlencoded": {
      "$ref": "#/components/schemas/Body_login_api_v1_auth_login_post"
    }
  },
  "parameters": [...]
}

Features:

• Shows all accepted content-types
• Indicates if request body is required
• Provides full request schema for each content-type
• Lists all parameters (path, query, header)

File changed: src/tools.py - Added new tool handler

3. Content-Type Auto-Detection (Enhanced Visibility)

Auto-detection was implemented in v0.3.0 but wasn't visible to AI agents. Now the schema information is exposed, making it clear:

• Auto-sets Content-Type from OpenAPI schema when not provided
• Preserves user-specified Content-Type headers
• Works transparently - no manual header configuration needed

How it works:

1. openapi_loader.get_preferred_content_type() extracts content-type from schema
2. Priority: application/x-www-form-urlencoded > application/json > first available
3. Auto-sets header only if: endpoint has body AND user hasn't specified Content-Type
4. Uses httpx data= for form encoding, json= for JSON

🔧 Technical Details

Modified Files:

• src/openapi_loader.py - Extract and expose content-types from schemas
• src/tools.py - Add endpoint details tool, expose content-types in listings, fix rollback bug
• src/main.py - Add debugpy remote debugging support (optional, via MCP_DEBUG=1 env var)

New Files:

• .vscode/launch.json - Debugger configuration for MCP server

📋 Test Results

✅ Initial server setup: Connects successfully from unconfigured state
✅ Content-type visibility: Login endpoint shows application/x-www-form-urlencoded
✅ Auto-detection: Login works without manual Content-Type header
✅ User override: Explicit Content-Type headers are preserved
✅ GET requests: No Content-Type set when body is empty
✅ Detailed inspection: get_endpoint_details returns complete schema info

🎯 Impact

Before this release:

• ❌ Could not configure server on first run
• ❌ Content-type requirements hidden from AI agents
• ❌ No way to inspect detailed endpoint schemas
• ❌ Auto-detection worked but wasn't documented/visible

After this release:

• ✅ Server configuration works seamlessly from fresh start
• ✅ Content-types visible in all endpoint listings
• ✅ Dedicated tool for detailed schema inspection
• ✅ Complete transparency of auto-detection behavior

🛠️ Development Tools Added

Remote Debugging Support:

• Set MCP_DEBUG=1 environment variable in mcp.json
• Debugger listens on localhost:5678
• Use "Attach to MCP Server" launch configuration
• Helpful for troubleshooting complex MCP interactions

🙏 Acknowledgments

Thanks to the debugging session that uncovered the server configuration bug and led to improved content-type visibility!

ControlAPI-MCP v0.3.1 - Critical Bugfix

🐛 Critical Bug Fixed

Query Parameters Not Passed in GET Requests

Issue: Query parameters were being stripped from all GET requests, making search, filtering, and pagination completely non-functional.

Root Cause: When httpx.Client().request() receives both a URL with query parameters AND a params argument, it discards the URL query parameters and only uses the params dict. Since the code was passing an empty dict {} when no explicit query_params were provided, all URL query strings were being stripped.

Example of broken behavior:

# User makes request
execute_request(
    method="GET",
    path="/api/v1/service-types/?is_package=true&page_size=3"
)

# Before fix: Query parameters were lost
# API received: /api/v1/service-types/ (no parameters!)

# After fix: Query parameters work correctly
# API receives: /api/v1/service-types/?is_package=true&page_size=3 ✅

Fix:

• Extract query parameters from URL path if present
• Merge with explicit query_params argument (explicit params take precedence)
• Only pass params to httpx if non-empty

📋 Test Cases (All Now Pass)

✅ Boolean filter: ?is_package=true - Returns only packages
✅ Pagination: ?page_size=5 - Returns 5 items
✅ Search: ?search=brake - Returns filtered results
✅ Combined: ?category=diagnostics&search=battery&page_size=2 - All params work together
✅ Mixed approach: Both URL params and explicit query_params dict merge correctly

🔧 Technical Details

File changed: src/request_executor.py

Changes:

1. Import urllib.parse for query string handling
2. Extract and parse query parameters from path using parse_qs()
3. Merge URL params with explicit query_params dict
4. Strip query string from path before URL construction
5. Pass None instead of {} to httpx when no params

💥 Impact

This bug affected:

• ❌ All GET endpoints with query parameters
• ❌ Filtering and search functionality
• ❌ Pagination controls
• ❌ Any endpoint relying on query strings

Now fixed: All query parameter functionality fully restored.

🙏 Thanks

Thanks to the detailed bug report with curl comparisons and debugger traces that made this easy to diagnose!

ControlAPI-MCP v0.3.0 - macOS Support

🎉 New Features

macOS Support

• ✅ Native macOS binaries - Works on Intel and Apple Silicon Macs
• ✅ Auto-detection - auto-run.sh automatically downloads the correct binary for your platform
• ✅ One-click install - Same seamless experience on both Linux and macOS

Cross-Platform

• Linux - controlapi-mcp-linux (x86_64)
• macOS - controlapi-mcp-macos (universal binary)

🔧 Technical Changes

• GitHub Actions: Matrix build strategy for parallel Linux + macOS builds
• auto-run.sh: OS detection using uname -s to download platform-specific binary
• Release artifacts: Two separate binaries per release

📥 Installation

macOS & Linux (One-Click)

Click the install link in the README or use:

curl -O https://raw.githubusercontent.com/fellowabhi/ControlAPI-openapi-to-mcp/main/auto-run.sh
chmod +x auto-run.sh
./auto-run.sh

The script automatically detects your OS and downloads the correct binary!

🙏 Feedback

Please report any macOS-specific issues on GitHub!