mcp-wcgw

Instructions

Implementation Reference

• src/wcgw/client/tools.py:1083-1114 (handler)

  Handler logic for ContextSave tool within the get_tool_output dispatcher function. Globs and reads relevant files, saves memory using save_memory helper, and returns the path to the saved context file.

  elif isinstance(arg, ContextSave):
      context.console.print("Calling task memory tool")
      relevant_files = []
      warnings = ""
      # Expand user in project root path
      arg.project_root_path = os.path.expanduser(arg.project_root_path)
      for fglob in arg.relevant_file_globs:
          # Expand user in glob pattern before checking if it's absolute
          fglob = expand_user(fglob)
          # If not absolute after expansion, join with project root path
          if not os.path.isabs(fglob) and arg.project_root_path:
              fglob = os.path.join(arg.project_root_path, fglob)
          globs = glob.glob(fglob, recursive=True)
          relevant_files.extend(globs[:1000])
          if not globs:
              warnings += f"Warning: No files found for the glob: {fglob}\n"
      relevant_files_data, _, _ = read_files(
          relevant_files[:10_000], None, None, context
      )
      save_path = save_memory(
          arg, relevant_files_data, context.bash_state.serialize()
      )
      if not relevant_files and arg.relevant_file_globs:
          output_ = f'Error: No files found for the given globs. Context file successfully saved at "{save_path}", but please fix the error.'
      elif warnings:
          output_ = warnings + "\nContext file successfully saved at " + save_path
      else:
          output_ = save_path
      # Try to open the saved file
      try_open_file(save_path)
      output = output_, 0.0
  else:

• src/wcgw/types_.py:304-309 (schema)

  Pydantic BaseModel defining the input schema for ContextSave tool: id, project_root_path, description, relevant_file_globs.

  class ContextSave(BaseModel):
      id: str
      project_root_path: str
      description: str
      relevant_file_globs: list[str]

• src/wcgw/client/tool_prompts.py:89-97 (registration)

  MCP Tool registration for ContextSave, including schema reference, name, description, and annotations.

      Tool(
          inputSchema=remove_titles_from_schema(ContextSave.model_json_schema()),
          name="ContextSave",
          description="""
  Saves provided description and file contents of all the relevant file paths or globs in a single text file.
  - Provide random 3 word unique id or whatever user provided.
  - Leave project path as empty string if no project path""",
          annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=False),
      ),

• src/wcgw/client/memory.py:34-60 (helper)

  Helper function save_memory that formats and persists the task context to a file using the ContextSave model data and relevant files content.

  def save_memory(
      task_memory: ContextSave,
      relevant_files: str,
      bash_state_dict: Optional[dict[str, Any]] = None,
  ) -> str:
      app_dir = get_app_dir_xdg()
      memory_dir = os.path.join(app_dir, "memory")
      os.makedirs(memory_dir, exist_ok=True)
  
      task_id = task_memory.id
      if not task_id:
          raise Exception("Task id can not be empty")
      memory_data = format_memory(task_memory, relevant_files)
  
      memory_file_full = os.path.join(memory_dir, f"{task_id}.txt")
  
      with open(memory_file_full, "w") as f:
          f.write(memory_data)
  
      # Save bash state if provided
      if bash_state_dict is not None:
          state_file = os.path.join(memory_dir, f"{task_id}_bash_state.json")
          with open(state_file, "w") as f:
              json.dump(bash_state_dict, f, indent=2)
  
      return memory_file_full

• src/wcgw/client/memory.py:15-32 (helper)

  Helper function format_memory that structures the task description, relevant globs, and file contents into a memory string.

  def format_memory(task_memory: ContextSave, relevant_files: str) -> str:
      memory_data = ""
      if task_memory.project_root_path:
          memory_data += (
              f"# PROJECT ROOT = {shlex.quote(task_memory.project_root_path)}\n"
          )
      memory_data += task_memory.description
  
      memory_data += (
          "\n\n"
          + "# Relevant file paths\n"
          + ", ".join(map(shlex.quote, task_memory.relevant_file_globs))
      )
  
      memory_data += "\n\n# Relevant Files:\n" + relevant_files
  
      return memory_data