Create Instruction

Instructions

Implementation Reference

• src/mode_manager_mcp/instruction_manager.py:400-434 (handler)

  The actual implementation of create_instruction in InstructionManager class. Handles ensuring the .instructions.md extension, creates frontmatter with 'applyTo' and 'description' fields, and writes the file using write_frontmatter_file.

  def create_instruction(self, instruction_name: str, description: str, content: str) -> bool:
      """
      Create a new instruction file.
  
      Args:
          instruction_name: Name for the new .instructions.md file
          description: Description of the instruction
          content: Instruction content
  
      Returns:
          True if successful
  
      Raises:
          FileOperationError: If file cannot be created
      """
  
      # Ensure filename has correct extension
      instruction_name = self._ensure_instruction_extension(instruction_name)
  
      file_path = self.prompts_dir / instruction_name
  
      if file_path.exists():
          raise FileOperationError(f"Instruction file already exists: {instruction_name}")
  
      # Create frontmatter with applyTo field so instructions are actually applied
      frontmatter: Dict[str, Any] = {"applyTo": "**", "description": description}
  
      try:
          success = write_frontmatter_file(file_path, frontmatter, content, create_backup=False)
          if success:
              logger.info(f"Created instruction file: {instruction_name}")
          return success
  
      except Exception as e:
          raise FileOperationError(f"Error creating instruction file {instruction_name}: {e}")

• src/mode_manager_mcp/tools/instruction_tools.py:35-50 (handler)

  The MCP tool handler function for 'create_instruction'. Decorated with @app.tool(name='create_instruction'), it checks read-only mode, delegates to instruction_manager.create_instruction(), and returns a success/error message.

  def create_instruction(
      instruction_name: Annotated[str, "The name for the new instruction (with or without extension)"],
      description: Annotated[str, "A brief description of what this instruction does"],
      content: Annotated[str, "The main content/instructions in markdown format"],
  ) -> str:
      """Create a new VS Code .instructions.md file with the specified description and content."""
      if read_only:
          return "Error: Server is running in read-only mode"
      try:
          success = instruction_manager.create_instruction(instruction_name, description, content)
          if success:
              return f"Successfully created VS Code instruction: {instruction_name}"
          else:
              return f"Failed to create VS Code instruction: {instruction_name}"
      except Exception as e:
          return f"Error creating VS Code instruction '{instruction_name}': {str(e)}"

• src/mode_manager_mcp/tools/instruction_tools.py:16-34 (registration)

  The tool registration decorator with name='create_instruction', description, tags, annotations (parameters & returns), and meta data. Registers the tool on the MCP app instance.

  @app.tool(
      name="create_instruction",
      description="Create a new VS Code .instructions.md file with the specified description and content.",
      tags={"public", "instruction"},
      annotations={
          "idempotentHint": False,
          "readOnlyHint": False,
          "title": "Create Instruction",
          "parameters": {
              "instruction_name": "The name for the new instruction. If .instructions.md extension is not provided, it will be added automatically.",
              "description": "A brief description of what this instruction does. This will be stored in the frontmatter.",
              "content": "The main content/instructions in markdown format.",
          },
          "returns": "Returns a success message if the instruction was created, or an error message if the operation failed.",
      },
      meta={
          "category": "instruction",
      },
  )

• src/mode_manager_mcp/tools/__init__.py:14-18 (registration)

  The register_all_tools() function which calls register_instruction_tools() to register all instruction tools including create_instruction.

  def register_all_tools() -> None:
      """Register all tools with the server."""
      register_instruction_tools()
      register_memory_tools()
      register_remember_tools()