{
  "markdown": "<picture>\n  <source media=\"(prefers-color-scheme: dark)\" srcset=\"./assets/hypertool_darkmode_wordmark_horizontal.png\">\n  <source media=\"(prefers-color-scheme: light)\" srcset=\"./assets/hypertool_lightmode_wordmark_horizontal.png\">\n  <img alt=\"Shows a darkmode hypertool-mcp Logo in light color mode and a white one in dark color mode.\" src=\"./assets/hypertool_lightmode_wordmark_horizontal.png\"  width=\"full\">\n</picture>\n\n<h1 align=\"center\">Give your AI the best tools from all your MCPs 🎯</h1>\n\n[![Version](https://img.shields.io/npm/v/@toolprint/hypertool-mcp)](https://npmjs.com/package/@toolprint/hypertool-mcp)\n[![Downloads](https://img.shields.io/npm/dm/@toolprint/hypertool-mcp)](https://npmjs.com/package/@toolprint/hypertool-mcp)\n[![Discord](https://img.shields.io/discord/1379961140259459113?logo=discord&logoColor=white&label=Discord&color=5865F2)](https://discord.gg/MbvndnJ45W)\n[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)\n[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green)](https://modelcontextprotocol.io)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\n## ⚡ Features\n\n### 🔓 **Break Free from Tool Limits**\n\nConnect unlimited MCP servers. Use 10, 50, or 500+ tools total - your AI only sees what it needs.\n\n### 🎯 **Task-Specific Toolsets**\n\nBuild \"git-essentials\" with 5 tools instead of drowning in 47 Git commands. Switch contexts instantly.\n\n### 🧠 **Smart Tool Descriptions**\n\nEnhance tools with examples and context. Watch your AI pick the right tool 89% more often.\n\n## 🚀 Quick Start\n\n### Step 1: Copy Your Existing Config\n\n```bash\n# In your project directory\ncp .mcp.json .mcp.hypertool.json\n```\n\n### Step 2: Point Your AI to HyperTool\n\nReplace your `.mcp.json` with:\n\n```json\n{\n  \"mcpServers\": {\n    \"hypertool\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@toolprint/hypertool-mcp\", \"mcp\", \"run\", \"--mcp-config\", \".mcp.hypertool.json\"]\n    }\n  }\n}\n```\n\n### Step 3: Create Your First Toolset\n\nRestart your AI and try:\n\n```\nYou: \"Create a toolset called 'coding' with git and docker tools\"\nAI: \"Created 'coding' toolset with 15 focused tools\"\n\nYou: \"Switch to coding toolset\"\nAI: \"Equipped! I now have just the tools needed for development\"\n```\n\n**That's it!** Your AI is now focused and effective. 🎉\n\n💡 **Want automated setup?** Try our interactive `setup` command - see [Advanced Guide](guides/ADVANCED.md#setup-command) for details.\n\n📚 **Configuration Mode:** HyperTool uses a smart Configuration Mode to keep toolset management separate from your operational tools. Learn more in the [Configuration Mode Guide](guides/CONFIGURATION_MODE.md).\n\n## 🎭 Personas: Pre-configured Tool Bundles (NEW!)\n\nDon't want to configure from scratch? Use personas - ready-to-use MCP server bundles with pre-built toolsets.\n\n### What are Personas?\n\nThink of personas as \"app bundles\" for your AI - they come with:\n- ✅ Pre-configured MCP servers\n- ✅ Curated toolsets for specific workflows\n- ✅ Everything you need to get started instantly\n\n### Quick Start with Personas\n\n```bash\n# 1. Clone the persona collection\ngit clone https://github.com/toolprint/awesome-mcp-personas\n\n# 2. Add a persona (e.g., web-dev persona)\nhypertool-mcp persona add awesome-mcp-personas/personas/web-dev\n\n# 3. Run with the persona\nnpx -y @toolprint/hypertool-mcp mcp run --persona web-dev\n```\n\nThat's it! No server configuration needed. The persona brings its own servers and toolsets.\n\n📦 **Browse all available personas**: [awesome-mcp-personas](https://github.com/toolprint/awesome-mcp-personas)\n\n### Available Personas\n\n| Persona | Included Servers | Best For |\n|---------|-----------------|----------|\n| **web-dev** | Git, Docker, Filesystem, Browser, Testing | Full-stack web development |\n| **data-scientist** | Python, Jupyter, Database, Filesystem, Plotting | Data analysis & ML workflows |\n| **devops** | Docker, Kubernetes, AWS, Terraform, Monitoring | Infrastructure & deployment |\n| **content-creator** | Notion, Slack, Grammar, SEO, Social | Writing & content management |\n| **researcher** | Perplexity, Arxiv, Wikipedia, Filesystem | Research & knowledge work |\n\n### Persona vs Standard Mode\n\n```bash\n# Standard Mode (use your existing MCP servers):\nnpx -y @toolprint/hypertool-mcp mcp run --mcp-config .mcp.hypertool.json\n\n# Persona Mode (bundled servers + pre-built toolsets):\nnpx -y @toolprint/hypertool-mcp mcp run --persona web-dev\n\n# Persona Mode with specific toolset:\nnpx -y @toolprint/hypertool-mcp mcp run --persona web-dev --equip-toolset frontend\n```\n\n💡 **Pro tip**: Personas can be mixed with your existing servers! Add `--mcp-config` to include your custom servers alongside the persona's servers.\n\n📚 **Learn more**: See the complete [Personas Guide](guides/PERSONAS.md) for detailed instructions, creating custom personas, and troubleshooting.\n\n## 📊 Context Measurement (NEW!)\n\nSee exactly how much context each tool consumes. Optimize your toolsets with token estimates for every tool.\n\n<div align=\"center\">\n  <img src=\"./assets/toolset_context.png\" alt=\"Toolset Context View\" width=\"700\">\n  <p><em>Active toolset showing token usage per tool</em></p>\n</div>\n\n**Why it matters:**\n- 🎯 **Optimize context usage** - Identify heavyweight tools consuming your context window\n- 📉 **Make informed decisions** - See token costs before adding tools to toolsets\n- 🔍 **Compare alternatives** - Find lighter tools that do the same job\n- 💡 **Budget your context** - Understand exactly what you're exposing to your AI\n\n**How to use:**\n\nAsk your AI to use these MCP tools to see context information:\n- `list-available-tools` - Shows token estimates for all available tools\n- `get-active-toolset` - Shows token usage for your currently equipped toolset\n\nEach tool displays estimated tokens and percentage of total context consumed. Perfect for building lean, efficient toolsets!\n\n## 🎬 Demo\n\n### Hotswap toolsets across 100+ tools\n\n_Targeted toolsets across any number of MCPs. Swap to the best toolset for a goal with a tool call. Dynamic tool registration._\n\n<div align=\"center\">\n  <a href=\"https://www.youtube.com/watch?v=43fkKOBayCg\">\n    <img src=\"./demos/build_dynamic_toolsets_1080p_25fps.gif\" alt=\"HyperTool Demo - Click for full video\" width=\"800\">\n  </a>\n</div>\n\n## 🏗️ How It Works\n\n```\nBefore: Tool Chaos 😵\n┌─────────────┐   ┌─────────────────────────────┐\n│ Claude/     │──▶│ 50+ tools from 8 servers   │\n│ Cursor      │   │ ❌ Wrong picks             │\n│             │   │ ❌ Slow decisions          │\n│             │   │ ❌ Confused context        │\n└─────────────┘   └─────────────────────────────┘\n\nAfter: Expert Mode 🎯\n┌─────────────┐   ┌──────────────┐   ┌─────────────────┐\n│ Claude/     │──▶│ HyperTool    │──▶│ ALL Your Tools  │\n│ Cursor      │   │ (Local)      │   │ (Same servers)  │\n└─────────────┘   └──────────────┘   └─────────────────┘\n                         │\n                         ▼\n                  ┌─────────────────┐\n                  │ Smart Toolsets  │\n                  │ 🔨 coding (5)   │ ← \"I'm coding now\"\n                  │ 📝 writing (3)  │ ← \"I'm writing now\"\n                  │ 📊 analysis (4) │ ← \"I'm analyzing now\"\n                  └─────────────────┘\n                  ✅ Expert picks every time\n```\n\n### What's a \"Toolset\"? Think Playlists for Your AI\n\nJust like Spotify playlists organize your music, toolsets organize your AI tools:\n\n```\nALL YOUR TOOLS (64 total)              YOUR TOOLSETS\n┌────────────────────────────┐         ┌──────────────────┐\n│ 🐳 Docker (19 tools)       │         │ 🔨 \"coding\"      │\n│  • build_image             │   ┌───▶ │  • git.status    │\n│  • create_container        │   │     │  • git.commit    │\n│  • run_container           │   │     │  • docker.build  │\n│  • stop_container          │   │     │  • docker.run    │\n│  • [... 15 more]           │   │     │  • github.pr     │\n├────────────────────────────┤   │     └──────────────────┘\n│ 🔀 Git (12 tools)          │───┤\n│  • status                  │   │     ┌──────────────────┐\n│  • commit                  │   │     │ 📝 \"writing\"     │\n│  • push                    │   └───▶ │  • notion.create │\n│  • [... 9 more]            │         │  • slack.send    │\n├────────────────────────────┤         │  • grammarly.fix │\n│ 📝 Notion (8 tools)        │─────┐   └──────────────────┘\n│ 💬 Slack (6 tools)         │     │\n│ 📊 Linear (10 tools)       │     │   ┌──────────────────┐\n│ 🧪 Testing (9 tools)       │     └─▶ │ 🐛 \"debugging\"   │\n└────────────────────────────┘         │  • logs.search   │\n                                       │  • docker.logs   │\nAI sees ALL 64 tools = confused 😵     │  • traces.view   │\n                                       └──────────────────┘\n\n                                       AI sees 3-5 tools = focused 🎯\n```\n\n## 💼 Real-World Toolsets\n\nCreate focused toolsets for different workflows:\n\n### 🔨 Development Mode\n\n```\n\"deep-coding\": git + docker + filesystem (12 tools)\n→ Everything you need for feature development\n\n\"code-review\": git + github + linear (10 tools)\n→ Review PRs, update tickets, merge with confidence\n\n\"debugging\": logs + docker + traces + alerts (8 tools)\n→ Find and fix issues fast\n```\n\n### 📝 Content Creation\n\n```\n\"writing\": notion + grammarly + slack (6 tools)\n→ Blog posts, docs, and team updates\n\n\"research\": perplexity + notion + filesystem (7 tools)\n→ Deep dives with organized notes\n```\n\n### 🎬 Real Chat Example\n\n```\nYou: \"I need to debug our API\"\nAI: \"I'll switch to the debugging toolset for better focus\"\n[Now has: logs, traces, curl, docker]\n\nYou: \"Actually, let's write the incident report\"\nAI: \"Switching to writing toolset\"\n[Now has: notion, slack, templates]\n```\n\n💡 **Pro tip**: Start with 3-5 tools per toolset. Your AI will thank you!\n\n## 📋 All Features\n\nExplore everything HyperTool can do:\n\n| Feature | Description | Guide |\n|---------|-------------|-------|\n| **🎭 Personas** | Pre-configured MCP server bundles with curated toolsets. Get started instantly with ready-to-use workflows for web-dev, data science, DevOps, and more. | [Personas Guide](guides/PERSONAS.md) |\n| **📁 Server Groups** | Organize MCP servers into logical groups. Launch related servers together, switch between projects, and maintain focused contexts. | [Advanced Guide](guides/ADVANCED.md) |\n| **📊 Context Measurement** | See token estimates for every tool. Optimize your toolsets by understanding exactly how much context each tool consumes. | [Context Measurement](docs/features/context-measurement.md) |\n| **🔧 Configuration Mode** | Smart separation of toolset management from operational tools. Keep your AI focused on work, not configuration. | [Configuration Mode Guide](guides/CONFIGURATION_MODE.md) |\n| **🎯 Dynamic Toolsets** | Build, modify, and switch between toolsets on the fly. Adapt your AI's capabilities to match your current task. | [Examples & Recipes](guides/EXAMPLES.md) |\n| **🧠 Tool Annotations** | Enhance tools with custom descriptions, examples, and context. Improve your AI's tool selection accuracy by 89%. | [Advanced Guide](guides/ADVANCED.md) |\n| **🚀 HTTP Mode** | Run HyperTool as a long-lived HTTP server for persistent connections and faster response times. | [Advanced Guide](guides/ADVANCED.md) |\n| **🔌 Unlimited Servers** | Connect as many MCP servers as you need. Break free from the 100-tool limit without sacrificing performance. | [Quick Start](#-quick-start) |\n\n## ❓ FAQ\n\n### General Questions\n\n**Q: How is this different from just using MCP servers directly?**\nA: HyperTool lets you use unlimited MCP servers without hitting the 100-tool limit, and dynamically switches between focused toolsets for better AI performance.\n\n**Q: What's the difference between Personas and Standard Mode?**\nA: Standard Mode uses your existing MCP server configurations. Personas are pre-packaged bundles that include both MCP servers AND curated toolsets - perfect for getting started quickly or trying new workflows.\n\n**Q: Can I use multiple toolsets at once?**\nA: In stdio mode (default), use `--equip-toolset <name>` when launching. HTTP mode supports one active toolset but you can switch anytime.\n\n**Q: Where are my toolsets and configurations stored?**\nA: Everything is stored locally in `~/.toolprint/hypertool-mcp/`:\n- Personas: `~/.toolprint/hypertool-mcp/personas/`\n- Toolsets: `~/.toolprint/hypertool-mcp/toolsets/`\n- Preferences: `~/.toolprint/hypertool-mcp/config/`\nYou can directly edit these files when HyperTool is not running.\n\n### Setup & Compatibility\n\n**Q: Does this work with Claude Desktop / Cursor / Claude Code?**\nA: Yes! Cursor has full hot-swapping support. Claude Desktop works with restart. Claude Code [hot-swap coming soon](https://github.com/anthropics/claude-code/issues/411).\n\n**Q: What if an MCP server goes down?**\nA: HyperTool monitors health and automatically reconnects when servers come back. Your toolsets stay intact.\n\n**Q: Can I share toolsets with my team?**\nA: Import/export is coming soon! For now, you can copy and share toolset files - they'll work if your team has the same MCP servers configured.\n\n**Q: How accurate are the token estimates in context measurement?**\nA: The estimates use BPE-based approximation for consistent relative comparisons between tools. They're perfect for understanding which tools consume more context, but not exact counts since different LLMs use different tokenizers.\n\n**Q: Does context measurement slow down my toolsets?**\nA: No! Token counts are cached and add less than 10ms overhead. You won't notice any performance impact.\n\n### Technical Questions\n\n**Q: How do I add tools from a new MCP server?**\nA: Just add the server to your `.mcp.hypertool.json` config. It's automatically available for toolsets.\n\n**Q: Can I use this in production?**\nA: Yes! For enterprise support, [contact us](mailto:support@onegrep.dev?subject=HyperTool%20Production%20Use&body=Hi%20team%2C%0A%0AI'm%20interested%20in%20using%20HyperTool%20in%20production.%0A%0ACompany%3A%20%0AUse%20case%3A%20%0AScale%3A%20%0A%0AThanks!).\n\n## 🎮 App Compatibility\n\n**Works with ANY MCP-compatible app!** HyperTool is a standard MCP server, so if your app supports MCP, it supports HyperTool.\n\n### Hot-swap Toolsets Without Restarts\n\n| App | Status | How to Switch Toolsets |\n|-----|---------|------------------------|\n| **Cursor/VSCode** | ✅ Full support | Switch toolsets instantly - no restart needed! |\n| **Claude Code** | ⏳ Coming soon | Use `--equip-toolset <name>` flag ([track progress](https://github.com/anthropics/claude-code/issues/4118)) |\n| **Claude Desktop** | ⏳ In progress | Restart app after switching toolsets |\n\n---\n\n📚 **Learn More**\n\n- 🎭 [Personas Guide](guides/PERSONAS.md) - Complete guide to using and creating personas\n- 🔬 [Research & Performance](guides/RESEARCH.md) - Why focused toolsets work\n- 🚀 [Advanced Features](guides/ADVANCED.md) - Tool annotations, HTTP mode, CLI\n- 🔧 [Troubleshooting](guides/TROUBLESHOOTING.md) - Common issues and solutions\n- 📖 [Examples & Recipes](guides/EXAMPLES.md) - Toolset patterns for every workflow\n\n## 🛠️ Development Setup\n\n### Prerequisites\n\n- Node.js 18+\n- Python 3.8+ (for pre-commit hooks)\n\n### Quick Setup\n\n```bash\n# Clone and install\ngit clone https://github.com/toolprint/hypertool-mcp.git\ncd hypertool-mcp\njust setup-dev  # Installs dependencies and pre-commit hooks\n```\n\n### Pre-commit Hooks\n\nThis project uses pre-commit hooks to ensure code quality:\n\n```bash\n# Install pre-commit hooks (included in setup-dev)\njust setup-pre-commit\n\n# Run hooks manually\njust pre-commit-check        # On staged files\njust pre-commit-check-all    # On all files\n\n# Skip hooks for emergency commits (use sparingly)\nSKIP=eslint,typescript git commit -m \"emergency fix\"\n```\n\n### Available Commands\n\n```bash\njust build          # Build the project\njust test           # Run tests\njust lint           # Run linting\njust format         # Format code\njust typecheck      # Check types\njust pre-publish-checks  # Run all quality checks\n```\n\n### Service command\n\nThe `hypertool-mcp service` subcommand is currently disabled and will exit with a\nnotification when invoked.\n\n## 🤝 Contributing\n\nFound a bug? Have an idea? We'd love your help!\n\n- 🐛 [Report issues](https://github.com/toolprint/hypertool-mcp/issues)\n- 💡 [Share ideas](https://github.com/toolprint/hypertool-mcp/discussions)\n- 🔧 [Submit PRs](https://github.com/toolprint/hypertool-mcp/pulls)\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n---\n\n<div align=\"center\">\n\n**Built by developers who got tired of watching AI pick the wrong tools** 🎯\n\n<a href=\"https://toolprint.ai\">\n  <img src=\"./assets/toolprint.png\" alt=\"Toolprint\" width=\"200\">\n</a>\n\n<p>\n  <strong>Built with ❤️ by <a href=\"https://toolprint.ai\">Toolprint</a></strong><br>\n  <sub>© 2025 OneGrep, Inc.</sub>\n</p>\n\n</div>\n",
  "bytes": 16854,
  "sha": "17b73629f1c7e29e9c60fd0a4dc4bede5fc369db898794ea0ef4ee247c3689f4",
  "repo_slug": "toolprint/hypertool-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_ai_toolprint_hypertool_mcp_b9579d64/readme"
}