Mode Manager MCP

Instructions

Implementation Reference

• src/mode_manager_mcp/tools/instruction_tools.py:66-84 (handler)

  The main handler function for the 'list_instructions' tool. It calls the instruction manager to get the list of instructions and formats them into a human-readable string with details like name, filename, description, size, and content preview.

  def list_instructions() -> str:
      """List all VS Code .instructions.md files in the prompts directory."""
      try:
          instructions = instruction_manager.list_instructions()
          if not instructions:
              return "No VS Code instruction files found in the prompts directory"
          result = f"Found {len(instructions)} VS Code instruction(s):\n\n"
          for instruction in instructions:
              result += f"Name: {instruction['name']}\n"
              result += f"   File: {instruction['filename']}\n"
              if instruction["description"]:
                  result += f"   Description: {instruction['description']}\n"
              result += f"   Size: {instruction['size']} bytes\n"
              if instruction["content_preview"]:
                  result += f"   Preview: {instruction['content_preview'][:100]}...\n"
              result += "\n"
          return result
      except Exception as e:
          return f"Error listing VS Code instructions: {str(e)}"

• src/mode_manager_mcp/tools/instruction_tools.py:52-65 (registration)

  The @app.tool decorator that registers the 'list_instructions' tool with the MCP server, specifying name, description, tags, annotations, and metadata.

  @app.tool(
      name="list_instructions",
      description="List all VS Code .instructions.md files in the prompts directory.",
      tags={"public", "instruction"},
      annotations={
          "idempotentHint": True,
          "readOnlyHint": True,
          "title": "List Instructions",
          "returns": "Returns a formatted list of all instruction files with their names, descriptions, sizes, and content previews. If no instructions are found, returns an informational message.",
      },
      meta={
          "category": "instruction",
      },
  )

• src/mode_manager_mcp/tools/instruction_tools.py:56-61 (schema)

  Schema definition in annotations: confirms no input parameters needed, specifies return type description, and provides hints like idempotent and read-only.

  annotations={
      "idempotentHint": True,
      "readOnlyHint": True,
      "title": "List Instructions",
      "returns": "Returns a formatted list of all instruction files with their names, descriptions, sizes, and content previews. If no instructions are found, returns an informational message.",
  },

• src/mode_manager_mcp/instruction_manager.py:283-327 (helper)

  Supporting utility method in InstructionManager class that scans the prompts directory for all *.instructions.md files, parses frontmatter and content previews, collects metadata, and returns a sorted list of instruction dictionaries used by the tool handler.

  def list_instructions(self, scope: MemoryScope = MemoryScope.user) -> List[Dict[str, Any]]:
      """
      List all .instructions.md files in the prompts directory.
  
      Args:
          scope: "user" or "workspace" to determine which directory to list
  
      Returns:
          List of instruction file information
      """
      instructions: List[Dict[str, Any]] = []
  
      prompts_dir = self._get_prompts_dir(scope)
      if not prompts_dir.exists():
          return instructions
  
      for file_path in prompts_dir.glob(f"*{INSTRUCTION_FILE_EXTENSION}"):
          try:
              frontmatter, content = parse_frontmatter_file(file_path)
  
              # Get preview of content (first 100 chars)
              content_preview = content.strip()[:100] if content.strip() else ""
  
              instruction_info = {
                  "filename": file_path.name,
                  "name": file_path.name.replace(INSTRUCTION_FILE_EXTENSION, ""),
                  "path": str(file_path),
                  "description": frontmatter.get("description", ""),
                  "frontmatter": frontmatter,
                  "content_preview": content_preview,
                  "size": file_path.stat().st_size,
                  "modified": file_path.stat().st_mtime,
                  "scope": scope,
              }
  
              instructions.append(instruction_info)
  
          except Exception as e:
              logger.warning(f"Error reading instruction file {file_path}: {e}")
              continue
  
      # Sort by name
      instructions.sort(key=lambda x: x["name"].lower())
      return instructions