• Restore the management console's stronger responsive header behavior, including cleaner tab overflow handling and keyboard-accessible menu navigation.
• Fix MCP-AQL agent execution loop guidance and recovery messaging so smaller models get clearer lifecycle instructions, stronger parameter errors, and better get_execution_state correction hints.

[2.0.31] - 2026-04-22

• Fix Codex PreToolUse silent allow handling and expand permission hook diagnostics.

2.0.30

• Improve hook reliability across Codex and other supported clients, including fail-open JSON behavior.
• Automatically refresh stale local hook assets and surface repair outcomes in status/build info.
• Add session platform metadata, update-available labeling, and cleaner dropdown alignment in the web console.

2.0.29

• Added explicit session platform metadata and update-available status in the web console session dropdown
• Improved dropdown alignment for session status, platform, and uptime columns
• Fixed Codex pre-tool-use hook JSON output and expanded hook contract coverage across supported clients
• Automatically verify and refresh installed local permission hook assets when they go stale

DollhouseMCP 2.0.28

• Add explicit session client metadata and update-available status in the web console dropdown, with improved layout alignment.
• Fix Codex pre-tool-use allow-hook output so Bash permission checks no longer fail with invalid JSON.
• Audit and document permission-hook contracts across supported clients, including stronger fail-open regression coverage and setup guidance.

DollhouseMCP v2.0.27\n\nThis stable point release is built from the safe hotfix line off v2.0.26.\n\n### Included\n- web console favicon\n- running version in the footer\n- responsive header cleanup at mid widths\n- packaging fix for permission port discovery helper\n- tarball-level package verification in CI\n

What's Changed

• Support root-path worker verification compatibility by @mickdarling in https://github.com/DollhouseMCP/mcp-server/pull/2043
• Fix Codex TOML setup detection by @mickdarling in https://github.com/DollhouseMCP/mcp-server/pull/2046
• Recover permission hook port discovery when latest file is missing by @mickdarling in https://github.com/DollhouseMCP/mcp-server/pull/2051
• Add Dockerized cross-platform permission hook harness by @mickdarling in https://github.com/DollhouseMCP/mcp-server/pull/2052
• Add permission authority foundation by @mickdarling in https://github.com/DollhouseMCP/mcp-server/pull/2054
• Polish authority mode permissions UX by @mickdarling in https://github.com/DollhouseMCP/mcp-server/pull/2056
• Polish permissions debug views and audit modal UX by @mickdarling in https://github.com/DollhouseMCP/mcp-server/pull/2057
• Add first-class session identity surfaces by @mickdarling in https://github.com/DollhouseMCP/mcp-server/pull/2059
• Patch Dependabot alerts for dompurify and hono by @mickdarling in https://github.com/DollhouseMCP/mcp-server/pull/2060
• Release 2.0.26 by @mickdarling in https://github.com/DollhouseMCP/mcp-server/pull/2061

Full Changelog: https://github.com/DollhouseMCP/mcp-server/compare/v2.0.25...v2.0.26

Highlights

• restore the permissions audit modal markdown copy action
• surface direct commercial license email delivery failures instead of falsely reporting success
• move direct verification email requests onto a public worker path with rate limiting and cooldowns instead of a client-shared secret
• harden the license email worker validation and cleanup around the new direct delivery flow

• Fix web console authority convergence so newer sessions replace stale listeners, register correctly, and serve current assets.

Highlights

• Expand npm package keywords for broader discovery across MCP clients, AI tool ecosystems, and Dollhouse element primitives.

Full Changelog

• Merge release PR #2036: release: 2.0.23

Highlights

• Fix legacy console leader takeover so new authenticated sessions can replace older incompatible port owners and register correctly.
• Preserve safer bind recovery behavior while allowing intentional replacement of legacy/incompatible leaders that would otherwise keep serving stale console state.

Full Changelog

• Merge hotfix PR #2035: Replace legacy console leaders on bind recovery

• Sanitize OAuth and PAT helper logging to restore SonarCloud security quality

Point release for console leader bind authority and session registration recovery.

Includes:

• provisional console leadership until the HTTP listener successfully binds
• follower fallback and real-leader registration when bind fails
• safer stale-process recovery so live Claude/Codex-backed MCP servers are not evicted
• additional logging and recovery hardening for troubleshooting production console startup issues

Summary

• ship the deadlock relief recovery flow from #2027
• ship version-aware web console leadership from #2028
• add cache-busted console reloads so browser tabs move to the newest compatible leader

Included PRs

• #2027
• #2028
• #2029

2.0.18

• Expanded permission setup and support-matrix clarity across supported clients.
• Added stronger gatekeeper validation, activation diagnostics, and audit tooling.
• Fixed Claude Code hook response-shape compatibility.
• Improved the permissions audit modal with richer entries, persistent expansion state, and Markdown export.
• Stabilized Extended Node Compatibility coverage for release CI.

What's Changed

• Sync main back into develop after 2.0.15 release by @mickdarling in https://github.com/DollhouseMCP/mcp-server/pull/1972
• Sync main back into develop after 2.0.16 release by @mickdarling in https://github.com/DollhouseMCP/mcp-server/pull/1987
• Expand permission reporting and Codex hooks by @mickdarling in https://github.com/DollhouseMCP/mcp-server/pull/1995
• Expand platform setup and permission hook support by @mickdarling in https://github.com/DollhouseMCP/mcp-server/pull/1997
• Clarify gatekeeper policy authoring examples by @mickdarling in https://github.com/DollhouseMCP/mcp-server/pull/1999
• Validate malformed gatekeeper policy on create and save by @mickdarling in https://github.com/DollhouseMCP/mcp-server/pull/2000
• Release 2.0.17 by @mickdarling in https://github.com/DollhouseMCP/mcp-server/pull/2001

Full Changelog: https://github.com/DollhouseMCP/mcp-server/compare/v2.0.16...v2.0.17

What's Changed

• Fix MCP Registry publish verification by @mickdarling in https://github.com/DollhouseMCP/mcp-server/pull/1970
• Fix permission hook wiring and session enforcement by @mickdarling in https://github.com/DollhouseMCP/mcp-server/pull/1981
• Release 2.0.16 by @mickdarling in https://github.com/DollhouseMCP/mcp-server/pull/1986

Full Changelog: https://github.com/DollhouseMCP/mcp-server/compare/v2.0.15...v2.0.16

Fixes

• Automate stable MCP bundle (.mcpb) release publishing
• Keep manifest and package versions synchronized during releases
• Harden release verification with signed publisher checks, checksum assets, upload retries, and workflow attestations

Fixes

• Permissions console reporting, audit feed routing, and session UX hardening
• Permissions tab dark mode rendering fixes
• Numeric YAML version deserialization fix for two-component versions like 1.1

What's Changed

Security Fixes

• False-positive CRITICAL alerts eliminated — bundled elements containing legitimate YAML keys (javascript:) or educational security payloads (wget in pentest templates) no longer fire CRITICAL alerts at install time (#1941)
• JavaScript protocol injection regex tightened — pattern now requires a non-whitespace character after the colon (javascript[ \t]*:[ \t]*\S), preventing bare YAML map keys from matching while still catching real javascript:void(0) injection attempts (#1941)
• Bundled element trust system — build generates data/HASHES.json; at startup, DefaultElementProvider verifies each bundled file against its SHA-256 and registers matching hashes with ContentValidator; verified content bypasses injection scanning, modified files automatically lose trust (#1941)

CI/CD

• OIDC publishing restored — removed broken npm install -g npm@11 step that caused every publish workflow to fail with MODULE_NOT_FOUND: promise-retry; npm 10.x (ships with Node 22) already supports --provenance (#1941)

Full Changelog

https://github.com/DollhouseMCP/mcp-server/blob/main/CHANGELOG.md

What's New in v2.0.12

Authenticated Web Console

The management console at http://dollhouse.localhost:41715 now requires authentication. Console sessions are issued signed tokens; TOTP enrollment provides a second factor for sensitive operations such as token rotation.

• Session token auth — console issues a signed bearer token on first connect; subsequent requests require it (#1787)
• TOTP enrollment — Phase 2 interactive TOTP setup with QR code, ±60s validation window, rate limiting (#1794)
• Auth tab — dedicated tab surfaces the active token, enrollment flow, and session event log (#1807)
• CLI token commands — dollhousemcp token show/rotate/revoke manage the console token from the terminal (#1790)
• Browser 401 recovery — expired-session toast with one-click re-auth, no full-page reload (#1792)
• Token rotation — TOTP-confirmed rotation endpoint; HTML cache auto-invalidates on rotation (#1795, #1804)
• Permanent port 41715 — "AILIS" on a phone keypad; env-var overridable (#1798)

Setup Tab & Install Experience

• Release channel selector — switch between Stable, RC, and Beta channels; config snippets update live (#1835)
• License selector — commercial license activation with email verification on the Setup tab (#1826, #1831)
• Setup tab per-version — tab reopens once per new version so users see what changed, then stays out of the way (#1905)
• NVM-aware launcher — install script auto-detects and wires NVM so node is always in PATH on restart (#1902)
• Cleaner install UX — channel label, button state clears on channel change, current config refreshes after install (#1850, #1862, #1864)

Permission Server

• Hook-based agent permissioning — dollhousemcp-permission-server evaluates Gatekeeper policies for external hooks, enabling autonomous agent approval flows outside the MCP session (#1777)

Element Reliability Fixes

• Template variable auto-derive — {{placeholder}} tokens in template content are automatically registered as variable schema entries on save; renders never silently return unfilled text (#1896)
• Ghost session cleanup — sessions that return 404 on kill are now reaped from the active list; permanent kill + pending kill flows unified (#1870)
• Ensemble stale cache — LRU cache flushed on ensemble activation so newly added members appear immediately (#1895)
• Agent storage index — index updated correctly after create, fixing stale list after first agent add (#1877)
• Ensemble member deactivation — members deactivate cleanly without leaving orphaned state (#1878)
• Template variable routing — normalization hardened so variables survive round-trip edits (#1879)
• Memory addEntry transport — transport-layer regression for memory entries resolved (#1880)
• Content-only agent creation — agents can now be created with content only, without requiring all metadata fields (#1893)

Security

• NFC normalization on web routes — all route name and file parameters are NFC-normalized before path traversal checks, closing a Unicode homograph bypass (#1736)
• Hono CVE — pinned hono 4.12.12 and @hono/node-server 1.19.13 via npm overrides (#1908)
• Startup error sanitization — production startup failures no longer leak stack traces or internal paths (#1848)
• Vulnerability triage — osv-scanner.toml, GHSA reclassification monitor, Dependabot alert triage tooling (#1800)

Developer Experience

• Console discovery hints — element list/search/activate operations surface the console URL so LLMs can direct users there (#1849)
• Session auth status indicators — two-dimension status badge in session dropdown shows auth state at a glance (#1805)
• Web console regressions — comprehensive fix pass covering tabs, sinks, Auth panel init, and leader/follower edge cases (#1881)

Breaking Change

The web console default port moved 3939 → 41715. Update bookmarks and any scripts referencing localhost:3939.

Install: claude mcp add dollhousemcp -- npx -y @dollhousemcp/mcp-server

Desktop Extension: Download dollhousemcp-2.0.12.mcpb below and double-click to install in Claude Desktop.

Full changelog: https://github.com/DollhouseMCP/mcp-server/blob/main/CHANGELOG.md

v2.0.11

Critical Bug Fix

• npx one-liner silently exits on fresh machines — npx @dollhousemcp/mcp-server@latest --web did nothing on computers without a prior DollhouseMCP install. The v2.0 rewrite replaced Node's symlink-aware import.meta.url check with raw process.argv[1] path matching, which missed the mcp-server bin symlink. Fixed with three layers of defense:
  • Symlink resolution via realpathSync so .bin/mcp-server → dist/index.js is detected
  • Modern npx detection via npm_command === 'exec' (npm v7+ no longer sets npm_execpath to include 'npx')
  • Bin name matching for both dollhousemcp and mcp-server entries

Security

• Sanitized startup error logging — production no longer leaks full stack traces and internal paths on startup failure. Debug details require DOLLHOUSE_DEBUG=true.

Upgrade

npx @dollhousemcp/mcp-server@latest

Or restart your MCP client to pick up the new version.

v2.0.10

Features

• get_capabilities operation — discover all 73+ server operations grouped by 14 user-intent categories. Extensible provider pattern ready for portfolio element capabilities.
• Setup completion flow — after installing to MCP clients, a banner guides users through next steps. Terminal accepts q/quit/exit to exit the installer.
• URL parameter deep-linking — console URLs accept query parameters (#portfolio?q=axiom&type=persona, #logs?level=error&since=1h) for pre-populated search, filters, and navigation from any system.
• Brand logo — DollhouseMCP house logo in the console header.

Bug Fixes

• Ensemble activation registration — ensembles now properly register member elements with type managers. get_active_elements correctly reports ensemble-activated elements.
• addEntry error messages — markdown content failures provide diagnostic hints about JSON encoding. Tool description documents markdown support and escaping rules.
• Ensemble example in tool description — valid roles (primary, support, override, monitor, core) derived dynamically from source constants.

Maintenance

• ts-jest 29.4.9 — clears 17 Dependabot alerts (2 critical, 8 high)
• Node engines — >=18.0.0 for broader compatibility

Upgrade

npx @dollhousemcp/mcp-server@latest

Or restart your MCP client to pick up the new version.

Fix: MCP stdio corruption on Claude Desktop

What changed

• Fixed: Web console banner was written to stdout via console.log, corrupting the JSON-RPC protocol in MCP stdio mode (Claude Desktop). Changed to console.error (stderr).
• Fixed: engines.node in package.json updated from >=20.0.0 to >=18.0.0 for broader compatibility.
• Added: MCP stdio safety test suite (mcp-stdio-safety.test.ts) to prevent regressions.

Who is affected

Users running DollhouseMCP on Claude Desktop — the MCP connection would fail immediately after initialization with JSON parse errors in the logs.

Upgrade

npx @dollhousemcp/mcp-server@latest

Or restart Claude Desktop — it will pick up the new version automatically.

Fixes

Follower session forwarding

The --web leader's global 1kb JSON body limit blocked follower sessions (Claude Desktop, Claude Code) from forwarding their logs and metrics. The Logs and Metrics tabs now show data from all connected sessions, not just the leader.

No more CRITICAL SECURITY ALERT from bundled skills (#1725)

The content injection scanner no longer flags DollhouseMCP's own security-related skills (penetration-testing, threat-modeling) as CRITICAL threats. Skills, templates, and agents can legitimately describe attack techniques — they're educational content, not attacks. Prompt injection, actual token exposure, and HTML/XSS scanning remain active for all element types.

Latin + Greek is legitimate (#1722)

Mixed script detection no longer flags Greek characters (α, β, γ, π, Σ, Δ) alongside Latin as a homoglyph attack. Greek letters in math, science, and engineering content are standard notation. Only Latin + Cyrillic remains HIGH severity (true homoglyph risk). Confusable character normalization still runs independently.

Express error handler

Unhandled Express errors now go to the Logs tab via the logger instead of dumping stack traces to the --web terminal.

Full Changelog: https://github.com/DollhouseMCP/mcp-server/compare/v2.0.7...v2.0.8

Clean terminal output for --web mode

Running npx @dollhousemcp/mcp-server --web now shows only the console URL:

  DollhouseMCP Management Console
  http://dollhouse.localhost:3939
  http://127.0.0.1:3939 (fallback)

Previously, startup dumped ~80 lines of internal log output (dotenv injection, persona loading, memory seeding, cache stats, leader election, etc.) that looked like errors to new users. All of that output is still captured and visible in the management console's Logs tab.

Set DOLLHOUSE_DEBUG=1 to restore verbose terminal output for troubleshooting.

Full Changelog: https://github.com/DollhouseMCP/mcp-server/compare/v2.0.6...v2.0.7

What's Changed

Critical fix: Web installer logs & metrics

The standalone web installer (npx @dollhousemcp/mcp-server --web) now correctly starts with log and metrics sinks. Previously, the Logs and Metrics tabs in the management console showed "disconnected" / 404 errors for all users running the guided installer.

Port conflict handling

If port 3939 is already in use by another DollhouseMCP instance, the console gracefully opens the existing instance instead of crashing.

Operation aliases

LLMs can now use natural names like open_console, open_dollhouse_mcp, open_logs, open_metrics, open_setup — 20+ aliases across 5 operations. Aliases are discoverable via introspect.

Console tab deep-linking

open_logs, open_metrics, open_permissions, open_setup operations open the management console directly to the requested tab.

Full changelog

• fix: --web mode logs/metrics sinks + EADDRINUSE handling
• feat: operation alias system (aliases + implicitParams on OperationRoute)
• feat: 4 tab-specific operations with 20+ aliases
• feat: URL hash deep-linking for console tabs (#logs, #metrics, etc.)
• feat: aliases surfaced in introspection responses
• fix: SonarCloud issues (useless spread, globalThis)
• docs: console.log vs logger distinction comment

Full Changelog: https://github.com/DollhouseMCP/mcp-server/compare/v2.0.5...v2.0.6

Hotfix: --web mode UX improvements

Fixes

• Browser auto-open: Security regex now accepts *.localhost subdomains (RFC 6761) — dollhouse.localhost:3939 opens correctly
• Log verbosity: --web mode suppresses debug output in terminal (set DOLLHOUSE_DEBUG=true to override). All logs still captured in memory for web console.
• Follower forwarding: Gives up after 5 failed attempts instead of spamming "Leader unreachable" forever (#1751)
• Leadership takeover: When existing leader (MCP stdio process) isn't running a web console, --web mode probes the leader endpoint and forces a takeover. The old leader naturally becomes a follower.

Full changelog: https://github.com/DollhouseMCP/mcp-server/compare/v2.0.4...v2.0.5

Hotfix: npm package missing web assets

v2.0.3 npm package was missing static web assets (.html, .css, fonts) and seed element files (.yaml), causing --web mode to crash with NotFoundError on fresh installs.

Fixes

• Added dist/web/public/** and dist/seed-elements/** to package.json files field
• Added package inclusion regression tests to prevent this from recurring

Impact

• npx @dollhousemcp/mcp-server@latest --web now works on first run for new users
• Seed memory installation no longer fails silently

Full changelog: https://github.com/DollhouseMCP/mcp-server/compare/v2.0.3...v2.0.4

Setup Tab — Interactive Installer

One command opens a browser-based setup wizard for installing DollhouseMCP on any MCP client:

npx @dollhousemcp/mcp-server@latest --web

Features

• One-click install for 9 platforms: Claude Desktop, Claude Code, Cursor, VS Code, Codex, Gemini CLI, Windsurf, Cline, LM Studio
• Auto-updating vs Pinned version toggle — all config snippets update dynamically
• Installation detection — scans existing client configs, shows green/amber state based on whether current settings match
• Open config file buttons — opens client config in the system default editor
• Version-aware .mcpb download — resolves correct versioned Desktop Extension from GitHub API
• Install verification — confirms config was written after install
• Keyboard navigation — arrow keys, Home, End for platform tabs

Technical

• Bundled install-mcp (MIT, by Dhravya Shah) as runtime dependency
• 7 of 9 platform panels generated from declarative PLATFORMS registry (zero HTML duplication)
• UnicodeValidator.normalize() on all server-side user input
• 171 tests including JSDOM DOM validation of generated panels
• All READMEs and guides updated with interactive setup one-liner

Full changelog: https://github.com/DollhouseMCP/mcp-server/compare/v2.0.2...v2.0.3

Security patch addressing findings from the v2.0.0 code review.

Security Fixes

• Remove raw exec export that bypassed CommandValidator (SEC-02)
• Replace ...process.env with explicit env allowlist in secureExec — stops leaking tokens/secrets to child processes (SEC-03)
• Apply NFC Unicode normalization to web route params before path traversal checks (CQ-05)
• Log startup warning when Gatekeeper permission system is disabled (CQ-06)

Housekeeping

• Replace hardcoded stale version string with dynamic PACKAGE_VERSION
• Remove committed backup file and stale comments
• Move @types/* to devDependencies

Hotfix: Updates the npm package README to show v2 content instead of stale v1 documentation.

No code changes. If you're on 2.0.0, there is no functional reason to upgrade.

DollhouseMCP v2.0.0

The first stable release of DollhouseMCP v2 — open-source AI customization through modular elements.

Install

Claude Code (one command):

claude mcp add -s user dollhousemcp -- npx -y @dollhousemcp/mcp-server

Claude Desktop (one-click): Download the Desktop Extension (.mcpb) from this release and open it.

npm:

npm install @dollhousemcp/mcp-server

See the Quick Start Guide for Cursor, Gemini, Codex, local LLMs, and more.

What's New in v2

MCP-AQL (Agent Query Language)

5 semantic CRUDE endpoints — Create, Read, Update, Delete, Execute — replacing 30+ individual tools with a unified query interface. Reduces token overhead by ~80%.

Gatekeeper Permission System

Per-element security policies that activate and deactivate with elements. Auto-confirm with risk scoring (0–100) reduces session startup from ~50 user approvals to ~15 while preserving safety layers.

6 Element Types

• Personas — AI behavioral profiles with security policies
• Skills — Discrete capabilities
• Templates — Reusable content with variable substitution
• Agents — Goal-oriented multi-step execution with LLM-first architecture
• Memories — Persistent context across sessions
• Ensembles — Bundled element orchestration

Unified Web Console

Built-in dashboard with log viewer, metrics, and permissions tabs. Multi-session support with leader election, session names, and real-time SSE streaming.

Permission Evaluation

evaluate_permission MCP-AQL operation with cross-platform adapter support for Claude Code, Gemini CLI, Cursor, Codex CLI, Windsurf, VS Code Copilot, and JetBrains Junie.

Security

• Unicode normalization (DMCP-SEC-004)
• YAML bomb protection (5:1 amplification threshold)
• Path traversal protection
• Rate limiting on sensitive operations
• 0 findings across 511 scanned files

Testing

9,000+ tests across unit, integration, security, e2e, and calibration suites. Full cross-platform CI (macOS, Linux, Windows) on Node 20.x and 22.x.

Migration from v1

See the v2 Migration Guide.

Key changes:

• Parameter naming standardized to element_name / element_type (snake_case)
• MCP_INTERFACE_MODE env var controls tool exposure (default: MCP-AQL unified endpoints)
• Element filenames use plain {name}.ext (directory provides type context)
• DOLLHOUSE_LOG_SECURITY_RETENTION_DAYS default reduced from 90 to 7 days

Full Changelog

See CHANGELOG.md for the complete history from beta through RC to stable.