GSoC2026/Borgy: MCP App tools experiment

[AbdelrahmanELBORGY]

Description - API Dash MCP App

This PR contains the MCP server and basic MCP app UI for API Dash.
It allows AI assistants inside editors like VS Code (e.g., Claude Code, Roo Code) to interact directly with the API Dash core engine, execute API requests, and view rich, interactive UIs directly within the editor.

Visual view

Execute Request	List History

1. VS Code MCP Server Setup

⚠️ Prerequisites:

1. Node.js: You must have Node.js installed on your system to run the MCP server wrapper.
2. Build the Desktop App:

• Because this headless engine relies on API Dash's Flutter native plugins (like local database and networking), you must compile the app for your desktop operating system at least once.
• Run flutter build windows --release (or macos / linux) in the root directory to generate the required native build files before starting the server.

To connect this engine to your VS Code AI assistant (like Roo Code or Cline), you must create a .vscode folder in the root of your workspace, and then create an mcp.json file inside it to register the server.

Add the following configuration to your new .vscode/mcp.json file, making sure to replace <PATH_TO_APIDASH_REPO> with the actual absolute path to where you cloned this repository on your machine:

{
  "servers": {
    "apidash-mcp": {
      "command": "node",
      "args": [
        "<PATH_TO_APIDASH_REPO>/scripts/apidash-mcp.js"
      ]
    }
  }
}

Examples of valid paths:

• Windows: "C:/Users/Username/Documents/apidash/scripts/apidash-mcp.js"
• macOS/Linux: "/Users/Username/projects/apidash/scripts/apidash-mcp.js"

(Note: Use standard forward slashes / in the JSON path, even on Windows, as Node.js handles them perfectly and it prevents escaping errors).

---

2. Architecture and File Overview

Added Files

• mcp_engine.dart: Acts as the core JSON-RPC protocol router. It listens for incoming tool executions or resource requests, matches the requested method (e.g., tools/call), and dispatches it to the appropriate handler while catching errors to prevent server hangs.
• mcp_service.dart: Manages the lifecycle of the headless Dart process. It bridges standard input/output (stdio) to the isolate ports, allowing the underlying Flutter/Dart engine to communicate with the Node.js wrapper.
• tool_handler.dart: The brain of the operations. It registers the schemas for the AI tools and executes the actual backend logic (like sending HTTP requests and saving to the database).
• resource_handler.dart: Responsible for providing the MCP client with the correct UI template based on the requested ui:// URI scheme.
• html_templates.dart: Contains the raw HTML, CSS, and Javascript needed to render the API Dash dashboards inside VS Code's webview panels.

The 4 Core Tools and How They Invoke Each Other

1. apidash_execute_request:
   • Function: The AI calls this tool to construct and fire off an HTTP request using the API Dash core.
   • Invocation: Once the request completes, it saves the data to the local database, generates a unique Execution ID, and returns a _meta UI trigger. This forces VS Code to open the Results Dashboard.
2. apidash_get_results:
   • Function: This tool acts as the data bridge for the UI. It is explicitly hidden from the AI agent using the visibility: ["app"] modifier in its _meta schema.
   • Invocation: The AI cannot see or call this tool. Instead, the Javascript running inside the Results Dashboard UI polls this tool continuously to fetch the latest request data from the local database and update the screen.
3. apidash_list_history:
   • Function: Fetches all past requests from the local database.
   • Invocation: When the AI calls this, the Dart backend returns the history list as structuredContent (raw JSON) and sends a _meta trigger to open the History UI. The UI's Javascript automatically intercepts this raw JSON to render the interactive list.
4. apidash_delete_request:
   • Function: Deletes a specific request from the database. It is explicitly hidden from the AI agent using the visibility: ["app"] modifier.
   • Invocation: This is invoked silently by the History UI. When a user clicks the "Delete" button on the screen, the Javascript uses window.parent.postMessage to secretly ask the MCP client to call this tool on the backend, bypassing the AI entirely.

Invoking visible to app only tools - not visible to the ai agent

apidash_get_results	apidash_delete_request

---

3. The Node.js Wrapper & Stdio Communication

You might wonder why a .js file is used as the entry point when the entire application is built in Dart/Flutter.

Why a .js script?
Most MCP clients running inside VS Code expect to spawn a server process via a highly standard environment (like Node.js or Python) and communicate over standard Input/Output (stdio). The Node.js script acts as a lightweight, reliable proxy wrapper.

Why this approach is necessary:
API Dash relies heavily on Flutter-specific packages (like WidgetsFlutterBinding) and complex local databases. If you try to run a pure, raw Dart script from the command line without the proper Flutter context, these core packages will crash.

By starting a Flutter-based headless app, we initialize all the necessary core packages securely. The Node.js script simply pipes standard JSON-RPC text strings via stdin into the headless Dart environment, and the Dart environment pushes responses back out via stdout. The McpService class actively listens to this stdin stream, processes the JSON, and pipes it into the isolated MCP engine.

---

4. Hive Boxes for Local Storage

The engine utilizes Hive CE (hive_ce) as its local storage mechanism.

What it does:
Initialize an isolated agent_history box specifically for the MCP server.

Why it is important:

• Persistence: Unlike keeping data in RAM (which vanishes the moment the AI finishes its thought process), Hive permanently saves every request to the physical hard drive.
• Stateless UI Synchronization: Because the AI and the UI operate completely asynchronously, Hive acts as the central source of truth. The AI saves the request data to Hive and calls .flush() to guarantee it is written to the disk. Milliseconds later, the UI wakes up, queries Hive, and is guaranteed to find the data.
• Historical Records: By generating a unique ID (execution_id) for every request, Hive allows us to build a comprehensive, permanent history log that the user can browse and manage.