DollhouseMCP

# Claude Code Plugin Integration Research **Document Version**: 1.0.0 **Date**: October 2025 **Status**: Exploratory Research --- ## Executive Summary This document analyzes Claude Code's plugin system and explores potential integration patterns for DollhouseMCP. The research evaluates technical feasibility, architectural approaches, and identifies gaps between documented capabilities and practical implementation. ### Research Objectives 1. Understand Claude Code plugin architecture and capabilities 2. Evaluate potential DollhouseMCP integration patterns 3. Identify technical constraints and opportunities 4. Assess compatibility with existing MCP server functionality --- ## Plugin System Overview ### Confirmed Capabilities From official Claude Code documentation: - Plugins support slash commands, agents, hooks, and MCP servers - Structure: `.claude-plugin/`, `commands/`, `agents/`, `hooks/` - Distribution via GitHub repositories - Marketplace configuration with JSON manifests ### Speculative Features Features mentioned in community discussions but requiring validation: - Specific token savings percentages (60-90%) - Hook implementation details (bash scripts with additionalContext) - 15K character budget limits - Auto-clearing of context after messages ### Research Approach Focus on documented features for initial exploration. Speculative capabilities should be validated through testing before relying on them in production implementations. --- ## Architecture Analysis ### Proposed Integration Pattern ``` ┌──────────────────────────────────────────┐ │ Claude Code CLI │ ├──────────────────────────────────────────┤ │ DollhouseMCP Plugin (Potential) │ │ ┌────────────────────────────────────┐ │ │ │ Slash Commands │ │ │ │ /dollhouse enable → activate_element│ │ │ │ /dollhouse status → get_active │ │ │ └────────────────────────────────────┘ │ ├──────────────────────────────────────────┤ │ DollhouseMCP MCP Server (Existing) │ │ All business logic remains here │ └──────────────────────────────────────────┘ ``` ### Design Principle Plugin as UX Enhancement Layer: The plugin would serve as a user experience enhancement, not a logic layer. All business logic remains in the MCP server, ensuring compatibility and maintainability. --- ## Technical Implementation Analysis ### Repository Structure A potential plugin structure could look like: ``` DollhouseMCP/claude-code-plugin/ ├── .claude-plugin/ │ ├── plugin.json # Plugin metadata │ └── marketplace.json # Marketplace configuration ├── commands/ │ ├── dollhouse-enable.md # /dollhouse enable │ ├── dollhouse-disable.md # /dollhouse disable │ ├── dollhouse-status.md # /dollhouse status │ ├── dollhouse-search.md # /dollhouse search │ └── dollhouse-help.md # /dollhouse help ├── README.md # User guide └── LICENSE # AGPL-3.0 ``` ### Plugin Manifest ```json { "name": "dollhousemcp", "version": "1.0.0", "description": "Enhanced commands for DollhouseMCP AI customization", "author": "DollhouseMCP", "license": "AGPL-3.0", "repository": "https://github.com/DollhouseMCP/claude-code-plugin", "requires": { "mcpServers": ["@dollhousemcp/mcp-server"] } } ``` ### Marketplace Configuration ```json { "name": "DollhouseMCP Official Plugins", "owner": "DollhouseMCP", "plugins": [ { "name": "dollhousemcp", "description": "Simplified commands for DollhouseMCP elements", "source": "./", "version": "1.0.0", "tags": ["productivity", "ai-customization", "mcp"] } ] } ``` ### Command Implementation Pattern Example command structure for element activation: ```markdown --- description: Enable a DollhouseMCP element (persona, skill, template, etc.) argument-hint: element-name --- Enable the DollhouseMCP element: {{element_name}} First, use the search_portfolio tool to find "{{element_name}}" in the portfolio. If found, use the activate_element tool to enable it. Confirm activation by showing the element details. If not found, suggest similar elements using fuzzy matching. ``` ### Potential Command Set | Command | Purpose | MCP Tool Mapping | |---------|---------|------------------| | `/dollhouse enable [element]` | Activate element | `activate_element({name: element})` | | `/dollhouse disable [element]` | Deactivate element | `deactivate_element({name: element})` | | `/dollhouse status` | Show active elements | `get_active_elements()` | | `/dollhouse search [query]` | Find elements | `search_portfolio({query})` | --- ## Integration Points ### Command to MCP Tool Mapping ```typescript // Plugin commands would map to existing MCP tools '/dollhouse enable X' → mcp.activate_element({name: X}) '/dollhouse disable X' → mcp.deactivate_element({name: X}) '/dollhouse status' → mcp.get_active_elements() '/dollhouse search X' → mcp.search_portfolio({query: X}) ``` ### Critical Implementation Considerations 1. **Element Naming**: Must handle variations (kebab-case, spaces, capitals) 2. **Search Functionality**: Leverage existing fuzzy matching capabilities 3. **Error Messages**: User-friendly responses with correction suggestions 4. **MCP Dependency**: Graceful handling if MCP server not installed 5. **Version Compatibility**: Ensure plugin works across MCP server versions --- ## Benefits Analysis ### User Experience Improvements 1. **Simplified Syntax**: Slash commands vs. tool invocation syntax 2. **Discoverability**: Built-in command completion and hints 3. **Reduced Cognitive Load**: Familiar command-line interface patterns 4. **Consistency**: Standardized interaction model ### Technical Benefits 1. **Thin Integration Layer**: Minimal maintenance overhead 2. **Backwards Compatible**: Works alongside existing MCP tools 3. **Modular**: Plugin can be installed independently 4. **Open Source**: Community contributions and transparency --- ## Risk Assessment | Risk | Probability | Impact | Mitigation Strategy | |------|------------|--------|-------------------| | Hook capabilities limited | Medium | Low | Focus on slash commands initially | | MCP server compatibility issues | Low | High | Extensive testing, thin plugin layer | | Installation complexity | Medium | High | Clear documentation, troubleshooting guide | | Limited adoption | Medium | Low | Set realistic expectations, iterate based on feedback | --- ## Evaluation Criteria ### Technical Feasibility - ✅ Slash commands are well-documented - ✅ MCP server integration is straightforward - ⚠️ Hook capabilities need validation - ⚠️ Token optimization claims need testing ### User Value - ✅ Simplifies common operations - ✅ Reduces syntax complexity - ✅ Improves discoverability - ✅ Familiar command-line patterns ### Maintenance Considerations - ✅ Thin layer, minimal logic - ✅ Leverages existing MCP tools - ⚠️ Requires Claude Code version compatibility tracking - ⚠️ Plugin system maturity is unknown --- ## Future Exploration Areas ### Phase 1: Basic Commands (Validated) - Simple slash commands for element management - Status and search functionality - Basic error handling ### Phase 2: Hooks (Requires Validation) - Project detection with `.dollhouse-project.json` - Auto-loading based on directory context - Session persistence mechanisms ### Phase 3: Smart Loading (Requires Validation) - Capability Index integration - Context-aware element selection - Token usage optimization (if supported) ### Phase 4: Advanced Features (Long-term) - Custom agents for specialized tasks - Team collaboration features - Analytics and usage tracking --- ## Key Technical Insights ### Capability Index Considerations The DollhouseMCP Capability Index (46K tokens) serves as a client-side search engine. It's important to note: - Index is never loaded into Claude's context - Provides fast element lookup without token cost - Enables fuzzy matching and semantic search - Could be leveraged by plugin for intelligent suggestions ### Plugin vs. MCP Server Boundary Clear separation of concerns: - **Plugin**: User interface layer (commands, formatting, help text) - **MCP Server**: Business logic (activation, search, validation, state management) - **Benefit**: Plugin updates don't require MCP server changes --- ## Compatibility Analysis ### Advantages of Plugin Approach 1. **Existing User Base**: Current DollhouseMCP users could adopt immediately 2. **Proven Architecture**: MCP server is stable and well-tested 3. **Unique Features**: Capability Index provides differentiation 4. **Open Source**: Aligns with community values and contribution model ### Integration Challenges 1. **Version Synchronization**: Plugin and MCP server version compatibility 2. **Error Handling**: Graceful degradation if MCP server unavailable 3. **Documentation**: Clear explanation of plugin + MCP relationship 4. **Testing**: Validation across different Claude Code versions --- ## Related Research ### Documentation References - [Claude Code Plugins Docs](https://docs.claude.com/en/docs/claude-code/plugins) - [Plugin Marketplaces](https://docs.claude.com/en/docs/claude-code/plugin-marketplaces) - [DollhouseMCP MCP Server](https://github.com/DollhouseMCP/mcp-server) ### Community Examples - Dan Avila's Templates: Different focus (templates vs. elements) - Various MCP servers: No documented plugin integrations yet ### Internal References - Capability Index documentation - Multi-agent architecture discussions (Issues #1252-1269) - Element management API documentation --- ## Conclusions ### Technical Feasibility: **High** The documented Claude Code plugin system provides clear pathways for integration. Slash commands offer immediate, tangible value with minimal technical risk. ### User Value: **Medium to High** Simplified command syntax and improved discoverability would benefit both new and existing users. The value proposition is clearest for frequent element management operations. ### Implementation Complexity: **Low to Medium** A thin plugin layer mapping to existing MCP tools represents straightforward implementation. Main complexity lies in error handling and user experience polish. ### Recommendation: **Worth Exploring** A minimal viable plugin focusing on slash commands would provide useful data on: - Actual user adoption and usage patterns - Integration challenges with Claude Code updates - Real-world value vs. direct MCP tool usage - Foundation for more advanced features if warranted ### Next Steps for Evaluation 1. Validate hook capabilities through testing 2. Create prototype with core slash commands 3. Gather user feedback on command design 4. Assess installation friction and documentation needs 5. Evaluate maintenance burden vs. user value --- ## Research Status This document represents exploratory research as of October 2025. Implementation decisions should be based on: - Validation of speculative features - User demand signals - Resource availability - Strategic alignment with project goals The research provides a foundation for informed decision-making but does not constitute a commitment to implementation. --- *Document created: October 2025* *Status: Exploratory Research* *Next review: When Claude Code plugin ecosystem matures*