DollhouseMCP

# Session Notes - October 11, 2025 **Date**: October 11, 2025 **Time**: 11:07 AM - 12:30 PM (approx. 1h 23min) **Focus**: install-mcp integration, mcp-installer skill creation, and Bridge Elements epic planning **Outcome**: ✅ Created mcp-installer skill, tested successfully, created 21 GitHub issues for Bridge Elements ## Session Summary This session had two major accomplishments: 1. Created and tested the `mcp-installer` skill using the install-mcp tool 2. Transformed the Bridge Elements proposal into a comprehensive set of GitHub issues ## Part 1: install-mcp Tool Integration ### Discovery and Investigation User was frustrated with JSON editing for MCP server configuration files. Discussion led to discovery that tools like `install-mcp` already exist for this purpose. **Key Tool Found**: `install-mcp` by supermemoryai - GitHub: https://github.com/supermemoryai/install-mcp - Universal CLI tool for installing MCP servers to any client - Supports 14+ clients (Claude Desktop, Claude Code, Cursor, VS Code, etc.) - Handles config merging automatically - Cross-platform (macOS, Windows, Linux) ### Security Review Cloned user's fork at `/Users/mick/Developer/Organizations/mickdarling/install-mcp` and performed comprehensive security audit: **Dependencies Reviewed**: - All legitimate, well-maintained packages - No suspicious packages detected - Standard tools: consola, yargs, js-yaml, picocolors, giget, dotenv **Code Review Findings**: - ✅ No arbitrary eval() or Function() calls - ✅ No credential harvesting - ✅ Proper file I/O with error handling - ✅ Config merging preserves existing data (deepMerge function) - ✅ Comprehensive test coverage **Security Considerations (By Design)**: - Spawns `npx mcp-remote@latest` for OAuth (legitimate) - Writes to config files (expected behavior) - User confirms before execution **Verdict**: SAFE TO USE ✅ ### OAuth Authentication Clarification User questioned what OAuth authenticates to: - **Answer**: Authenticates YOU to the specific remote MCP server URL you're installing - NOT to install-mcp itself or any central service - Only applies to URL-based servers, skipped entirely for local stdio servers - Authentication tokens stored locally and shared across all MCP clients ## Part 2: mcp-installer Skill Creation ### Skill Design Created new DollhouseMCP skill: `mcp-installer` **Purpose**: Parse MCP server configuration JSON from documentation and install servers to any MCP client using the install-mcp tool. **Key Features**: - Accepts multiple input formats (full config JSON, server block only, package names, URLs) - Extracts server details automatically - Runs `npx install-mcp` with correct parameters - Verifies installation succeeded - Reminds user to restart target app **Skill Location**: `~/.dollhouse/portfolio/skills/mcp-installer.md` ### Skill Testing Successfully tested the skill twice: **Test 1: Install Playwright to Claude Desktop** ```json { "mcpServers": { "playwright": { "command": "docker", "args": ["run", "-i", "--rm", "mcp/playwright"] } } } ``` - ✅ Parsed JSON successfully - ✅ Executed: `npx install-mcp 'docker run -i --rm mcp/playwright' --client claude --name playwright --yes` - ✅ Verified in `/Users/mick/Library/Application Support/Claude/claude_desktop_config.json` - ✅ Preserved all existing servers **Test 2: Install Playwright to Claude Code** - Same JSON, different target - ✅ Installed to `~/.claude.json` - ✅ Config verified successfully ### Key Insight: The Paradigm Shift During testing, we identified a crucial value proposition for DollhouseMCP: **Without MCP Infrastructure**: - LLMs can only say "Here's what you should type..." - User must manually copy/paste commands - LLM is an advisor, not an agent **With MCP Infrastructure (DollhouseMCP)**: - LLM autonomously executes tasks - Skills = reusable agent behaviors - User just says "do it" and it happens **This is the paradigm shift**: From chatbot to autonomous agent framework. ### Technical Discussion Explored adding `--from-json` flag to install-mcp itself: - Would be straightforward (~50-100 lines) - Helps developers who want to script installations - But doesn't help LLMs without execution capability - DollhouseMCP skill approach enables any MCP-capable LLM to use it autonomously ## Part 3: Bridge Elements Epic Planning ### Context User provided comprehensive proposal document: `dollhouse-bridge-element-proposal.md` **Problem**: DollhouseMCP skills in sandboxed environments (Claude Desktop) can only provide guidance, not execute commands that affect the host filesystem. **Solution**: Bridge Elements - a new element type that enables command execution from sandboxed environments through containerization. ### Bridge Elements Design Overview **Key Decisions**: 1. **Advanced/Opt-In Feature**: Not required for core DollhouseMCP functionality 2. **Docker-First Implementation**: Phase 1 uses Docker (cross-platform, proven) 3. **Apple Container Future**: Phase 4+ adds native macOS 26 optimization 4. **Skill Fallback Pattern**: All skills work without bridges (provide guidance or recommend Claude Code) 5. **Security Through Isolation**: True OS-level containerization **Target Users**: - Power users comfortable with Docker - Users who prefer Claude Desktop but need file system automation - Users willing to trade setup complexity for convenience **Non-Target Users**: - Basic DollhouseMCP users (core features work without bridges) - Users who prefer simplicity (Claude Code is easier) - Users without Docker/container experience ### GitHub Issues Created Transformed the proposal into 21 GitHub issues in DollhouseMCP/mcp-server repository: **Epic Issue**: #1324 - [EPIC] Bridge Elements **Phase 1: Core Bridge Infrastructure (8 issues)** - #1325 - Define Bridge Element Schema - #1326 - Create Bridge Element Parser - #1327 - Design MCP Bridge Server Architecture (Docker-Based) - #1328 - Implement Docker Container Runner for Bridges - #1329 - Create install-mcp-bridge Proof-of-Concept - #1330 - Add Environment Detection Utilities for Skills - #1331 - Document Bridge Creation Process - #1332 - Create Docker Images for Bridges **Phase 2: Security & UX Polish (3 issues)** - #1333 - Implement User Approval Flow for Bridge Execution - #1334 - Implement Audit Logging for Bridge Executions - #1335 - Add Bridge Health Checks and Status Monitoring **Phase 3: Skill Integration & Documentation (3 issues)** - #1336 - Update mcp-installer Skill to Use Bridge - #1337 - Create Skill Fallback Guidance Templates - #1338 - Create "Running Skills Without Bridges" Guide **Phase 4: Expansion & Platform Optimization (3 issues)** - #1339 - Add Apple Container Support for macOS - #1340 - Create Additional Bridges (npm, git, filesystem) - #1341 - Community Bridge Submission Process **Phase 5: Enterprise & Advanced Features (3 issues)** - #1342 - Bridge Orchestration and Composability - #1343 - Resource Quotas and Rate Limiting for Bridges - #1344 - Multi-User and Team Bridge Configurations All issues properly labeled, linked to Epic, with acceptance criteria and dependencies. ### Bridge Elements Security Model **Container-Based Isolation**: - Phase 1: Docker containers with explicit volume mounts - True OS-level isolation (not just validation logic) - Network isolation (typically network=none) - Read-only root filesystem - Non-root user execution - Resource limits **Phase 4: Apple Container** (macOS 26+) - One-VM-per-container architecture - Hardware-level isolation - Sub-second startup - Native macOS integration - Reduced attack surface ### Implementation Strategy **Phase 1 Focus**: Proof-of-concept with Docker - Working install-mcp-bridge - Schema, parser, Docker runner, bridge server - Environment detection for skills - Comprehensive documentation **Success Criteria**: - Skills work consistently when bridge available - Skills provide clear guidance when bridge NOT available - No bridge required for basic DollhouseMCP functionality - Security model clear and auditable ## Key Learnings ### 1. DollhouseMCP as Agent Framework Skills + MCP tools + portfolio = autonomous agent capabilities. This is not just a collection of utilities, it's an agent framework where: - Skills define reusable behaviors - MCP provides tool access - Portfolio stores personal agent capabilities - LLM orchestrates everything ### 2. Unix Philosophy Applied to Agent Tools `install-mcp` exemplifies doing one thing well: - Universal (14+ clients) - Smart merging (preserves existing configs) - No malicious code - Cross-platform - Simple interface This is exactly what we want for DollhouseMCP tools. ### 3. Security Through Opt-In Bridge elements demonstrate good security design: - Advanced feature, not required - User self-selection (Docker requirement naturally filters) - True isolation through containers - Explicit setup demonstrates intent - Alternative exists (Claude Code) ### 4. Skill Fallback Patterns All skills that need filesystem access should: 1. Detect environment first 2. Check for bridge availability 3. Use bridge if available 4. Provide clear guidance if not 5. Never fail silently 6. Offer alternatives (Claude Code, manual, bridge setup) ### 5. Issue Organization Best Practices Breaking large features into phases works well: - Each phase has clear goal - Dependencies explicit - Can ship incrementally - Community can contribute at any phase ## Next Session Priorities ### Immediate (Phase 1 - Start) 1. Begin #1325 (Define Bridge Schema) 2. Create bridge element schema with security fields required 3. Example bridge YAML for reference ### Short Term (Phase 1 - Complete) 4. Implement parser and Docker runner 5. Create install-mcp-bridge POC 6. Test end-to-end from Claude Desktop ### Documentation 7. Write "Creating Your First Bridge" guide 8. Write "Running Skills Without Bridges" guide 9. Update mcp-installer skill to use bridge when available ### Future Considerations - Apple Container implementation (Phase 4) - Additional bridges (npm, git, filesystem) - Community submission process - Enterprise features (Phase 5) ## Technical Notes ### Files Created/Modified - `~/.dollhouse/portfolio/skills/mcp-installer.md` - New skill created - `/Users/mick/Library/Application Support/Claude/claude_desktop_config.json` - Playwright server added - `~/.claude.json` - Playwright server added - 21 GitHub issues in DollhouseMCP/mcp-server ### Tools Verified - install-mcp security audit passed - Tool works as advertised - No permission issues - Merge behavior confirmed safe ### Commands Used ```bash # Clone and audit install-mcp git clone https://github.com/mickdarling/install-mcp.git # Test skill - Install to Claude Desktop npx install-mcp 'docker run -i --rm mcp/playwright' --client claude --name playwright --yes # Test skill - Install to Claude Code npx install-mcp 'docker run -i --rm mcp/playwright' --client claude-code --name playwright --yes # Create GitHub issues gh issue create --title "..." --body "..." --label "..." ``` ## Artifacts ### Session Deliverables 1. ✅ mcp-installer skill created and tested 2. ✅ install-mcp security audit completed 3. ✅ 21 GitHub issues created for Bridge Elements 4. ✅ Epic #1324 created and updated with issue links ### Documentation URLs - Epic: https://github.com/DollhouseMCP/mcp-server/issues/1324 - install-mcp fork: https://github.com/mickdarling/install-mcp - Skill location: ~/.dollhouse/portfolio/skills/mcp-installer.md ## Session Metrics - **Duration**: ~1 hour 23 minutes - **Issues Created**: 21 - **Skills Created**: 1 (mcp-installer) - **Security Audits**: 1 (install-mcp) - **Successful Tests**: 2 (Claude Desktop + Claude Code) - **Lines of Code Reviewed**: ~1000+ (install-mcp codebase) ## Collaboration Notes ### User Preferences Observed - Prefers direct file operations over abstractions - Values Unix philosophy (do one thing well) - Security-conscious (wanted full audit before use) - Appreciates clear explanations of "why" - Wants proper GitHub issues, not just markdown files ### Communication Style - Technical and detailed - Appreciates architectural discussions - Wants to understand paradigm shifts - Prefers showing over telling (demonstrations) --- **Status**: Session complete, deliverables committed, ready for next session to begin Phase 1 implementation.