EoF MCP Studio Architecture

EoF MCP Studio is a native macOS application for configuring, serving, testing, and using Model Context Protocol (MCP) tools, resources, prompts, skills, and multi-agent workflows. The application combines a SwiftUI desktop interface, Core Data configuration storage, an embedded MCP server, an AI chat runtime, a script/plugin execution layer, and importable JSON seed assets.

This document describes the current source architecture and the main runtime flows.

High-Level Shape

flowchart LR
    UI["SwiftUI App Shell"]
    CoreData["Core Data Configuration"]
    MCP["Embedded MCP Server"]
    ToolEngine["ToolCallEngine"]
    LLM["LLMChatService / AIChatEngine"]
    Agents["MultiAgentRuntime"]
    Plugins["Plugin and Script Runtime"]
    Assets["Bundled JSON Configuration"]

    UI --> CoreData
    Assets --> CoreData
    UI --> LLM
    UI --> Agents
    CoreData --> MCP
    MCP --> ToolEngine
    LLM --> ToolEngine
    Agents --> ToolEngine
    ToolEngine --> Plugins

Loading

The app is organized around a few stable responsibilities:

• MCPStudio/UI: SwiftUI views and controllers for user workflows.
• MCPStudio/Core: persistence, server, tooling, LLM, plugin, logging, settings, and shared services.
• MCPStudio/Assets/Configuration: bundled default tools, skills, prompts, resources, and multi-agent workflows.
• MCPStudio/MCPStudio.xcdatamodeld: Core Data model for all editable configuration entities.
• XcodeExtension: companion Xcode extension that can send requests into the main app.
• Bundles: bundled runtime tools such as Node.js and Python runtime plugins.

Application Shell

The entry point is MCPStudio/UI/AppMain.swift. It creates the main SwiftUI window, configures menus, initializes startup work, imports/refreshes configuration, and hosts AppMainView.

AppMainView is the central navigation hub. It exposes these destinations through MenuDestination:

• Server
• Prompts
• Resources
• Skills
• Tools
• Agents
• Scripts
• Plugins
• AI Chat
• About

Each destination owns its controller as a @StateObject, so switching views does not discard editing state. Shared view models are injected through SwiftUI environment objects where needed, especially for chat, tools, resources, skills, and multi-agent workflows.

AppDelegate handles AppKit integration: window behavior, external notifications, launch services, alert presentation, app lifecycle, and Xcode extension communication.

Persistence Model

The application uses Core Data through PersistenceController with the model MCPStudio.xcdatamodeld. User-facing configuration is stored as typed entities:

• ServerConfig: embedded MCP server name, title, version, port, token, and instructions.
• ToolsConfig: tool definitions with type, method, handler, plugin/script references, title, description, input schema, and output schema.
• ToolInputSchema, ToolOutputSchema, ToolInSchemaParams, ToolOutSchemeParams: JSON-schema-like parameter definitions.
• PromptConfig, PromptArguments: reusable prompt templates and arguments.
• ResourceConfig: resource URI, MIME type, annotations, tags, and related resources.
• SkillConfig: bundled prompt/resource/tool scopes and model preferences.
• MultiAgentWorkflow, MultiAgentNode, MultiAgentConnection, MultiAgentProperty: graph-based workflow definitions.

ConfigurationController imports and exports these entities from JSON folders under Assets/Configuration. Startup can seed bundled configuration, and users can import additional configuration packages.

User interface preferences and integration state are stored separately in UserDefaults through helpers such as SettingsManager, UserDefaultsKeys, and SharedStore.

Embedded MCP Server

The embedded MCP server lives under MCPStudio/Core/Server.

The server is layered as:

• Swift app layer: MCPServer.swift, ServerConfigController, and UI configuration.
• Objective-C++ bridge: MCPServerBridge, MCPMessage, and service shims.
• C++/Objective-C++ server core: MCPServer.mm, MCPRouter.mm, MCPServices.mm, and MCPHttpTransport.mm.
• Security/certificate support: ServerCertificateManager.

The server exposes configured tools, prompts, resources, skills, and workflow helper tools to MCP clients. It uses Core Data configuration and routes tool execution through ToolCallEngine, keeping execution behavior consistent whether the caller is the embedded server, AI chat, or multi-agent runtime.

Tool Runtime

ToolCallEngine is the central executor for configured MCP tools. It accepts a ToolCallRequest, validates the selected tool configuration, normalizes results against the declared output schema, logs runtime events, and dispatches to the appropriate backend.

Supported runtime types:

• BuiltinTool: native handlers such as file access, calendar/reminder access, contacts, skills, workflow load/run/create/validate/commit helpers.
• ScriptTool: JavaScript files executed in JavaScriptCore through ScriptContext, with the app bridge exposed as MCPStudio.
• CustomTool: external plugins loaded through the native plugin bridge.

Core handlers include:

• FileAccessHandler for file listing, reading, and writing.
• CalendarToolHandler for calendars, events, reminder lists, and reminders.
• ContactsToolHandler for contacts.
• MultiAgentWorkflowDraftService and MultiAgentWorkflowExecutionBridge for workflow draft and runtime tools.

Tool lists and picker options are intentionally unrestricted: all configured tool types and methods can be selected and executed.

MCP Integrations for Chat

MCPIntegrationManager manages local and remote MCP integrations for AI chat. It persists integration definitions in UserDefaults, derives publishable internal tools from Core Data, and builds provider-specific payloads for chat requests.

It supports:

• Remote MCP servers.
• The internal embedded MCP server as an ephemeral MCP endpoint.
• LM Studio MCP JSON plugin mode.
• Tool allowlists per integration.
• Guards against recursive calls back into the embedded server.

The internal always-enabled helper tools include skill loading, workflow loading, and workflow execution.

AI Chat Layer

The AI chat feature is split between MCPStudio/Core/LLM and MCPStudio/UI/AIChat.

Important pieces:

• AIProviderTypes and AIProviderRegistry: provider descriptors, auth modes, protocol families, endpoints, model capabilities, and bundled provider catalog loading.
• LLMChatService: unified service layer for provider calls.
• AIChatEngine: chat orchestration and tool-call handling.
• AttachmentHandler, AttachmentStrategies, and AttachmentTypes: file/image/document attachment preparation.
• HistoryModel: chat history persistence.
• ChatViewModel: UI-facing session state, selected provider/model, messages, MCP integration state, selected skills, selected workflows, and streaming lifecycle.

The chat UI is composed from ChatView, ChatPanelView, InputAreaView, message bubble views, provider/model settings, MCP integration settings, and picker sheets for prompts, resources, skills, and workflows.

Multi-Agent Workflows

Multi-agent workflows are graph-based Core Data entities edited in MCPStudio/UI/MultiAgents.

The editor contains:

• MultiAgentConfigView: main workflow management surface.
• MultiAgentCanvasView: graph canvas for agents and connections.
• MultiAgentInspectorView: selected workflow, agent, connection, and property editing.
• MultiAgentWorkflowPickerSheet: chat input picker for workflow selection.
• MultiAgentJSONSupport: JSON draft create/validate/commit support for tool-driven workflow creation.
• MultiAgentRuntime: execution engine for graph traversal, agent runs, tool runners, shared context, logging notifications, and cancellation.

Agent execution modes:

• llmInstruction: an agent calls an LLM provider/model with its instruction and workflow context.
• mcpTool: an agent invokes a configured MCP tool directly.

Connections define how artifacts and state move through the graph, using kinds such as delegation, handoff, review, shared state, and artifact flow.

Plugin and Script System

The plugin system lives under MCPStudio/Core/Plugins and MCPStudio/Core/Plugins/Core.

Key pieces:

• PluginController: registration, persistence, approval, security metadata, bundled plugin registration, and plugin UI state.
• PluginDescriptor: plugin metadata and ABI descriptor.
• PluginDispatch: dispatch support for plugin calls.
• ExternToolBridge, CustomToolHandler, ToolDiscoveryService, ToolABI, and ToolJSONBridge: native plugin loading and invocation.

Plugins can be .dylib, .bundle, or .plugin style packages. Registered plugins store security-scoped bookmark data so the app can reopen approved plugin paths.

Script tools are JavaScript-based and run through JavaScriptCore, with Node-like bootstrap support from bundled assets. The script runtime injects a MCPStudio bridge, console helpers, module directory context, and structured result handling.

Security and File Access

macOS sandbox and user approval concerns are handled through:

• BookmarkController and BookmarkSetupView: UI and persistence for security-scoped folder access.
• SecurityScopeRuntime: non-UI runtime helper for starting and stopping security-scoped operations.
• SandboxLauncher: helper for launching sandboxed processes where required.
• Plugin approval views and enable wizards for explicit user confirmation before activating external code.

File access tools use the security scope runtime before reading or writing user-selected locations.

Configuration Assets

Bundled configuration is stored in MCPStudio/Assets/Configuration:

• Tools: built-in tool descriptors, runtime tools, shell/build helpers, calendar/contact/reminder tools, HTTP tools, and file tools.
• Skills: reusable instruction bundles for development workflows.
• Prompts: reusable prompt templates.
• Resources: static reference resources.
• MultiAgents: sample workflow graphs.

ConfigurationController maps these JSON files into Core Data entities and can export the same families back to disk.

UI Architecture

The UI follows a controller-backed SwiftUI pattern:

• Controllers inherit common behavior from AbstractController.
• List/detail editors keep selection, focus, dirty state, add/delete/save/revert events, and Core Data fetches in the controller.
• Views are mostly declarative compositions over controller state.
• Reusable controls and design tokens live in DesignComponents.
• Focus routing uses FocusedKey+Values.
• Onboarding overlays use OnBoardingView.
• Logging UI uses LogController, LogEntry, and LogTableView.

Main editor families:

• Server: ServerConfigView, ServerConfigController
• Prompts: PromptConfigView, PromptDetailView, PromptListView, PromptConfigController
• Resources: ResourceConfigView, ResourceDetailView, ResourceListView, ResourceConfigController
• Skills: SkillConfigView, SkillDetailView, SkillListView, SkillConfigController
• Tools: ToolsConfigView, ToolsDetailView, ToolsListView, ToolsConfigController
• Scripts: ScriptEditorView, ScriptEditorController, ScriptDebugSession
• Plugins: PluginManagerView, approval/detail/enable wizard views

Xcode Extension

The XcodeExtension target contains a source editor extension that can communicate with the main app using shared store and distributed notifications. The main app receives external requests through AppDelegate and routes them into the active chat window when appropriate.

Logging and Feedback

Runtime logging is centralized through:

• RuntimeLogCenter
• RuntimeLogEvent
• LogController
• LogTableView

Feedback submission is handled by FeedbackService, a small network service that posts structured feedback to the project endpoint without depending on licensing or purchase code.

Build and Verification

The primary app target is MCPStudio.

Common local build command:

xcodebuild -quiet -project MCPStudio.xcodeproj -scheme MCPStudio -configuration Debug -derivedDataPath Build/DerivedData build

The project also includes an Xcode extension target and bundled runtime plugins. Generated build output and Swift package checkouts are placed under Build/DerivedData.