hypertool-mcp

# TASK-002: Implement Mode Switching Tools ## Task Overview **Priority**: P0 (Blocking) **Estimated Effort**: 1 day **Dependencies**: TASK-001 **Status**: Not Started ## Description Create the mode switching tools (`enter-configuration-mode` and `exit-configuration-mode`) that allow transitioning between Normal and Configuration modes. ## Acceptance Criteria - [ ] `enter-configuration-mode` tool module created - [ ] `exit-configuration-mode` tool module created - [ ] Tools properly registered in ConfigToolsManager - [ ] Tools trigger mode state changes in server - [ ] Tools trigger `tools_changed` notifications - [ ] Unit tests with >80% coverage ## Technical Details ### Implementation Steps 1. Create tool module for `enter-configuration-mode` in `src/server/tools/common/` 2. Create tool module for `exit-configuration-mode` in `src/server/tools/config-tools/tools/` 3. Define input/output schemas using Zod for both tools 4. Implement tool handlers that call the `onModeChangeRequest` callback 5. Add `exit-configuration-mode` to ConfigToolsManager registration 6. Server will manage `enter-configuration-mode` directly and add it to tool list in normal mode 7. Update ToolModuleFactory interface to support optional callback parameter ### Files to Create - `src/server/tools/common/enter-configuration-mode.ts` (managed by server, not ConfigToolsManager) - `src/server/tools/config-tools/tools/exit-configuration-mode.ts` - `src/server/tools/config-tools/tools/mode-switching.test.ts` ### Tool Specifications #### Selected Names: `enter-configuration-mode` / `exit-configuration-mode` These tools should leverage proper MCP annotations for enhanced LLM understanding: ```typescript // enter-configuration-mode tool definition export const enterConfigurationModeDefinition: Tool = { name: "enter-configuration-mode", description: "Switch the server to configuration mode for managing tools and toolsets. In this mode, you can access: list-available-tools (browse all discovered tools), build-toolset (create custom tool collections), list-saved-toolsets (view saved configurations), equip-toolset (activate a toolset), delete-toolset (remove configurations), get-active-toolset (check current status), and add-tool-annotation (add context to tools). Operational tools will be hidden while in configuration mode. Use this when you need to organize, create, or modify tool configurations.", inputSchema: { type: "object" as const, properties: {}, additionalProperties: false }, // MCP annotations provide hints to LLMs about tool behavior annotations: { title: "Enter Configuration Mode", readOnlyHint: false, // This changes server state destructiveHint: false, // Not destructive, just changes mode idempotentHint: true, // Calling multiple times has same effect openWorldHint: false, // Does not interact with external systems } } // exit-configuration-mode tool definition export const exitConfigurationModeDefinition: Tool = { name: "exit-configuration-mode", description: "Leave configuration mode and return to normal operational mode. This will hide configuration tools and restore access to your equipped toolset's tools (or show only navigation tools if no toolset is equipped). The server will automatically exit configuration mode when you successfully equip a toolset. Use this when you're done with configuration tasks and ready to use your tools.", inputSchema: { type: "object" as const, properties: {}, additionalProperties: false }, // MCP annotations provide hints to LLMs about tool behavior annotations: { title: "Exit Configuration Mode", readOnlyHint: false, // This changes server state destructiveHint: false, // Not destructive, just changes mode idempotentHint: true, // Calling multiple times has same effect openWorldHint: false, // Does not interact with external systems } } // Handler implementation example export const createExitConfigurationModeModule: ToolModuleFactory = ( deps, onModeChangeRequest?: () => void ): ToolModule => { return { toolName: "exit-configuration-mode", definition: exitConfigurationModeDefinition, handler: async () => { // Call the callback to request mode change if (onModeChangeRequest) { onModeChangeRequest(); return { content: [{ type: "text", text: "Exiting configuration mode..." }] }; } throw new Error("Mode change callback not configured"); } }; }; ``` ### Annotations for Other Configuration Tools The existing configuration tools should also have appropriate MCP annotations to help LLMs understand their behavior: ```typescript // list-available-tools - already has annotations (see src/server/tools/list-available-tools.ts) annotations: { title: "List Available Tools", readOnlyHint: true, // Just reads, doesn't modify destructiveHint: false, idempotentHint: true, openWorldHint: false, } // build-toolset - should have annotations like: annotations: { title: "Build Toolset", readOnlyHint: false, // Creates new toolset destructiveHint: false, // Not destructive, creates new resource idempotentHint: false, // Each call creates a new toolset openWorldHint: false, // Works with local configuration } // equip-toolset - should have annotations like: annotations: { title: "Equip Toolset", readOnlyHint: false, // Changes active toolset destructiveHint: false, // Not destructive, just switches idempotentHint: true, // Equipping same toolset multiple times is same openWorldHint: false, // Local configuration change } // delete-toolset - should have annotations like: annotations: { title: "Delete Toolset", readOnlyHint: false, // Modifies saved configurations destructiveHint: true, // DESTRUCTIVE - permanently removes toolset idempotentHint: true, // Deleting already-deleted toolset fails safely openWorldHint: false, // Local configuration change } ``` ### MCP Annotation Guidelines The MCP annotations provide semantic hints to help LLMs understand tool behavior: - **title**: Human-readable name for the tool - **readOnlyHint**: `true` if the tool only reads data without making changes - **destructiveHint**: `true` if the tool destroys data or resources permanently - **idempotentHint**: `true` if calling the tool multiple times with same args has same effect as calling once - **openWorldHint**: `true` if the tool interacts with external systems beyond the MCP server These hints help LLMs: 1. Understand which tools are safe to call repeatedly 2. Be cautious with destructive operations 3. Know which tools might have external side effects 4. Optimize tool usage patterns ## Testing Requirements - Test mode switching logic - Test notification triggering - Test error handling for invalid mode transitions - Integration tests with server ## Notes These tools should only be available in the appropriate mode (enter in Normal, exit in Configuration).