DollhouseMCP

# Session Notes - October 16, 2025 (Late Evening) **Date**: October 16, 2025 **Time**: Late evening (pre-dinner) **Focus**: Completing PR #1361 telemetry opt-in implementation and realizing the elegant MCP config solution **Outcome**: ✅ Fully functional opt-in telemetry with simple configuration path --- ## Session Summary Completed the telemetry opt-in implementation for PR #1361 and discovered the elegant solution: MCP server configuration via `env` vars in the JSON config is the standard, legitimate pattern. No complex tooling needed - users can simply add environment variables to their existing MCP config. --- ## Key Achievements ### 1. **Simplified Opt-In Implementation** **Changed from:** - Complex POSTHOG_API_KEY requirement - No embedded key - Users had to get their own PostHog account **Changed to:** - Simple `DOLLHOUSE_TELEMETRY_OPTIN=true` flag - Embedded PostHog project key in code (safe, write-only) - Backward compatible with custom POSTHOG_API_KEY **PostHog Key Added:** `phc_xFJKIHAqRX1YLa0TSdTGwGj19d1JeoXDKjJNYq492vq` ### 2. **Fixed Documentation Gap** **Critical Error Found:** - README told users to `export DOLLHOUSE_TELEMETRY_OPTIN=true` in shell profile - **This doesn't work** - MCP servers don't use shell profiles! - MCP servers are configured via JSON files with `env` objects **Fixed:** ```json { "mcpServers": { "dollhousemcp": { "command": "node", "args": ["/path/to/mcp-server/dist/index.js"], "env": { "DOLLHOUSE_TELEMETRY_OPTIN": "true" // ← This is how } } } } ``` ### 3. **The Elegant Realization** **Key Insight:** MCP server configuration via `env` vars IS the standard pattern. **Why This Works:** 1. Users already edit the JSON to add DollhouseMCP 2. Adding telemetry is just one more line in the `env` object 3. DollhouseMCP has file editing skills - can automate this 4. It's the **official MCP specification pattern** (not a hack!) **Confirmed:** Every MCP server uses `env` vars for configuration. This is how it's meant to work. --- ## Technical Implementation ### Code Changes (PR #1361) **1. OperationalTelemetry.ts (src/telemetry/OperationalTelemetry.ts:50)** ```typescript // PostHog Project API Key (safe to expose publicly - write-only) const DEFAULT_POSTHOG_PROJECT_KEY = 'phc_xFJKIHAqRX1YLa0TSdTGwGj19d1JeoXDKjJNYq492vq'; ``` **2. Opt-In Logic (src/telemetry/OperationalTelemetry.ts:79-139)** ```typescript // Three ways to enable: // 1. POSTHOG_API_KEY (custom key, takes precedence) // 2. DOLLHOUSE_TELEMETRY_OPTIN=true (uses default key) // 3. Neither set (remote telemetry disabled) ``` **3. Documentation Updates** - README.md: Added MCP config examples for Claude Desktop and Claude Code - docs/privacy/OPERATIONAL_TELEMETRY.md: Simple opt-in section - docs/development/TELEMETRY_INCENTIVE_STRATEGY.md: Future program strategy ### Testing - ✅ All 50 telemetry tests pass - ✅ TypeScript compilation successful - ✅ Backward compatibility maintained - ✅ PostHog key works (tested) --- ## Configuration Context ### Two Separate Config Files **Important Distinction:** 1. **`~/.dollhouse/config.yml`** - DollhouseMCP's internal settings - User identity, GitHub settings, sync preferences - Managed via `dollhouse_config` MCP tool - Example shown by user: ```yaml version: 1.0.0 user: username: (not set - anonymous mode active) github: portfolio: repository_name: dollhouse-portfolio sync: enabled: false elements: enhanced_index: enabled: true ``` 2. **`~/Library/Application Support/Claude/claude_desktop_config.json`** - MCP client config - Where MCP servers are defined - Where `env` vars are set for each server - **This is where telemetry opt-in goes** - Example: ```json { "mcpServers": { "dollhousemcp": { "command": "node", "args": ["/path/to/server"], "env": { "DOLLHOUSE_TELEMETRY_OPTIN": "true" } } } } ``` ### Why This Matters **MCP server env vars ≠ DollhouseMCP config** - Telemetry opt-in → MCP server config (claude_desktop_config.json) - User preferences → DollhouseMCP config (config.yml) - They serve different purposes --- ## Next Session Priorities ### 1. **Programmatic Config Modification** **Goal:** Enable users to opt in via LLM conversation **Approach:** - Use DollhouseMCP's file editing skills - Target: `claude_desktop_config.json` - User asks: *"Enable telemetry for DollhouseMCP"* - Agent/skill modifies JSON, adds env var - User restarts MCP client **Technical Challenge:** - Need to locate the right config file - Parse JSON safely - Add `env.DOLLHOUSE_TELEMETRY_OPTIN` to dollhousemcp section - Preserve all other config ### 2. **Visual Instructions** **Goal:** Make manual editing super easy for non-technical users **Create:** - Step-by-step guide with screenshots - Copy-paste examples for each platform - Before/after JSON examples - Clear "restart required" messaging **Platforms to cover:** - Claude Desktop (macOS, Windows, Linux) - Claude Code (VS Code extension settings) - Other MCP clients ### 3. **Verify Environment Setup** **Questions to answer:** - What's the best way to detect the MCP client being used? - Where are config files on each platform? - Can we provide a diagnostic tool to verify telemetry status? --- ## Commits Made 1. **3594ae7e** - `feat: Simplify telemetry opt-in with DOLLHOUSE_TELEMETRY_OPTIN flag` - Rewrote initPostHog() with three enablement paths - Added DEFAULT_POSTHOG_PROJECT_KEY constant - Updated documentation 2. **5ddb02dc** - `feat: Add PostHog project API key for opt-in telemetry` - Added real PostHog key - Tested and verified 3. **87b0a8e3** - `docs: Fix telemetry opt-in instructions for MCP configuration` - Corrected README with JSON config examples - Removed incorrect shell export instructions --- ## Key Learnings ### 1. **MCP Config Pattern is Standard** The `env` section in MCP server config is **THE** configuration mechanism for MCP servers. It's not a hack - it's how the protocol is designed. **Every MCP server uses it:** - Filesystem servers: paths via env vars - Database servers: connection strings via env vars - API servers: keys via env vars ### 2. **Documentation Must Match Implementation** **Critical mistake:** Telling users to `export` env vars when MCP servers use JSON config. **Lesson:** Always verify how the actual runtime environment receives configuration. ### 3. **Simple is Better** **Overcomplicated approach:** - Build MCP tools to modify config - Create wizards and interactive flows - Try to work around the config file **Simple approach:** - Document the JSON config pattern - Provide clear examples - Use existing file editing skills if automation needed ### 4. **DollhouseMCP Config vs MCP Server Config** **Two different things:** - DollhouseMCP's `config.yml` = application settings (user, sync, elements) - MCP client's JSON = server configuration (command, args, **env vars**) Telemetry opt-in is an **operational setting** → belongs in MCP server env vars, not DollhouseMCP config. --- ## Questions for Tomorrow 1. **File Editing Approach** - Can DollhouseMCP safely edit `claude_desktop_config.json`? - What about other MCP clients' config files? - Should we create a dedicated skill for this? 2. **User Experience** - What's the ideal workflow: *"Enable DollhouseMCP telemetry"* - Should we detect which MCP client is running? - How do we verify opt-in status? 3. **Documentation Strategy** - Where do visual guides go? - Do we need platform-specific instructions? - Should we create a video walkthrough? --- ## Files Modified **Code:** - `src/telemetry/OperationalTelemetry.ts` - Opt-in implementation **Documentation:** - `README.md` - Fixed MCP config instructions - `docs/privacy/OPERATIONAL_TELEMETRY.md` - Updated opt-in section - `docs/development/TELEMETRY_INCENTIVE_STRATEGY.md` - Future strategy **Session Notes:** - This file --- ## PR Status **PR #1361:** Open, ready for review/merge - ✅ All tests passing - ✅ Documentation updated - ✅ PostHog key added - ✅ Simple opt-in implementation complete **Next steps:** 1. Determine if additional automation/tooling needed 2. Create user-friendly guide for manual opt-in 3. Consider skill/agent for programmatic opt-in 4. Merge when ready --- ## Session Completed **Time spent:** ~2 hours **Outcome:** Fully functional opt-in telemetry with clear path forward **Blocker removed:** Documentation now shows correct MCP config pattern **Ready to go:** Users can opt in right now by editing their MCP config JSON. **Tomorrow:** Figure out best automation approach and create killer user documentation. 🤖 Generated with Claude Code --- *End of session notes*