Skip to content

Modular MCP Client

Overview

A full-stack Bun application designed as an MCP client with a modular plugin system inspired by Obsidian. The architecture enables dynamic plugin loading, type-safe communication between frontend and backend, and sophisticated agent permission management.

Architecture

Plugin System

Each plugin defines three core components:

  • Views: Frontend UI components for user interaction
  • Functions: Backend logic with both stub and execution versions
  • MCP Server: Integration specifications for external services

Type Safety

The system maintains type safety through:

  • Function stubs available on frontend for rendering
  • Full function logic available on server for execution
  • RPC communication between frontend and backend
  • Automatic type generation across the stack

Agent Management

  • Permission Systems: Agents with controlled access to specific MCP servers
  • Inbox Workflows: GitHub Actions triggered by agent inbox folders
  • Multi-Engine Support: Different agent engines (Claude Code, etc.) with configurable permissions

Current Implementation

Working Plugins

  • Notes Plugin: Information management and documentation
  • TLDraw Plugin: Visual diagramming and sketching integration with enhanced whiteboard capabilities

Discord Bot Integration Concepts

Advanced discussions about running Claude Code SDK directly within Discord bot server infrastructure:

  • Unified Agent Access: Claude Code with MCP server access running directly in Discord
  • Threaded Responses: Complex agent interactions delivered through Discord thread responses
  • Permission Inheritance: Leveraging existing modular permission models for Discord-based agent access
  • Context Isolation: Same context management principles applied to Discord bot interactions

Data Management

  • GitHub Backing: Repository-based data storage and version control
  • Workflow Integration: GitHub Actions for automated processing
  • Local Development: Full-stack running locally for development

Technical Stack

  • Runtime: Bun for full-stack JavaScript/TypeScript using bun.server()
  • Frontend: Custom React implementation without traditional framework dependencies
  • Routing: Home-rolled routing system (custom useRouter() hook since no Next.js framework)
  • Backend: RPC-based function execution with plugin logic
  • Storage: GitHub repository integration for data persistence
  • Architecture: Local full-stack development with Bun's bundler integration

Development Details

Plugin Registration Flow: 1. Plugin defines views, functions, and MCP server configurations 2. Functions include both stub versions (frontend) and execution logic (backend) 3. Registration makes function stubs available for frontend rendering 4. Server maintains full function logic for execution 5. Type-safe RPC communication between frontend and backend

Bun Full-Stack Approach: - Uses bun.server() that serves both backend and client - Leverages Bun's bundler for full-stack development - Custom React implementation without framework constraints - Dynamic imports enabled by Bun's flexible module system

Planned Features

Enhanced Plugin Ecosystem

  • Thumbnail Editor Integration: Existing thumbnail generation as plugin
  • Content Creation Tools: Various media and document generation plugins
  • Development Tools: Code analysis and automation plugins

Workflow Automation

  • Agent Inbox: Folder-based triggering of agent workflows
  • Multi-Service Integration: Comprehensive MCP server ecosystem
  • Automated Processing: GitHub Actions for background operations

User Experience

  • Plugin Discovery: Marketplace or registry for community plugins
  • Visual Workflow Builder: GUI for creating agent automation flows
  • Real-time Collaboration: Multi-user plugin environments

Technical Innovation

Novel Import System

Leveraging Bun's full-stack capabilities for dynamic plugin loading and execution:

  • Compile-time plugin registration with runtime execution
  • Hot module replacement for development workflow
  • Shared type definitions across plugin boundaries
  • Custom React implementation without traditional framework dependencies
  • Home-rolled routing system (e.g., useRouter()) due to no Next.js framework

Agent Orchestration

  • Permission Models: Fine-grained access control for MCP servers with granular tool filtering
  • Workflow Triggers: Event-driven agent activation through inbox folder system
  • Resource Management: Controlled agent resource utilization preventing context pollution
  • Multi-Engine Support: Different agent instances with specific MCP server permissions

Context Management Philosophy

Addresses the challenge where broad MCP server access leads to tool context pollution in LLMs. For example, when doing GitHub-specific work, Playwright MCP server tools shouldn't clutter the agent's available function space, improving both performance and decision-making clarity.

Development Status

  • Phase: Active personal exploration during off-hours development
  • Testing: Notes and TLDraw plugins fully operational with screenshot evidence
  • Focus: Core plugin system refinement and enhanced agent integration patterns
  • Timeline: Iterative development as personal productivity tool with potential executable bundling
  • Integration Exploration: Evaluating Discord bot server architecture for shared agent management concepts
  • Latest Update: September 17, 2025 - Advanced session management and configuration features demonstrated

Recent Developments (September 17, 2025)

Session Management Enhancement

  • Reusable Configurations: Create and manage multiple Claude Code configurations within the MCP Client interface
  • Session Resumption: Resume previous conversations and development sessions seamlessly
  • Organized Workflow: Centralized management of various Claude Code "flavors" eliminating manual directory navigation
  • Configuration Persistence: Advanced session state management with proper file organization

Claude Code Integration Improvements

  • Documentation Clarification: Identified discrepancy in official docs regarding session storage location (~/.claude/ vs ~/.config/claude/)
  • File Structure Understanding: Session metadata in sessions.json with project-specific transcripts in JSONL format
  • Developer Experience: Streamlined setup process removing need for manual configuration in each project directory

Demo Progress

  • Internal Demo: Comprehensive demonstration of reusable configurations and session resumption
  • Quality of Life Features: Significant improvements in developer workflow efficiency
  • Professional Tooling: Addressing gaps in official Claude Code tooling through integrated interface

Community Validation

  • Developer Feedback: Strong positive reception for session resumption and organizational improvements
  • Workflow Modernization: Recognition that current terminal-based approach feels primitive compared to integrated solution
  • Market Gap: Community noting absence of similar integrated tooling from official Claude Code team

Native macOS Integration

Production Milestone: Successfully implemented and deployed native macOS app packaging for the modular MCP client:

Architecture

  • Swift Host Application: Native macOS container providing professional app experience
  • Sidecar Bun Server: Full-stack Bun server running as background process serving API and client assets
  • WebView Rendering: Swift WebView component displaying the React frontend
  • Standalone Deployment: Complete agent management system as independent macOS application

Implementation Approach: The Swift host starts a sidecar running the Bun full-stack server. Bun serves both the API and client assets, while a Swift WebView handles the rendering. This creates a fully standalone macOS app that could replace the current terminal-based workflow.

Technical Benefits

  • Native app performance and system integration capabilities
  • Professional user experience without browser dependencies
  • Desktop-class functionality with web technology flexibility
  • Simplified distribution through standard macOS app packaging
  • Integrated Terminal Support: Full terminal environment within the native app for Claude Code execution

Deployment Strategy Evolution

  • Terminal Workflow: Current development approach via command line
  • Standalone macOS App: Newly implemented native application deployment
  • Web Interface: Cross-platform browser-based access maintained
  • Future Mobile: Same architecture patterns applicable to mobile deployment

Cross-Platform Implications

This breakthrough demonstrates that the plugin architecture can seamlessly operate across: - Development environments (terminal-based) - Desktop applications (native macOS) - Web platforms (browser-based) - Potential mobile platforms (using similar native + web hybrid approach)

The native integration maintains all plugin functionality while providing professional desktop application user experience.

Terminal Integration Milestone (September 2025)

Breakthrough Achievement: Complete terminal environment integration within the native macOS application:

Implementation Details

  • Terminal Technology Stack: xterm for client-side rendering with bun-pty backend for session management
  • Real-time Communication: WebSocket connection streams terminal output and input between client and server
  • Dual Input Interface: Both direct terminal input and auxiliary text box for enhanced command entry
  • Claude Code Optimization: Terminal environment specifically designed for Claude Code bootstrapping and execution
  • Development Complexity: Implementation required significant engineering effort, indicating sophisticated terminal integration
  • Workflow Bridge: Seamless connection between visual plugin management and command-line development workflows

Technical Architecture

  • Frontend Terminal: xterm.js integration for professional terminal emulation within Swift WebView
  • Backend Process: bun-pty instance managing actual terminal sessions and command execution
  • Communication Layer: WebSocket-based real-time bidirectional communication for responsive terminal experience
  • Input Flexibility: Multiple input methods including traditional terminal interface and dedicated command input field

Technical Significance

  • Unified Development Environment: Combines GUI-based plugin management with direct terminal access
  • Agent Execution Platform: Provides dedicated environment for Claude Code agent development and testing
  • Native Performance: Terminal runs with full macOS integration benefits
  • Development Efficiency: Eliminates context switching between separate terminal applications
  • Professional Terminal Experience: Full-featured terminal emulation comparable to dedicated terminal applications

Developer Experience Impact

  • Integrated Workflow: Plugin development, testing, and Claude Code execution within single application
  • Reduced Friction: No need for separate terminal windows or applications
  • Enhanced Productivity: Direct access to command-line tools within the modular client environment
  • Professional Tooling: Desktop-class development experience with integrated terminal capabilities
  • Session Management: Advanced session resumption and configuration management capabilities

Use Cases

Personal Productivity

  • Unified interface for information management
  • Visual thinking with integrated drawing tools
  • Automated workflow processing

Development Workflow

  • Code analysis and documentation generation
  • Automated testing and deployment triggers
  • Multi-service integration management

Content Creation

  • Media generation and editing workflows
  • Document processing and formatting
  • Social media and marketing automation

Latest Developments (September 18, 2025)

Tldraw Whiteboard Integration Enhancement

Following recognition from Tldraw's official release notes featuring the original branching chats demo, the MCP Client has been enhanced with advanced Tldraw whiteboard capabilities:

  • Interactive Collaboration: Real-time collaborative whiteboard functionality integrated directly into the MCP development environment
  • Visual MCP Interactions: Enhanced ability to visualize and document MCP server interactions through sketching and diagramming
  • Starter Kit Integration: Leveraged Tldraw's new starter kit for branching chat experiences within the MCP Client
  • Video Documentation: Comprehensive demonstration showcasing the new whiteboard integration capabilities

Technical Implementation

  • SDK Integration: Full Tldraw SDK integration providing professional whiteboard experiences
  • Plugin Architecture: Tldraw functionality seamlessly integrated through the existing plugin system
  • Real-time Sync: Live collaborative features enabling team-based MCP development workflows
  • Visual Design Tools: Enhanced sketching, diagramming, and annotation capabilities for development documentation

This integration represents a significant advancement in visual development environments, providing both individual productivity enhancements and collaborative development capabilities within the MCP ecosystem.

Production Distribution (September 30, 2025)

MacOS App Distribution: Successfully deployed production distribution system for the native macOS application:

Distribution Infrastructure

  • Download Site: https://mcp-client-production-c177.up.railway.app/
  • Storage Platform: Railway S3-compatible buckets for DMG hosting
  • Validation Status: Bun sidecar approach for macOS validated and working end-to-end
  • Installation Process: Currently requires manual Privacy & Security approval pending notarization

Technical Validation

  • End-to-End Workflow: Complete download, installation, and execution pipeline operational
  • Native Experience: Professional macOS application experience with integrated terminal and plugin management
  • Production Ready: Demonstrates viability of Bun-based native application packaging
  • Distribution Template: Provides blueprint for packaging MCP tools as native applications

Current Limitations

  • Manual security approval required (notarization in progress)
  • Directory bootstrapping bug requiring resolution for full functionality
  • Path resolution issues in some environments requiring debugging

This production distribution milestone validates the transition from experimental development tool to production-ready application, providing a template for native MCP client distribution across platforms.

Canvas Integration Innovation (October 2025)

Breakthrough Development: Successfully implemented Claude Code execution directly within tldraw canvas environment, representing a novel approach to visual programming and agent interaction.

Technical Implementation

  • Visual Agent Interface: Claude Code agents can now operate directly within canvas-based design environments
  • Plugin Architecture Extension: Leverages existing modular plugin system to enable canvas-based agent execution
  • Interactive Development: Real-time agent interaction within visual programming spaces
  • Resource Visualization: Proposed "resource card" UI components for displaying MCP server capabilities within canvas

Development Status

  • Current Phase: Proof-of-concept successfully demonstrated with screenshot evidence
  • Directory Optimization: Code organization improvements needed for production readiness
  • UI Enhancement: Resource card interface for MCP server visualization in development
  • Integration Depth: Builds on existing robust tldraw plugin within MCP Client architecture

Innovation Significance

  • Visual Programming Paradigm: Represents shift from terminal-based to visual agent interaction models
  • Agent Accessibility: Makes AI tool capabilities more discoverable through visual resource representation
  • Collaborative Potential: Canvas environments enabling team-based agent development workflows
  • Development Experience: Bridges gap between visual design and programmatic agent execution

Future Implications

This canvas integration demonstrates the plugin architecture's flexibility for supporting innovative interface paradigms, potentially influencing broader visual programming and AI agent interaction patterns across development tools.

Automated Testing Infrastructure (October 2025)

Latest Development: Strategic planning for implementing automated UI testing using Railway preview environments and Playwright automation.

Testing Architecture Vision

  • Railway Preview Environments: Automated creation of isolated testing environments for each pull request
  • Playwright Agent Integration: Claude agent utilizing Playwright to perform automated UI testing
  • MCP Client Focus: Initial implementation targeting MCP Client as ideal candidate due to UI-heavy functionality and simplified architecture

Implementation Strategy

Target Application Characteristics: - Rich UI interface suitable for Playwright testing - No database dependencies simplifying environment setup - Extensive backlog of UI improvements and fixes for testing validation - Focus on UI and application logic rather than complex agent functionality testing

Development Workflow Benefits: - Automated testing for each PR through preview environments - Systematic validation of UI changes and improvements - Reduced manual testing burden for interface modifications - Integration with existing CI/CD workflows

Technical Advantages

  • Simplified Testing Scope: Avoiding complex agent functionality testing while focusing on UI validation
  • Isolated Environment Testing: Each PR gets dedicated testing environment preventing interference
  • Agent-Driven Automation: Leveraging Claude agent capabilities for intelligent test execution
  • Cost-Effective Infrastructure: Using Railway's built-in preview environment capabilities

Development Timeline

  • Current Phase: Planning and architecture design for testing integration
  • Next Steps: Implementation of Railway preview environment configuration
  • Target Outcome: Fully automated UI testing pipeline for MCP Client development
  • Broader Application: Template for automated testing across other UI-focused projects

This testing infrastructure development represents a significant evolution in MCP Client development practices, moving toward systematic automated validation of user interface improvements and ensuring higher quality releases.

The modular MCP client represents an innovative approach to agent management and plugin architecture, combining the flexibility of local development with the power of cloud-based automation workflows.