Skip to content

Release v0.0.40

Choose a tag to compare

View all tags
@github-actions github-actions released this 08 Sep 14:48
v0.0.40
e8a3dfd
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

🎭 Introducing Persona Content Packs

Major Feature Release: This version introduces the Persona Content Pack System - a comprehensive framework for bundling, distributing, and managing collections of MCP servers and toolsets as reusable packages.

A complete set of public, MIT-licensed content packs can be found at https://github.com/toolprint/awesome-mcp-personas.

BREAKING CHANGE. The new way to run hypertool is using npx -y @toolprint/hypertool-mcp mcp run <args>. Run --help for more details.

What is a Persona?

A persona is a pre-configured bundle of MCP servers and curated toolsets that can be instantly activated to give AI assistants specialized capabilities for specific workflows. Think of them as "app bundles" or "skill packs" that transform your AI assistant into a domain expert with one command.

Example Personas

  • web-researcher - Web scraping tools (Playwright), search engines (Exa), and content extraction (Readability) for comprehensive online research.
  • full-stack-dev - Git operations, Docker management, database tools, and code analysis for complete development workflows.
  • data-scientist - Jupyter notebooks, data processing tools, visualization libraries, and statistical analysis capabilities
  • content-creator - SEO tools, grammar checkers, image generation, and social media APIs for content production
  • devops-engineer - Kubernetes, Terraform, monitoring tools, and CI/CD integrations for infrastructure management
  • ui-designer - Figma API, screenshot tools, color palette generators, and accessibility checkers for design workflows

See all the personas here:
https://github.com/toolprint/awesome-mcp-personas?tab=readme-ov-file#-personas-catalog

Each persona can contain multiple toolsets that can be switched on-the-fly (e.g., the web-researcher persona might have separate toolsets for "scraping", "analysis", and "reporting").

✨ Highlights

Persona System

  • Content Pack Management: Bundle MCP server configurations, toolsets, and related assets into distributable "personas"
  • Simple 3-Step Setup: Clone personas → Add them → Activate and use
  • Hot-Swappable Toolsets: Switch between different tool configurations within personas on the fly
  • Smart Discovery: Automatic detection and validation of persona packages
  • Environment Variable Detection: Automatic detection of required environment variables in MCP configurations

Enhanced Architecture

  • IToolsetDelegate Pattern: Unified interface for toolset operations across persona and regular modes
  • Intelligent Routing: Context-aware routing between PersonaManager and ToolsetManager
  • Two-Phase Boot Sequence: Optimized startup process for persona activation with MCP server integration

🚀 New Features

Persona CLI Commands

# First-time setup (3 steps)
git clone https://github.com/toolprint/awesome-mcp-personas
hypertool persona add awesome-mcp-personas/personas/<persona-name>
hypertool persona activate <persona-name>

# Management commands
hypertool persona list       # See all available personas
hypertool persona inspect    # View detailed persona info
hypertool persona status     # Check active persona
hypertool persona deactivate # Deactivate current persona

Persona Configuration (persona.yaml)

name: "web-research"
description: "Web scraping and research tools"

toolsets:
  - name: "scraping"
    toolIds:
      - "playwright.navigate"
      - "playwright.screenshot"
      - "readability.extract"
  
  - name: "research"
    toolIds:
      - "exa.search"
      - "context7.get-docs"

defaultToolset: "scraping"

metadata:
  author: "Your Name"
  version: "1.0.0"
  tags: ["web", "research", "automation"]

MCP Tools for Persona Management

  • list-personas: Discover available personas
  • activate-persona: Activate a persona with optional toolset
  • deactivate-persona: Deactivate current persona
  • get-active-persona: Query active persona state
  • validate-persona: Comprehensive validation of persona configurations

🏗️ Architecture Improvements

Core Components

  • PersonaManager: Central orchestrator for persona lifecycle
  • PersonaDiscovery: File system scanning and persona detection
  • PersonaLoader: Configuration loading and parsing
  • PersonaValidator: Multi-layer validation (YAML, schema, business rules, tools)
  • PersonaCache: High-performance caching with TTL and LRU eviction
  • PersonaToolsetBridge: Seamless conversion between persona and regular toolset formats
  • PersonaMcpIntegration: MCP server configuration merging and management

Unified Toolset Management

  • IToolsetDelegate Interface: Common interface for both PersonaManager and ToolsetManager
  • ConfigToolsManager: Intelligent routing based on persona activation state
  • Context-Aware Tools: Same commands work differently in persona vs standard mode

📊 Performance Enhancements

  • Optimized Discovery: Parallel scanning with caching (TTL: 5 minutes)
  • Two-Phase Validation: Deferred tool validation until after MCP server startup
  • Memory Management: LRU cache eviction with configurable limits
  • Background Cleanup: Automatic cache invalidation on file changes

🔧 Developer Experience

Testing Infrastructure

  • Comprehensive Test Suite: 1000+ tests covering all persona components
  • Test Fixtures: Ready-to-use persona examples for development
  • Integration Tests: Full lifecycle testing from discovery to activation
  • Performance Benchmarks: Memory usage and speed validation

Debugging & Development

# Development workflow
just persona-setup-real      # Set up test personas
just persona-debug           # Comprehensive debugging
just persona-validate-all    # Validate all personas
just persona-dev-workflow    # Complete dev cycle

🐛 Bug Fixes

  • Fixed tool ID validation to support compound names (e.g., docker.compose.up)
  • Resolved activation timing issues with MCP server startup
  • Fixed CLI commands hanging due to background timers
  • Corrected validation inconsistencies between discovery and activation
  • Fixed "No active persona" warning during successful activation

📚 Documentation

New Guides

  • Persona System Guide: Complete documentation in guides/PERSONAS.md
  • Architecture Documentation: Detailed design in docs/design/persona-content-pack.md
  • Integration Guide: Server tools architecture in src/server/tools/CLAUDE.md

Configuration

  • Persona Directory: Configurable via HYPERTOOL_PERSONA_DIR environment variable
  • State Persistence: Automatic state restoration across sessions
  • Conflict Resolution: Smart merging strategies for MCP configurations

🔄 Migration Notes

For Existing Users

  • No breaking changes to existing functionality
  • Standard mode (--mcp-config) continues to work as before
  • Configuration tools menu remains disabled by default (HYPERTOOL_ENABLE_CONFIG_TOOLS_MENU=false)

For Persona Users

  1. Set up persona directory: export HYPERTOOL_PERSONA_DIR=~/.toolprint/hypertool-mcp/personas
  2. Clone persona collections: git clone https://github.com/toolprint/awesome-mcp-personas
  3. Add and activate personas using the new CLI commands

🙏 Acknowledgments

This major release was developed with significant contributions from Claude AI, implementing a comprehensive 18-task roadmap for the persona content pack system.

📈 Statistics

  • Files Changed: 139
  • Insertions: 34,694
  • Deletions: 782
  • New Tests: 1,000+
  • New Components: 20+

🔗 Links

Full Changelog: v0.0.39...v0.0.40

Installation

# Install latest stable version
npm install -g @toolprint/hypertool-mcp
npx @toolprint/hypertool-mcp

# Or install specific version
npm install -g @toolprint/hypertool-mcp@0.0.40
Assets 2
Loading