GSoC2026/Borgy: MCP App tools experiment by AbdelrahmanELBORGY · Pull Request #1700 · foss42/apidash

AbdelrahmanELBORGY · 2026-06-16T15:03:47Z

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:

Node.js: You must have Node.js installed on your system to run the MCP server wrapper.
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

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

…bviews for API execution and history

animator · 2026-06-27T20:37:03Z

How will this file be shipped to the end user?

animator · 2026-06-27T20:40:50Z

Separate files for separate templates.
Why are you not following the best practices that have been already documented in the article provided to you - https://dev.to/ashita/a-practical-guide-to-building-mcp-apps-1bfm

separate files for UI resources

shared css design system

Why polling is implemented?

animator · 2026-06-27T20:42:46Z

+<div id="history-container" class="history-list"></div>
+
+<script>
+    async function executeMcpTool(name, args) {


Why is this not a common utility? As architected in the article.

animator · 2026-06-27T20:44:11Z

+import 'html_templates.dart';
+
+class ResourceHandler {
+  static Map<String, dynamic> listResources() {


Where is this function being used?

it tells the IDE client the list of the resources including interfaces that the MCP server has, by returning a JSON map containing a list of resources, each resource has its own name, uri and mimetype, it is not used directly,it runs once when the MCP server first connects to the IDE client

animator · 2026-06-27T20:45:09Z

+    };
+  }
+
+  static Map<String, dynamic> readResource(String uri) {


Where is this function being used?

this one when the IDE client actually decides to open a specific resource, it calls this function, passing in the specific uri

animator · 2026-06-27T21:06:20Z

+          },
+        },
+        {
+          "name": "apidash_get_results",


why is results a separate app?

actually this is an hidden from agent tool, it is used internally just to fetch the last request results in order to display it in the ui

animator · 2026-06-27T21:14:02Z

+
+// __dirname is "apidash/scripts"
+// '..' takes us up to the root folder "apidash/"
+const EXE_PATH = path.join(__dirname, '..', 'build', 'windows', 'x64', 'runner', 'Release', 'apidash.exe');


hard coded path .. does not work for end user.

Also now working for macos or linux as written in the instruction.

animator · 2026-06-27T21:20:48Z

+  genui: ^0.9.2
+  google_generative_ai: ^0.4.7


How is this relevant to this PR?

AbdelrahmanELBORGY force-pushed the GSoC2026-Borgy-MCP-App-tools-experiments branch from a06b552 to b5aef17 Compare June 16, 2026 15:25

feat(mcp app): integrate local MCP server with interactive VS Code we…

bb969ad

…bviews for API execution and history

AbdelrahmanELBORGY force-pushed the GSoC2026-Borgy-MCP-App-tools-experiments branch from b5aef17 to bb969ad Compare June 16, 2026 15:28

animator reviewed Jun 27, 2026

View reviewed changes

Comment thread scripts/apidash-mcp.js

animator Jun 27, 2026

Copy link
Copy Markdown

Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How will this file be shipped to the end user?

animator reviewed Jun 27, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

GSoC2026/Borgy: MCP App tools experiment#1700

GSoC2026/Borgy: MCP App tools experiment#1700
AbdelrahmanELBORGY wants to merge 1 commit into
foss42:mainfrom
AbdelrahmanELBORGY:GSoC2026-Borgy-MCP-App-tools-experiments

AbdelrahmanELBORGY commented Jun 16, 2026

Uh oh!

animator Jun 27, 2026

Uh oh!

animator Jun 27, 2026

Uh oh!

animator Jun 27, 2026

Uh oh!

animator Jun 27, 2026

Uh oh!

AbdelrahmanELBORGY Jun 27, 2026

Uh oh!

animator Jun 27, 2026

Uh oh!

AbdelrahmanELBORGY Jun 27, 2026

Uh oh!

animator Jun 27, 2026

Uh oh!

AbdelrahmanELBORGY Jun 27, 2026

Uh oh!

animator Jun 27, 2026

Uh oh!

animator Jun 27, 2026

Uh oh!

animator Jun 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

AbdelrahmanELBORGY commented Jun 16, 2026

Description - API Dash MCP App

Visual view

1. VS Code MCP Server Setup

2. Architecture and File Overview

Added Files

The 4 Core Tools and How They Invoke Each Other

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

3. The Node.js Wrapper & Stdio Communication

4. Hive Boxes for Local Storage

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants