Charles MCP Server

Instructions

Implementation Reference

• charles_mcp/tools/history.py:242-246 (handler)

  The MCP tool definition for 'list_recordings', which calls the service layer.

  @mcp.tool()
  async def list_recordings(ctx: ToolContext) -> RecordingListResult:
      """List saved recording files using an explicit history-oriented tool name."""
      deps = get_tool_dependencies(ctx)
      return deps.history_service.list_recordings_result()

• charles_mcp/services/history_capture.py:125-142 (handler)

  The core logic to list recording files in the history service.

  def list_recordings(self) -> list[dict]:
      files = list_files_with_extension(self.config.package_dir, ".chlsj")
      result: list[dict] = []
      for filename in sorted(files):
          filepath = os.path.join(self.config.package_dir, filename)
          try:
              stat = os.stat(filepath)
              result.append(
                  {
                      "filename": filename,
                      "size": format_bytes(stat.st_size),
                      "size_bytes": stat.st_size,
                      "path": filepath,
                  }
              )
          except OSError:
              result.append({"filename": filename, "error": "unable_to_read_file_metadata"})
      return result

• charles_mcp/services/history_capture.py:144-159 (handler)

  A wrapper method in the history service that prepares the result object for the MCP tool.

  def list_recordings_result(self) -> RecordingListResult:
      items: list[RecordingFileInfo] = []
      warnings: list[str] = []
      for record in self.list_recordings():
          if "error" in record:
              continue
          items.append(RecordingFileInfo(**record))
  
      if not items:
          warnings.append("no_saved_recordings")
  
      return RecordingListResult(
          items=items,
          total_items=len(items),
          warnings=warnings,
      )