Mode Manager MCP

Instructions

Implementation Reference

• src/mode_manager_mcp/tools/instruction_tools.py:135-150 (handler)

  The MCP tool handler function for 'update_instruction'. Checks read-only mode, calls InstructionManager.update_instruction with the provided content (description param is accepted but ignored), and returns success/error message.

  def update_instruction(
      instruction_name: Annotated[str, "The name of the instruction to update (with or without extension)"],
      description: Annotated[Optional[str], "Optional new description for the instruction"] = None,
      content: Annotated[Optional[str], "Optional new content for the instruction"] = None,
  ) -> str:
      """Update an existing VS Code .instructions.md file with new description or content."""
      if read_only:
          return "Error: Server is running in read-only mode"
      try:
          success = instruction_manager.update_instruction(instruction_name, content=content)
          if success:
              return f"Successfully updated VS Code instruction: {instruction_name}"
          else:
              return f"Failed to update VS Code instruction: {instruction_name}"
      except Exception as e:
          return f"Error updating VS Code instruction '{instruction_name}': {str(e)}"

• src/mode_manager_mcp/tools/instruction_tools.py:116-134 (registration)

  Registers the 'update_instruction' MCP tool with the server, including schema definition for parameters (instruction_name, optional description, optional content) and returns description.

  @app.tool(
      name="update_instruction",
      description="Update an existing VS Code .instructions.md file with new description or content.",
      tags={"public", "instruction"},
      annotations={
          "idempotentHint": False,
          "readOnlyHint": False,
          "title": "Update Instruction",
          "parameters": {
              "instruction_name": "The name of the instruction to update. If .instructions.md extension is not provided, it will be added automatically.",
              "description": "Optional new description for the instruction. If not provided, the existing description will be kept.",
              "content": "Optional new content for the instruction. If not provided, the existing content will be kept.",
          },
          "returns": "Returns a success message if the instruction was updated, or an error message if the operation failed.",
      },
      meta={
          "category": "instruction",
      },
  )

• src/mode_manager_mcp/tools/instruction_tools.py:120-130 (schema)

  Input/output schema definition for the 'update_instruction' tool via annotations: parameters for instruction_name (str), optional description (str), optional content (str); returns success/error str.

  annotations={
      "idempotentHint": False,
      "readOnlyHint": False,
      "title": "Update Instruction",
      "parameters": {
          "instruction_name": "The name of the instruction to update. If .instructions.md extension is not provided, it will be added automatically.",
          "description": "Optional new description for the instruction. If not provided, the existing description will be kept.",
          "content": "Optional new content for the instruction. If not provided, the existing content will be kept.",
      },
      "returns": "Returns a success message if the instruction was updated, or an error message if the operation failed.",
  },

• src/mode_manager_mcp/instruction_manager.py:437-490 (helper)

  Core helper method in InstructionManager that updates the .instructions.md file: ensures extension, reads current frontmatter/content, merges updates (note: tool only passes content, keeps frontmatter), rewrites file with backup.

  def update_instruction(
      self,
      instruction_name: str,
      frontmatter: Optional[Dict[str, Any]] = None,
      content: Optional[str] = None,
  ) -> bool:
      """
      Replace the content and/or frontmatter of an instruction file.
  
      This method is for full rewrites. To append to a section, use append_to_section.
  
      Args:
          instruction_name: Name of the .instructions.md file
          frontmatter: New frontmatter (optional)
          content: New content (optional, replaces all markdown content)
  
      Returns:
          True if successful
  
      Raises:
          FileOperationError: If file cannot be updated
      """
      # Ensure filename has correct extension
      instruction_name = self._ensure_instruction_extension(instruction_name)
  
      file_path = self.prompts_dir / instruction_name
  
      if not file_path.exists():
          raise FileOperationError(f"Instruction file not found: {instruction_name}")
  
      try:
          # Read current content
          current_frontmatter, current_content = parse_frontmatter_file(file_path)
  
          if content is not None and frontmatter is None:
              # We check if the content is actually including yaml
              frontmatter, content = parse_frontmatter(content)
  
          # Use provided values or keep current ones
          new_frontmatter = frontmatter if frontmatter is not None else current_frontmatter
          # If new content is provided, replace all markdown content
          if content is not None:
              new_content = content
          else:
              new_content = current_content
  
          success = write_frontmatter_file(file_path, new_frontmatter, new_content, create_backup=True)
          if success:
              logger.info(f"Updated instruction file with backup: {instruction_name}")
          return success
  
      except Exception as e:
          raise FileOperationError(f"Error updating instruction file {instruction_name}: {e}")