hypertool-mcp

# Configuration Mode Feature - Agent Instructions ## Quick Start for Agents You are implementing the **Configuration Mode** feature for hypertool-mcp. This feature separates configuration tools from operational tools to reduce cognitive load on AI assistants. ## Essential Reading Order ### 1. Understand the Project Context 1. **Read First**: `/CLAUDE.md` - Project development standards 2. **Read Second**: `/README.md` - Understand what hypertool-mcp does 3. **Read Third**: `./PRD.md` - Complete feature specification ### 2. Understand Current Architecture Before implementing any task, familiarize yourself with: #### Key Files to Study ```bash # Core server implementation src/server/enhanced.ts # Main server class - you'll modify this src/server/tools/index.ts # Current tool registration src/toolset/manager.ts # ToolsetManager - your parallel component # Tool implementations (for reference) src/server/tools/equip-toolset.ts src/server/tools/build-toolset.ts src/server/tools/list-available-tools.ts # Type definitions src/server/tools/types.ts # ToolModule interface src/types/options.ts # RuntimeOptions interface ``` #### Key Patterns to Understand 1. **Tool Module Pattern**: How tools are defined and registered 2. **Dependency Injection**: How tools receive dependencies 3. **Event System**: How `tools_changed` notifications work 4. **MCP Protocol**: Tool listing and calling conventions ## Task Implementation Guide ### Before Starting Any Task 1. **Check Dependencies**: Review the task's dependencies in `tasks/README.md` 2. **Read Previous Work**: If dependencies exist, understand their implementation 3. **Review Tests**: Look at existing test patterns in the codebase ### For Each Task #### TASK-001: ConfigToolsManager **Start Here** - This is the foundation 1. Study `src/toolset/manager.ts` for the pattern to follow 2. Look at how tool modules are structured in `src/server/tools/` 3. Create parallel structure in `src/config-tools/` #### TASK-002: Mode Switching Tools 1. Reference existing tool implementations in `src/server/tools/` 2. Follow the same module pattern and Zod schema approach 3. These are simple tools with no arguments #### TASK-003: Server Integration **Most Complex Task** - Requires careful modification 1. Study entire `src/server/enhanced.ts` file first 2. Understand the current `listTools()` and `callTool()` flow 3. Add mode logic without breaking existing functionality #### TASK-004: Auto-Exit Triggers 1. Modify existing tool handlers carefully 2. Ensure backward compatibility 3. Only trigger on successful operations #### TASK-005: Feature Flag 1. Check how other runtime options are handled 2. Ensure flag properly disables all new behavior 3. Default should be new behavior (enabled) #### TASK-006: Testing 1. Follow existing test patterns in the codebase 2. Mock dependencies appropriately 3. Test both success and failure paths #### TASK-007: Documentation 1. Match the style of existing documentation 2. Include practical examples 3. Explain both the "what" and "why" ## Common Pitfalls to Avoid ### ❌ Don't Break Existing Functionality - Always ensure backward compatibility - Test with existing toolsets - Verify `tools_changed` notifications still work ### ❌ Don't Forget Edge Cases - What if no MCP servers are connected? - What if toolset operations fail? - What if mode switching is called in wrong mode? ### ❌ Don't Skip Tests - Write tests as you implement - Test error conditions - Test with feature flag both on and off ## Implementation Checklist Before marking any task complete: - [ ] Code follows TypeScript best practices - [ ] All tests pass (`npm test`) - [ ] Linting passes (`npm run lint`) - [ ] Feature works with flag enabled AND disabled - [ ] No breaking changes to existing functionality - [ ] Code is documented with JSDoc comments - [ ] Integration tested with real MCP client ## Testing Your Implementation ### Manual Testing ```bash # Build the project npm run build # Run with configuration mode (default) npm start -- --mcp-config .mcp.json # Run with configuration mode disabled npm start -- --mcp-config .mcp.json --disable-configuration-mode # Test with stdio transport echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | npm start ``` ### Automated Testing ```bash # Run all tests npm test # Run specific test file npm test -- src/config-tools/manager.test.ts # Run with coverage npm test -- --coverage ``` ## Getting Help ### Key Concepts - **MCP (Model Context Protocol)**: The protocol for tool communication - **Tool Module**: Self-contained tool definition with schema and handler - **Toolset**: A saved configuration of selected tools - **Discovery Engine**: Finds tools from downstream MCP servers ### Reference Implementation The closest reference is the ToolsetManager. Your ConfigToolsManager should follow a similar pattern but for configuration tools instead of discovered tools. ### Architecture Decision The separation of concerns is key: - **ToolsetManager**: Manages discovered tools from downstream servers - **ConfigToolsManager**: Manages built-in configuration tools - **EnhancedMCPServer**: Routes between them based on mode ## Success Criteria Your implementation is successful when: 1. Server starts in config mode when no toolset is equipped 2. Mode switching works smoothly via tool calls 3. Auto-exit triggers work on toolset equip 4. Feature flag properly disables the feature 5. All existing tests still pass 6. New tests provide >80% coverage Remember: The goal is to reduce cognitive load on AI assistants by showing only relevant tools at the right time.